Next.js in a monorepo: the structure that holds

A Next.js monorepo pays off when two applications genuinely share components, tokens and configuration. The minimum structure is apps/ for deployments, packages/ for shared code and a single lockfile at the root.

The minimum structure

repo/
  apps/
    web/            # app principale, un deploy
      app/
      next.config.ts
      package.json
    docs/           # seconda app, stesso design system
  packages/
    ui/             # componenti condivisi
    config/         # eslint, tsconfig, tailwind
    lib/            # utility pure
  package.json
  pnpm-workspace.yaml
  turbo.json

The workspace is declared in pnpm-workspace.yaml; every folder under apps/ and packages/ carries a package.json with an npm name. Next.js does not know it lives in a monorepo: the module resolver is what links the packages.

What to share and what to keep apart

A package that ships TSX files must be listed in transpilePackages, otherwise the Next build ignores files outside its own folder. If the package is also used outside Next, compile it and publish the output.

// apps/web/next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  transpilePackages: ["@repo/ui", "@repo/lib"],
};

export default nextConfig;

The command that exposes the problem

# una sola versione di React in tutto il workspace
pnpm why react

# build della sola app: rivela gli import fuori dal pacchetto
pnpm --filter @repo/web build

If pnpm why react prints two versions, hooks break with “Invalid hook call” at runtime and the message never says why. The cause is a package that declares React as a normal dependency instead of a peer.

The record I use as an example

The EneUI catalogue indexes 111,985 components and 1,556 blocks from 1,472 libraries (1 November 2026). A complete block installs as source into packages/ui: dashboard-01, with the dashboard category and the primitives in card.

Where a monorepo costs

• Remote build needs a cache token and a configuration nobody maintains.
• The standalone output must ship with the root lockfile, not the app one.
• A shared package without tests becomes a regression point for every app.
• The Next upgrade slips, because it must pass on every app before the merge.

Known limit: Next cannot resolve a package that exposes ESM only, with no exports field. The build fails with a syntax error that points at the wrong file, and the fix lives in the package package.json.

For the structure of a single app see App Router structure. For caching that survives the request see the four cache layers; the framework comparison for a marketing site is Next.js vs Vite.