Package Runtime Boundaries

When a shared package is consumed by Next.js, mixing browser-only code (React hooks, window) with server-only code (next/headers, filesystem, secrets) in the same entry point causes runtime crashes that TypeScript cannot catch at build time.

This guide defines how we split packages into shared, client, and server entry points to enforce safe boundaries.

Why This Matters

Next.js uses React Server Components by default. When a server component imports a package that re-exports a "use client" hook alongside a server utility, the bundler cannot tree-shake correctly and you get errors like:

Error: `useHook` is not allowed in Server Components.

or:

Error: `next/headers` can only be used in a Server Component.

These errors only appear at runtime, not during type-checking or build. The split strategy catches them at the import boundary instead.

Decision Tree

Use this to classify every module in a package:

Folder Structure

Every package with client or server code follows this layout:

my-package/
├── src/
│   ├── shared/          # Directive-free — runs everywhere
│   │   ├── types.ts
│   │   └── utils.ts
│   ├── client/          # Browser & React only
│   │   ├── hooks.ts
│   │   └── widget.tsx
│   ├── server/          # Node.js & Next.js server only
│   │   └── locale-cookie.ts
│   ├── index.ts         # Re-exports shared/*
│   ├── client.ts        # Re-exports client/* (with directive)
│   └── server.ts        # Re-exports server/* (with directive)
├── tsdown.config.ts
└── package.json

Entry Points

Each entry file re-exports only its own folder. The directive must be the first line of the file.

// src/index.ts — no directive needed
export * from "./shared/types.js"
export * from "./shared/utils.js"

// src/client.ts
"use client"
 
export * from "./client/hooks.js"
export * from "./client/widget.js"

// src/server.ts
"use server"
 
export * from "./server/locale-cookie.js"

Package Exports

Use explicit exports in package.json so consumers cannot accidentally import the wrong entry:

{
  "exports": {
    ".": {
      "types": "./build/index.d.ts",
      "import": "./build/index.js"
    },
    "./client": {
      "types": "./build/client.d.ts",
      "import": "./build/client.js"
    },
    "./server": {
      "types": "./build/server.d.ts",
      "import": "./build/server.js"
    },
    "react-server": "./build/server.js"
  }
}

Build Config (tsdown)

Each package uses a local tsdown.config.ts with one entry per boundary:

// tsdown.config.ts
import { defineConfig } from "tsdown"
 
export default defineConfig({
  sourcemap: true,
  clean: true,
  entry: {
    index: "src/index.ts",
    client: "src/client.ts",
    server: "src/server.ts",
  },
  dts: {
    compilerOptions: { composite: false },
  },
  platform: "neutral",
  format: ["cjs", "esm"],
  outExtensions: ({ format }) => ({
    js: format === "cjs" ? ".cjs" : ".js",
    dts: ".d.ts",
  }),
  outDir: "build",
})

Omit client or server from entry if the package doesn’t need them.

Biome Enforcement

We enforce boundary rules via Biome’s noRestrictedImports with scoped overrides:

This turns runtime boundary violations into lint errors that are caught before code is committed.

Setting Up a New Package

pnpm --filter <pkg> build