SpunkArt
Command line and project setup

How to set up a JavaScript monorepo

A monorepo keeps several related projects, such as a website, an API and a shared library, in one repository. Workspaces in npm, pnpm and Yarn link those projects together so a change to the library is visible to the apps at once.

Is it worth it?

A monorepo helps when projects change together. If a fix to a shared validation function must reach the web app and the API in the same release, one repository and one pull request make that easy. It helps less when projects have different owners, release cycles or languages, and it adds tooling to learn. A single app does not need one.

Good signWarning sign
Shared code copied between reposTeams that never touch each other’s code
Changes that span two projects every weekVery different build tools per project
One team, one release rhythmStrict access rules per project

A common layout

my-repo/
  package.json          root: workspace list and shared dev tools
  pnpm-workspace.yaml   (pnpm only)
  apps/
    web/package.json    name: "@acme/web"
    api/package.json    name: "@acme/api"
  packages/
    ui/package.json     name: "@acme/ui"
    config/package.json name: "@acme/config"

The split between apps/ (things you deploy) and packages/ (things you import) is a convention, not a rule, but it makes the purpose of each folder obvious. A scope such as @acme/ keeps internal names from clashing with packages on the public registry.

Setting it up with npm workspaces

  1. Create the root package.json and mark it private so it can never be published:
    {
      "name": "acme",
      "private": true,
      "workspaces": ["apps/*", "packages/*"]
    }
  2. Give each project its own package.json with a unique name.
  3. In the app that uses the library, add it as a dependency: npm install @acme/ui --workspace @acme/web.
  4. Run npm install once at the root. npm installs everything and links @acme/ui into node_modules as a link to the folder, not a downloaded copy.

The pnpm version

pnpm lists workspaces in its own file instead of package.json:

packages:
  - "apps/*"
  - "packages/*"

Internal dependencies use the workspace protocol, which guarantees the local copy is used: "@acme/ui": "workspace:*". pnpm is stricter than npm about undeclared dependencies, which catches imports that only worked by accident.

Running scripts across projects

npm run build --workspaces           # every workspace that has a build script
npm run test --workspace @acme/api   # just one
pnpm -r build                        # pnpm: recursive, in dependency order
pnpm --filter @acme/web dev          # pnpm: one project

As the repo grows, task runners such as Turborepo or Nx add caching and run only what changed. Start without one; add it when builds feel slow, not before.

Common mistakes

  • Importing from another package by relative path. ../../packages/ui/src bypasses the package boundary. Import @acme/ui and use its exports field.
  • Several lock files. A workspace has one lock file at the root. Delete stray ones inside apps.
  • Library not built. If the library compiles TypeScript to dist/, the apps see nothing until it is built. Order builds so packages come first.
  • Different versions of the same tool. Keep shared dev tools such as the linter and TypeScript in the root to stay consistent.

Questions

Can I deploy just one app from a monorepo?

Yes. Most hosts let you set a root directory per project, and CI can filter on changed paths.

Does a monorepo mean one huge build?

No. Each workspace keeps its own scripts. Tools decide what to run.