Workspace - n3wth docs

Use this guide to contribute to the products. Installing a product in another application does not require cloning this workspace.

Prerequisites#

Node.js 24.x.
npm 11.19.1, matching the root packageManager field.
Git and a feature branch.

git clone https://github.com/n3wth/n3wth.gitcd n3wthgit switch -c docs/my-changenpm install --global npm@11.19.1npm ci

Run installation at the repository root. The root lockfile owns application and shared-library dependencies. Do not fix a workspace resolution problem by creating an app-local lockfile or installing another copy of UI.

Find the right source#

Path	Responsibility	Start or validate
`packages/ui`	Public `@n3wth/ui` package	`npm run check -w @n3wth/ui`
`apps/ui-docs`	Interactive UI documentation	`npm run dev:ui`
`apps/kit`	Kit registry and website	`npm run dev -w @n3wth/kit`
`apps/skills`	Skills catalog, installer, and CLI source	`npm run dev:skills`
`apps/r3-web`	r3 website and documentation	`npm run dev -w @n3wth/r3-web`
`packages/site-config`	Private shared origins and metadata helpers	`npm run check -w @n3wth/site-config`
`docs/developers`	This Docs7 documentation hub	`npx @upstash/docs7 dev docs/developers`

The portfolio and Garden are also applications in this repository. Their public content is not an installable developer product. r3's core server, Redis tests, and package release workflow remain in n3wth/r3.

Build from the root#

Root build commands build shared dependencies before their consumers:

npm run build:ui-docsnpm run build:kitnpm run build:skillsnpm run build:r3

Use npm run build for all applications, and npm run check for the complete workspace validation. npm run check:metadata expects build output; running it before building will report missing files.

Applications import UI; UI owns its Astryx dependency and theme. Applications must not import Astryx directly. Shared packages must not import applications. Read the root and relevant package AGENTS.md before editing.

Verify a change#

Run the relevant package or app check while iterating.
Build the affected app through its root build command.
Run the complete checks required for shared changes. For route, layout, or packaging changes, run the relevant browser tests too.
Push a feature branch and wait for GitHub Site CI before merging.

UI changes can affect all six sites. Check both supported themes, mobile and desktop layouts, first paint, code overflow, anchor links, and browser Back. Pure edits to this hub use the documentation checks.

Releases and deployments#

@n3wth/ui releases from 2.0.0 are managed here through Changesets and publish-ui.yml. Add a Changeset for consumer-facing library changes; do not run npm publish locally. Documentation-only changes do not need a package release.

The six existing Vercel sites use automatic Git deployments. Docs7 is a separate hosting connection to this same repository. Merging documentation is not evidence that a Docs7 site has been connected or deployed; verify the hosted result.

Troubleshooting#

Symptom	Check
npm fails during peer resolution	Confirm `node --version` is 24.x and `npm --version` is 11.19.1; install from the root
An app cannot resolve UI output	Use the root app build command so shared packages build first
Unexpected duplicate React/UI behavior	Check workspace resolution with `npm ls @n3wth/ui react`; avoid nested registry copies
Metadata validation reports missing HTML	Build the relevant applications before checking generated metadata
r3 runtime tests are missing here	Run core development and tests in `n3wth/r3`, not `apps/r3-web`

Source: workspace instructions, build scripts, and UI release process.