Next.js

Verified against Claude Code · 2026-07-31

Structure a monorepo running multiple Next.js apps without duplicating your design system

Lays out a Turborepo workspace for several Next.js apps sharing UI, types, and config through internal packages linked via the workspace protocol, instead of code copy-pasted between app directories.

Claude CodeCursorGitHub Copilot4 fillable variables

The prompt

Ready to copy — highlighted parts are example details you can swap.

You are designing the monorepo layout for several Next.js apps that need to share code, using Turborepo and pnpm workspaces, with shared code living in internal packages that each app depends on via the workspace protocol rather than files copy-pasted between app directories.

APPS NEEDED
marketing site (apps/web), customer dashboard (apps/dashboard), internal admin tool (apps/admin)

SHARED CODE NEEDED
A design-system UI package, shared TypeScript types for the API, shared eslint/tsconfig config

DEPLOYMENT MODEL
Each app deploys independently as its own Vercel project with its own domain and preview deployments

STRUCTURE REQUIREMENTS
Put apps/ at the repo root, holding one folder per deployable Next.js app, each with its own next.config file, package.json, and env files — Next.js resolves .env files relative to each app's own root directory, not the monorepo root, so every app needs its own env files even for values that happen to be identical across apps; a shared .env file sitting at the repo root silently does nothing for any of them. Put packages/ at the repo root too, holding shared, non-deployable code: a UI package for shared components, a config package for shared eslint, tsconfig, and Tailwind config, a types package if there's a shared domain model worth centralizing, each with its own package.json so it can be versioned and depended on independently. Wire apps to internal packages via the workspace protocol — for example "@repo/ui": "workspace:*" — so a change to a shared package is picked up by every app that depends on it without a publish step in between; without this live link, "shared" UI components tend to get copy-pasted at the first point of divergence, since there's no actual dependency forcing consumers to stay in sync. Configure turbo.json's task pipeline so build, lint, and test tasks declare their real dependencies — a shared package's build must complete before an app that depends on it builds — so Turborepo's caching can actually skip rebuilding an app when nothing it depends on has changed; don't leave every task marked as depending on the whole repo by default, since that defeats the caching benefit that's the entire reason to accept a monorepo's coordination overhead in the first place. Decide, and state explicitly, whether each app deploys independently as separate projects and domains or as part of one coordinated deployment, since this affects whether environment variables and preview deployments get configured per-app or centrally.

OUTPUT FORMAT
The folder tree showing apps/ and packages/ with their contents, an example turbo.json pipeline entry showing the dependency between a shared package's build and an app's build, and one paragraph specifically explaining the env-file resolution gotcha above and how it changes what each app's setup instructions need to say.

Customize

Optional — swap in your own details for the highlighted parts above.

Why this works

The env-file detail is the one that actually bites teams in production and rarely shows up in a generic monorepo tutorial: Next.js resolves .env files relative to each app's own root, not the monorepo root, so a shared .env file at the repo root silently does nothing for any app — every app needs its own env files even for variables that are identical across every one of them, and a setup guide that doesn't say this explicitly leads to a very confusing debugging session where a variable that's clearly set in the repo appears completely undefined inside a specific app's build. The workspace-protocol dependency is what makes shared packages actually useful rather than aspirational: without a live link like "@repo/ui": "workspace:*", a shared UI package is just a folder that happens to sit next to the apps that use it, and the moment one app needs a slightly different variant of a shared component, the path of least resistance is copy-pasting it locally rather than modifying the shared version — workspace:* is what makes modifying the shared version the actually convenient choice instead. Making the turbo.json task graph reflect real build dependencies, rather than defaulting every task to depend on the whole repo, is what makes the monorepo's build genuinely faster than separate repos would have been, which is the entire reason to accept a monorepo's coordination overhead at all — a task graph that treats every package as a dependency of every app means Turborepo's caching has nothing meaningful to skip, since a single commit to any file anywhere invalidates the cache for everything, and the team pays every cost of coordinating a monorepo while getting none of the caching benefit that's supposed to offset it.

What you get back

apps/web, apps/dashboard, apps/admin each have their own next.config.ts, package.json, and .env.local. packages/ui (shared components), packages/config (shared eslint-config, tsconfig-base), packages/types (shared API types). turbo.json: the dashboard app's build task lists ['^build'] as a dependency, meaning packages/ui and packages/types build first, and Turborepo only rebuilds dashboard when its own files or one of those two packages' outputs actually changed — not on every commit to apps/admin, which shares neither package with dashboard's current dependency graph.

Verified against

Claude Code Sonnet 4.6 · 2026-07-31

Cursor Cursor 2.1 · 2026-08-05

Changelog

  • 2026-07-31 Initial publish, verified against Claude Code (Sonnet 4.6) laying out a three-app Turborepo/pnpm workspace with Next.js 16 apps.

Need this built into your business?

If a prompt isn't enough — custom software, built and maintained for you — that's Scult's day job.

EXPLORE CUSTOM SOFTWARE
All Next.js prompts

Check your AI visibility

One URL in, a 0–100 score and the exact fixes out.

RUN THE CHECK

Browse all the tools

15 tools across six categories
13 of them never send your data anywhere

Free · No signup · No trial clock

SEE THE DIRECTORY