Next.js in un monorepo: la struttura che regge

Un monorepo Next.js conviene quando due applicazioni condividono davvero componenti, token e configurazione. La struttura minima è apps/ per i deploy, packages/ per il codice condiviso e un solo lockfile alla radice.

La struttura minima

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

Il workspace è dichiarato in pnpm-workspace.yaml; ogni cartella sotto apps/ e packages/ ha un package.json con un nome npm. Next.js non sa di essere in un monorepo: è il resolver dei moduli a collegare i pacchetti.

Cosa condividere e cosa no

Un pacchetto che esporta file TSX va elencato in transpilePackages, altrimenti la build di Next ignora il file fuori dalla sua cartella. Se il pacchetto è usato anche fuori da Next, compilalo e pubblica il risultato.

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

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

export default nextConfig;

Il comando che smaschera il problema

# 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

Se pnpm why react stampa due versioni, gli hook si rompono con «Invalid hook call» a runtime e il messaggio non dice perché. La causa è un pacchetto che dichiara React come dipendenza normale invece che come peer.

Il record che uso come esempio

Il catalogo EneUI indicizza 111.985 componenti e 1.556 blocchi da 1.472 librerie (1 novembre 2026). Un blocco completo si installa come sorgente in packages/ui: dashboard-01, con la categoria dashboard e le primitive in card.

Dove il monorepo costa

• La build remota richiede un token di cache e una configurazione che nessuno mantiene.
• L'output standalone va copiato con il lockfile della radice, non con quello dell'app.
• Un pacchetto condiviso senza test diventa un punto di regressione per tutte le app.
• L'aggiornamento di Next slitta, perché va provato su ogni app prima del merge.

Limite noto: Next non risolve un pacchetto che espone solo ESM senza campo exports. La build fallisce con un errore di sintassi che punta al file sbagliato, e la correzione sta nel package.json del pacchetto.

Per la struttura della singola app vedi struttura App Router. Per la cache che attraversa le richieste i quattro livelli di cache; il confronto tra framework per un sito marketing è in Next.js vs Vite.