One repo, many deployables: submodules vs workspaces

How to choose between git submodules and a pnpm workspace when several services share code, plus the Docker build that ships one app from a workspace.

Published

Updated

Reading time

10 min

Two of your services need the same validation schema. Copy it once and nothing happens. Copy it three times and one copy gets the fix while the others do not. For code used only by your own services, the mainstream answers in a git-based team are a separate repository attached as a git submodule, or one repository where a package manager links the pieces as a workspace. Copy and paste is the baseline both beat, and a registry-published package is the right call when the code has consumers you do not control, though it puts a release step in front of every small change.

This guide is for two to eight deployable services. It compares the two layouts, gives the one question that decides between them, and then covers the part most workspace tutorials skip: building a Docker image for a single app out of a pnpm workspace.

A submodule pins a commit of another repository; a workspace links packages that live at the same commit.

Compare by what a change looks like#

Trade-offsChange flowTest against callersFresh cloneCI cost
Git submoduleshared repo pinned by commitPR in shared, then a pointer PR per parent (Weak)Only after the shared commit exists (Weak)Needs a flag (Depends)Low (Strong)
pnpm workspaceone repo, one lockfileOne PR (Strong)Same commit (Strong)Clone and install (Strong)Grows unless filtered (Depends)
Table 1— A change to shared code, under each layout.

The cost of a layout is mostly what each change costs. In a workspace, the schema change and the caller fix are one pull request, tested together. With a submodule the change is a pull request in the shared repository, a merge, and then a pointer-update pull request in every parent, which cannot be tested until the shared commit exists. That multiplies with every consumer: a shared library with three consumers means one library review plus three pointer reviews for each change.

The deciding question is how often the shared code changes in the same week as its callers. If the answer is nearly always, the boundary is in the wrong place, and a submodule charges a two-repository tax on every change. Use the workspace.

Use a submodule when the shared repository has its own audience, release rhythm or access rules, and changes rarely enough that a pointer update is an event rather than a chore. A design-token repository consumed by several unrelated products fits. Types shared by an API and its own web client do not.

Set up the workspace#

The workspace is declared in a root pnpm-workspace.yaml, as the pnpm workspaces documentation describes:

pnpm-workspace.yamlyaml
packages:
  - "apps/*"
  - "packages/*"

Each app depends on the shared package with the workspace: protocol, so install links the local directory instead of fetching from the registry:

apps/web/package.jsonjson
{
  "name": "@acme/web",
  "private": true,
  "dependencies": {
    "@acme/shared": "workspace:*"
  },
  "scripts": {
    "build": "tsc -b"
  }
}

There is a single pnpm-lock.yaml at the root by default. The filter syntax is what keeps CI affordable:

terminalbash
# one package and everything it depends on, in dependency order
pnpm --filter "@acme/web..." build
 
# a package and everything that depends on it (what to rebuild after changing shared)
pnpm --filter "...@acme/shared" build
 
# only packages changed since a git ref, plus their dependents
pnpm --filter "...[origin/main]" test

The first builds shared then web and leaves the API alone. The second builds shared and then both apps. The third runs only what the diff can affect. Selecting by changed files needs Git 2.24 or newer. Quote filters that contain ... or brackets, and escape ! in zsh, so the shell does not interpret them before pnpm does.

One rule keeps the workspace from rotting: apps may depend on packages/* but never on other apps. A lint rule or a small script that scans package.json files enforces it. Without it, services start importing each other's internals. Strictness is also why I picked pnpm for my own project: an import that works by accident because nothing declared it fails fast there, which is the kind of failure I prefer.

For independent deploys, give each app its own workflow with a path filter that includes the app and the packages it consumes:

.github/workflows/deploy-web.ymlyaml
on:
  push:
    branches: [main]
    paths:
      - "apps/web/**"
      - "packages/shared/**"
      - "pnpm-lock.yaml"
      - ".github/workflows/deploy-web.yml"

The path list is maintained by hand, so a missing entry means a silent skip. The alternative is letting pnpm --filter "...[HEAD~1]" decide inside the job, at the cost of starting a runner on every push. For two or three services I prefer explicit paths. Credentials work as in any pipeline; keyless auth for GitHub Actions works unchanged from a monorepo, one workflow per app.

Build one app's image from the workspace#

This is where a workspace stops being a tutorial. A Docker build needs the app, the shared package it links to and their production dependencies, but not the other apps or the dev tooling. Copying only apps/web into the image breaks, because @acme/shared is a link to a directory outside it.

pnpm deploy is the tool for this. It copies one workspace package into a target directory and installs its dependencies there, including workspace dependencies, into an isolated node_modules, so the result is portable. The pnpm deploy documentation lists the behaviours that matter:

  • The --filter must match exactly one project. None fails with ERR_PNPM_NOTHING_TO_DEPLOY, several with ERR_PNPM_CANNOT_DEPLOY_MANY.
  • The target directory must be empty unless you pass --force, and it cannot be the workspace root.
  • Before pnpm 12.2.0, deploy refused workspaces that did not set injectWorkspacePackages (or you passed --legacy). Since 12.2.0 a linked workspace dependency becomes a file: dependency in a deploy-specific lockfile and that requirement is gone. If you are on an older pnpm, set injectWorkspacePackages: true in pnpm-workspace.yaml or upgrade.
  • By default it copies the files pnpm pack would include: the files field of package.json, otherwise .npmignore, otherwise .gitignore.

The last point is the gotcha. Most repositories git-ignore dist, so a deploy driven by .gitignore leaves the compiled output out and the image starts with nothing to run. The same applies to the shared package: its built output must be included. Declare it explicitly in both packages:

apps/web/package.json (excerpt)json
{
  "files": ["dist"]
}
packages/shared/package.json (excerpt)json
{
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"]
}

Then a multi-stage Dockerfile whose build context is the repository root, because the build needs the lockfile and the workspace file:

apps/web/Dockerfiledockerfile
FROM node:22-bookworm-slim AS build
ENV PNPM_HOME=/pnpm PATH=/pnpm:$PATH
RUN corepack enable
WORKDIR /repo
 
# Manifests first, so the install layer is cached until dependencies change.
COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
COPY apps/web/package.json apps/web/
COPY packages/shared/package.json packages/shared/
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
    pnpm install --frozen-lockfile --filter "@acme/web..."
 
COPY apps/web apps/web
COPY packages/shared packages/shared
RUN pnpm --filter "@acme/web..." build
RUN pnpm --filter @acme/web --prod deploy /out
 
FROM node:22-bookworm-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build /out /app
USER node
CMD ["node", "dist/server.js"]

Build it from the root: docker build -f apps/web/Dockerfile -t web .. The trailing . is the context, and it is why a .dockerignore at the root listing node_modules, .git, .env* and other apps' build output matters. Corepack reads the packageManager field in the root package.json, so the image uses the same pnpm as your laptop. The ... suffix in the filters selects the app plus its workspace dependencies only, so changes to an unrelated app do not invalidate the cache.

If you keep a submodule#

I run the submodule layout myself, so I know its costs. My top-level repository holds the backend services, both frontends, infrastructure configuration and the cross-cutting docs, and each deployable service is its own repository mounted as a submodule with its own small CI pipeline. I chose it for deploy independence: a merge to a service's main branch builds and deploys that service and nothing else, so the blast radius of a change is visible in the pull request URL. One clone also shows the whole system, and the pointer commits double as a rough system changelog. It suits many deployables and one maintainer; with a different ratio I would answer differently.

For the narrow case where a submodule is right, these are the commands from the Pro Git submodules chapter. Add it to the parent, choosing the path:

terminalbash
git submodule add ../shared.git libs/shared
git commit -m "Add shared library"

This records the URL in .gitmodules and one commit hash in the parent. A plain clone gets an empty directory, so clone with git clone --recurse-submodules or run git submodule update --init --recursive in an existing clone. A new commit in the shared repository changes nothing in the parent until you move the pointer:

terminalbash
git submodule update --remote libs/shared
git diff --submodule        # shows a one-line log of what changed
git add libs/shared
git commit -m "Update shared to include the v2 schema"

The submodule is left on a detached HEAD, which the book flags as the place where commits get lost. Check out a branch inside it before editing. Three settings remove most daily friction:

terminalbash
git config --global diff.submodule log
git config submodule.recurse true
git config push.recurseSubmodules check

The first makes git diff show the readable log. The second makes pull, checkout and similar commands recurse (not clone). The third makes git push refuse if the parent points at a submodule commit that has not been pushed, which prevents a parent referencing a commit that exists only on one laptop.

In CI, actions/checkout takes a submodules input (true or recursive; the default is false), and a private submodule needs a credential that can read it, because the default token is scoped to the current repository:

.github/workflows/ci.ymlyaml
- uses: actions/checkout@v7
  with:
    submodules: recursive
    token: ${{ secrets.SUBMODULE_READ_TOKEN }}

Use a fine-scoped token with read access to that single repository. The recurring submodule problem is the stale pointer: the parent builds the commit it recorded, so a fix lands in the shared repository and services keep shipping the old behaviour until someone moves the pointer. A scheduled job that opens an update pull request per parent is the usual remedy.

Two more costs from my own use. Pointer updates are a ritual I cannot skip, and on Windows long paths and file locks add friction. Feature work therefore happens in a git worktree checked out from the remote default branch, which keeps long-running local state out of pull requests and avoids the file-lock trouble of switching branches under an editor, a package manager and a dev server at once. Pruning worktrees and watching path lengths took a few mistakes to learn.

What goes wrong in a workspace#

  • Everything builds on every push. Without filters, build time grows with the number of packages. Use the changed-since filter plus caching. If the build graph outgrows what pnpm filters express, a dedicated task runner is the next step, and not before.

  • One lockfile, one blast radius. A dependency upgrade affects every app at once. That is mostly the point, since drift is what you are avoiding, but a risky upgrade needs a branch every service passes before merge.

  • Configuration is not shared. A shared repository is not a shared environment. Keep configuration out of shared code and load it in each service, as in configuration and secrets for multi-service Node apps.

  • A tool that assumes another layout. In my repository the serverless functions deployed with a vendor CLI stay on npm, because that CLI's packaging quietly assumes npm's node_modules layout. I spent an afternoon trying to force pnpm on them, then wrote the exception down and moved on.

  • Docs that lag the code. A behaviour-changing pull request updates the relevant docs in the same diff. Much of my coding is done with an AI assistant that reads those docs as context, so a stale page steers it wrong today.

Which to pick#

  • Your own services, shared code changing weekly: a pnpm workspace, one deploy workflow per app, pnpm deploy for images.
  • Shared code with its own audience, release rhythm or access rules, rarely changed: a submodule, with push.recurseSubmodules check and a job that proposes pointer updates.
  • Outside consumers: publish a versioned package. Neither layout gives strangers a stable contract.
  • A single deployable: neither; a folder is enough.
  • Two services that always change together: ask whether they are really one service, which is a better question than the repository layout.
Share
All articles →