Category: Next.js, React and TypeScript

Next.js: diagnostics of invalid imports between Client and Server Components

Read this guide in Polish

In Next.js from component separation to server and client (RSC/CSR) incorrect or mixed imports are a common cause of errors when building applications and when launching in the production environment. This document describes the differential diagnostics, specific tests and sequence of steps to find and repair situations when a component marked as server imports a module using the state or effects of the browser, or when client component depends on code requiring node-only API. I focus on the real conditions that cause: "use client must be the first direct" compilation errors, execution time errors with hydration or unexpected behavior in production (e.g. different data rendered in dev and prod). I do not assume that the cause is a single file — I will show typical source variants, specific commands and test conditions. The proposed steps are executable in Next.js repository (versions 13+ from RSC) and do not require external tools outside the node, e.g./yarn and Next.js commands. I do not create fictitious patches or promise a solution in one step — I indicate repetitive tests and conditions that clearly identify the source of the import conflict and their repair.

How to Recognize Cause

Symptoms 1: compilation error during build or in dev console: "'use client' must be the first directive" or stacktrake indicating cyclic import. This message appears when the client file does not have 'use client' on the first line or the imported dependency is server-only. Check the first 3 lines of each component to confirm no additional comments before 'use client'.

Symptoms 2: runtime hydration mismatch, no useEffect effects or window is not defined in production. This suggests that the server component imports a module trying to use the browser API. Check the imports from libraries using DOM (e.g. UI/icon libraries) and perform a tree-shaking/webpack relationship analysis.

Symptoms 3: various dev vs production behavior: works locally, but build on Vercel/CI returns an error. This often results from differences in Node versions, different compiler flags or from the fact that the dev server is more tolerant. Make sure you have the Node version and run next build from --profile or --debug.

Step by step solution

1. Step 1 — Locate: Start next build and copy full stacktrake. If a message about 'use client' or 'window is not defined' appears, note the file indicated in the path. Use grep (e.g. rg "use client") on /app and /components directory to find all client components.

2 . Step 2 — Verification of direct imports: for the selected file open each import and check whether the imported path contains 'use client' or uses React hooks/effects. If the import is directly to the library, check the documentation for server rendering.

3 . Step 3 — Dependency tree analysis: run e.g. ls <packaget> or package graph display tool (e.g. example-why) to find indirect dependencies that can enter the browser code into the server component. Identify the modules that export DOM-dependent code.

4 . Step 4 — Isolation: temporarily replace suspect import stub (a simple component without effects) and repeat next build. If build passes, you know the problem comes from this dependency. Restore the original and continue to isolate at a further level of dependence.

5 . Step 5 — Repair: If this server component import client-only code, move import to client component or wrap the module with dynamic import from {sssr: false } for a part requiring a browser. Alternatively mark the 'use client' client file and make sure it is only used in a place that accepts client components.

6 . Step 6 — check configuration: compare Node version and next.config.js settings (Experimental appDir, transpilePackages, etc.) between local environment and CI. Enter changes to standardize the environment and repeat next build.

How to see if the problem is gone

Test 1 — build: run clean build (rm -rf .next &&egm run build) and check for no compilation errors. The reason is to confirm that no server component import client-only dependencies. Note the time of compilation and the lack of new Warnings.

Test 2 — locally run production: run NODE ENV=production egm start and visit the path that previously caused the error. Check the browser console for hydration mismatch and no window is not defined.

Test 3 — Dependency control: run nm ls < suspect-package> and confirm that it does not occur in the server component import path. If present, repeat insulation and repair for intermediate modules.

What to do

Do not mark the 'use client' file as a default solution without checking the impact: excess client components loses RSC benefit and can hide the actual server dependency.

Don't just rely on dev server: dev can mask errors by refreshing and tolerating imports; always test clean build and start in production mode.

Avoid introducing global polyfills for window/DOM in the server; this hides the problem and can lead to unstable behaviour in the production environment.