Server Components and external packages — what does `serverComponentsExternalPackages` do?

Q: Server Components and external packages — what does `serverComponentsExternalPackages` do?

**Target Audience:** Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. **Difficulty:** Medium > **How to read this doc:** Each idea is explained in plain language first, then tagged with `📌 Interview term:`. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the **Verified** section, against real output from a build or a running server; each Verified block says which version it ran on. ## 1. Why This Even Matters — A Story First Bundling is like packing all the tools for a job into one toolbox. Most tools fit, but some are bolted to the workshop wall (native binaries) or need the rest of the workshop to work (files they read at runtime). serverExternalPackages is the note that says: do not try to pack this one, the worker will use it from the workshop wall when needed. ## 2. The Core Idea 📌 **Interview term: serverExternalPackages** — a nex

The problem

Question presented to candidate: "A package with native binaries breaks when Next.js bundles it for Server Components. What does serverComponentsExternalPackages do, what is it called now, and when do you need it?"

What a strong answer should cover:

By default Next.js bundles the dependencies of Server Components and Route Handlers into the server output.
Some packages break when bundled: native addons, packages that read their own files at runtime, or packages with dynamic requires.
serverExternalPackages (renamed from experimental.serverComponentsExternalPackages in Next.js 15) tells Next.js to leave those packages unbundled and require them from node_modules at runtime.
Next.js already keeps a built-in list of such packages external (for example Prisma and sharp), so most apps never need to configure it.
The old experimental key is flagged as invalid, but Next.js still maps it to the new option and prints a warning.

Clarifying questions expected:

"What is the exact build or runtime error?" — module-not-found for a binary or a missing file points to bundling.
"Is the package already on the built-in list?" — then the problem is elsewhere.

Code / implementation expected: Yes — the config option and what changes in the build output.

rsc
serverExternal

Try it yourself

Sketch your approach before you read the solution. That is what the interview tests.

Stuck? Get a hint.

A short nudge toward the approach. It will not give the answer away.

Solution

Target Audience: Frontend engineers preparing for Next.js interviews — assumes basic React and App Router familiarity. Difficulty: Medium

How to read this doc: Each idea is explained in plain language first, then tagged with 📌 Interview term:. Every behaviour claim was checked against the Next.js docs shipped with the package (written on 16.3.4, re-reviewed against 16.4.2) and, in the Verified section, against real output from a build or a running server; each Verified block says which version it ran on.

1. Why This Even Matters — A Story First

Bundling is like packing all the tools for a job into one toolbox. Most tools fit, but some are bolted to the workshop wall (native binaries) or need the rest of the workshop to work (files they read at runtime). serverExternalPackages is the note that says: do not try to pack this one, the worker will use it from the wo

The solution is hidden so you can try first

5 min read · 8 sections

Read the code

Externalizing a native package

// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
  serverExternalPackages: ["@acme/native-pdf"],
};
export default nextConfig;

// app/api/invoice/[id]/route.ts  (server code using the package)
import { renderPdf } from "@acme/native-pdf"; // required from node_modules at runtime
export async function GET(_req: Request, ctx: { params: Promise<{ id: string }> }) {
  const { id } = await ctx.params;
  const pdf = await renderPdf({ invoiceId: id });
  return new Response(pdf, { headers: { "content-type": "application/pdf" } });
}

Discussion

Other approaches, follow-ups and how it went in real interviews.

Sign in to join the discussion.

No comments yet. Share how you would answer it.

The solution is hidden so you can try first

Keep your momentum going.