---
title: "ADR-0003: Mandatory Nimbus"
---

> Documentation Index
> Fetch the complete documentation index at: https://nclsppr.github.io/project-foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-0003: Mandatory Nimbus

- Status: accepted
- Implementation status: delivered
- Date: 2026-07-27
- Last verification: 2026-07-27, four packs, 44 Markdown files, 49 Nimbus pages, routes, and search verified locally
- Owner: Nicolas Pieper
- Supersedes: ADR-0002
- Superseded by: none

## Context

ADR-0002 required the exhaustive catalog but kept Nimbus optional. This
separation kept the bootstrap small, but it permitted several documentation
engines and required each project to create a Nimbus integration.

The foundation owner now requires Nimbus to be the common documentation surface
for all projects. The Markdown inventory, its audiences, and one editorial
source remain necessary.

## Decision problem

How can the foundation require Nimbus without publishing internal documents by
mistake or making the bootstrap depend on the network?

## Considered options

### Keep Nimbus optional

Advantage: Small projects do not require a Node dependency.

Limitation: The documentation experience varies, and each project must create
the integration later.

### Download Nimbus during each bootstrap

Advantage: The scaffold always comes from the upstream source.

Limitations: The bootstrap depends on the network. The result can change if the
generator or its template changes.

### Vendor the official scaffold in the foundation

Advantages: The bootstrap operates offline. The version and lockfile are
identical. The upgrade diff can be reviewed. The foundation and each project can
verify the build.

Limitations: Node becomes mandatory, and the Nimbus snapshot increases the size
of the foundation.

## Decision

Nimbus is a Project Foundation invariant. All packs automatically enable
`documentation-nimbus` and include the official Nimbus scaffold that
`nimbus.json` tracks.

The minimum Node version is `22.12.0`. `@cloudflare/nimbus-docs` is pinned to
`0.8.2`, and the lockfile is version-controlled. The `verify` command runs the
adapter tests, type check, Nimbus build, and lint.

The Markdown files that `documentation.json` classifies remain the only
editorial sources. The `docs-nimbus/src/content/docs/` collection is regenerated
and ignored by Git.

The local build contains all audiences so that the corpus is navigable.
It does not authorize publication. Each publication process must explicitly
define the permitted collections and prove that it exposes no internal content.

Another engine can supplement Nimbus for a local requirement, but it cannot
replace Nimbus without a new foundation version that supersedes this ADR.

## Consequences

### Positive

- All projects use the same documentation engine.
- A new project receives a scaffold and lockfile that it can verify offline.
- Nimbus build failures cause `verify` to fail.
- The sources remain independent of the generated collection.

### Negative

- Node and npm become universal prerequisites.
- An exploration project also contains a documentation site.
- Nimbus starter updates require review and redistribution.
- Publication requires an audience filter that is separate from the complete local build.

## Implementation

1. Include the official `@cloudflare/create-nimbus-docs` `0.6.3` scaffold.
2. Pin Nimbus and commit the lockfile.
3. Generate the collection from `documentation.json`.
4. Enable the profile automatically in all packs.
5. Add the Nimbus build to local and CI verification.
6. Document migration from `v0.2.0`.

## Verification

- The catalog has no unclassified or duplicate Markdown file.
- The Nimbus profile is present in all four packs.
- Conversion tests pass.
- The Nimbus type check, build, and lint pass.
- The generated collection is absent from Git.
- CI passes for the branch and tag.

## Review

Supersede this decision only if Nimbus is no longer maintained, does not support
the audience requirements, or has a measured and disproportionate cost in
several projects.

Source: https://nclsppr.github.io/project-foundation/docs/decisions/adr-0003-mandatory-nimbus/index.mdx