Next.js Is Confusing - Is This Server or Client Code?

Next.js: Server vs Client code — Key concepts, problems, and fixes

High-level problem

Next.js blurs server/client boundaries. Developers frequently accidentally import server-only code into client-side code, causing confusing runtime errors (often reported as “missing environment variable” or obscure bundler/syntax errors).

Core issue: any file imported into a client component gets shipped to and run in the browser. Browser code can’t access server-only resources (env vars, DB connections, file system, etc.), so importing server code into client code breaks at runtime or during bundling.

---

Concrete scenarios and fixes

1) Server component imported into a client component

• Symptom:
  • Environment-variable or DB-adapter errors in the browser even though env vars exist on the server.
• Cause:
  • A client component imported a server component, so server code is now treated as client code.
• Fixes:
  • Do not import server components into client components.
  • If you need to render server-rendered UI inside client UI, keep the server component in the parent server component and pass its rendered output as children (ReactNode). This preserves server-only execution for that component.

2) Server actions imported into client components

• Symptom:
  • Weird runtime/webpack/syntax errors, or env-var-like errors before the action even runs.
• Causes:
  • Importing a server action into client code can confuse bundling and cause failures; sometimes the server action isn’t marked properly.
• Fixes:
  • Mark server actions with the use server directive at the top of the file.
  • Prefer importing/defining the server action in a parent server component and pass the action down to the client component as a prop. Server actions can be passed as props and are handled across the server/client boundary, whereas normal functions cannot.
  • You may import types into client components, but do not import the server function implementation itself.

3) Clarify server-only files for better errors

• Use community/Next guidance to mark files that must never be sent to the client by importing the helper:
  • import "server-only"
• Benefits:
  • Produces more actionable error messages (e.g., “importing a component that needs server-only”) rather than misleading env-var errors.

---

Other notes and gotchas

• Changing DB drivers/platforms (example: Neon/Postgres → Turso/libSQL/SQLite) can reveal bundling issues if server-only code is accidentally imported on the client.
• Some libraries and cookie handling behave differently between server and client components; depending on how cookies/auth are used, you may be forced to keep code in server components.
• Avoid insecure quick fixes like pasting env vars into client-shipped files to bypass errors — this masks the real import/boundary problem and leaks secrets.
• Next.js docs mention patterns (like passing server actions to client components), but they don’t always explain the nuanced bundling/debugging issues; expect some time-consuming debugging when boundaries are crossed.

---

Practical checklist to avoid these traps

• Always check whether a component/file is server or client:
  • Add use client at the top of client components.
  • Add use server for server actions.
• Never import server components or server-only modules into client components.
• If a client UI needs to trigger server behavior, either:
  • Pass the server action from a server parent as a prop, or
  • Call an API route from the client.
• Use server-only markers (e.g., import "server-only") in DB/adapter files to surface clearer errors.
• Import only types (not implementations) into client components when you need typing without importing server code.

---

Mentioned technologies / libraries / sources

• Next.js (app router, server components, client components, server actions)
• React directives: use client and use server
• server-only (library/import to mark server-only files)
• Databases/drivers: Neon (Postgres), Turso / libSQL / SQLite
• Bundling errors (Webpack) as symptoms of boundary issues
• Next.js documentation and community guidance for patterns

---

Main speaker / sources

• Presenter (video author) — demonstrated examples and debugging steps.
• Next.js documentation and the server-only library are explicitly referenced as guidance sources.