Skip to main content

What a distribution is

A distribution is a repository that ships a set of modules together.

The modules are git submodules; the distribution is what end users install and upgrade.

The shape

acme/
  package.json          the distribution manifest, versioned by month
  apps/
    monolith/           optional: one deployment serving every app
    widget/             a module with routes
  packages/
    design/             a module without routes, shared by the apps
  policies/             the organization's policy, on every module's own

Everything under apps/ and packages/ is a submodule with its own repository, its own history and its own semver tags. policies/ is the organization's own, and stays in the distribution.

What the manifest holds

{
  "name": "@acme/core",
  "version": "26.09.01",
  "dependencies": { "@fairgarden/core": "26.6.1" },
  "distribution": { "extends": "@fairgarden/core" }
}

A date for the version, and the distribution it extends if it extends one. Note what is absent: no module versions. See where a version comes from.

What each piece does

  • Versioning — months for users, semver for developers, and why the submodule is the only place a version is written.
  • Modules — apps are mounted at a path, packages are depended on, and both are submodules resolved through the pnpm workspace.
  • Extending — a distribution may ship another distribution's modules and move ahead of them, never behind.
  • Policies — the organization's rules, on every module's own, built once and run by every service.
  • Deploying — a simple distribution deploys as one Next app; a complex one deploys each app separately.
  • Changelogs — every pull request adds its line, so a release's notes are written before it goes out.
  • Forking a module — fix one in your distribution, offer it upstream, and go back once upstream has it — or keep the fork.
  • Running it — dev serves the monolith, modular:dev runs each app on its own hostname.
  • Releasing a module — semver for modules, what main carries, and where a fix to an older minor goes.
  • Growing a module — build it inside the distribution, extract it once it works.