belgattitude/nextjs-monorepo-example

Collection of monorepo tips & tricks

Summary

nextjs-monorepo-example is a TypeScript monorepo tutorial built around Next.js, Yarn 4 workspaces, and Turborepo, with shared packages for UI, i18n, a Prisma data layer, and ESLint configuration. It documents a working setup for two apps (nextjs-app and vite-app) plus five packages and doubles as a reproducible sandbox for filing Next.js, Vercel, or Prisma bug reports. The project is licensed under MIT and targets engineers who want a concrete, opinionated reference rather than a blank starter.

What it is useful for

This repo is useful for engineers setting up a TypeScript monorepo that includes a Next.js application alongside other apps and shared libraries. Concretely, the README shows how to:

• Structure an apps/ and packages/ workspace with Yarn 4 ("workspaces": ["apps/*", "packages/*"] in the root package.json).
• Consume shared packages from a Next.js app using TypeScript paths aliases and the workspace:^ protocol, with experimental.externalDir: true in next.config.mjs.
• Wire shared tooling: an eslint-config-bases package, a UI library using Emotion and Storybook, a Prisma data layer (db-main-prisma), and a common-i18n package of locales.
• Run cross-workspace commands such as yarn g:typecheck, yarn g:lint, yarn g:test, and yarn g:build from any folder.
• Maintain changelogs and publishing with Atlassian Changesets via yarn g:changeset.
• Configure GitHub Actions workflows that only trigger on relevant path changes and cache node_modules plus previous Next.js builds.
• Deploy to Vercel (documented under docs/deploy/deploy-vercel.md) or build a Docker image (documented under docs/docker/docker.md).

The README also lists documented drawbacks: increased build time, growing git repository size, multi-language monorepos being hard to manage, and versioning complexity when sharing packages outside the monorepo.

How engineers can use it

The documented installation steps are:

corepack enable
yarn install

After that, the fastest way to learn is to follow the four-step walkthrough under the README's "Howto" section: create a folder under packages/, add it to an app with yarn add @your-org/<name>@'workspace:^', declare a paths entry in the app's tsconfig.json, and enable experimental.externalDir in next.config.mjs. Reference implementations live in apps/nextjs-app/package.json, apps/nextjs-app/tsconfig.json, and packages/ui-lib/package.json.

For day-to-day work, the global yarn g:* scripts (listed in the "Monorepo scripts" table) let you run typecheck, lint, test, build, and changeset commands across all workspaces. CI behavior is visible in .github/workflows/, including the paths filter and the caching strategy. The setup uses Yarn 4, so engineers unfamiliar with Corepack should consult the linked Yarn protocols documentation before adopting this template as a base.