FairGarden Monolith

Version 0.1.0-alpha.1

Compose several Next.js apps into one deployable app.

// apps/monolith/next.config.ts
import { withMonolith } from '@fairgarden/monolith'

export default withMonolith(
  {},
  {
    www: { package: '@fairgarden/www', prefix: '/' },
    id: '@fairgarden/id',
  }
)

id's routes are served from /id, its assets from public/id, and its Pages Router API from /api/id. www takes the site root.

Documentation

The docs are a site in this repository. Run them with:

pnpm --filter @fairgarden/monolith-docs dev

• Overview — what mounting an app actually does
• Mounting — symlinks, and why next dev needs different treatment
• Routing — how rewrites, redirects and headers are merged
• What a monolith can serve — root mounts, and when apps collide
• Next versions — which versions can be mounted together
• Dependencies — what the monolith has to install
• Portability — keeping an app mountable
• Functions — withMonolith, createLink, prefixPath and the rest

Install

pnpm add @fairgarden/monolith

Import	For
@fairgarden/monolith	the monolith's next.config.ts, and an app's portability check
@fairgarden/monolith/link	an app's own components
@fairgarden/monolith/eslint	an app's eslint.config.mjs

It also installs fg-monolith, for the things that happen around a build:

fg-monolith link                 # mount without starting Next
fg-monolith merge-package-json   # fold each app's dependencies in
fg-monolith list                 # print the apps it composes

Submodules, versions and scaffolding are a separate concern, handled by fg-dist in @fairgarden/distribution.

Releasing

This module releases on its own. 0.1.0-alpha.1 is what main is working towards, not what is published — the version here is always the next one. Its release notes are the top section of CHANGELOG.md, where every pull request adds a line linking itself.

1. Publish it. Run the Publish workflow from the Actions tab, picking the dist tag. It refuses if that version is already on npm. Once it is out, open pull requests are held — their changelog check fails — so nothing is noted under a version that has already shipped.
2. Start the next version. pnpm next-version opens a pull request moving main to 0.1.0-alpha.2 and starting its section of the changelog, or pnpm next-version --id rc to change identifier. Merging it lifts the hold. A prerelease gets no maintenance branch; there is no released line behind it yet.

A held pull request goes on once it is brought up to date with main and its line is moved into the new version's section.

Every push to main publishes @fairgarden/monolith@canary. A canary is not a release and carries no promise; it is there so main can be tried without a checkout.