Nx-first Monorepo

Summary

Prox OS is now an Nx-first pnpm monorepo. pnpm remains responsible for package linking and lockfile management. Nx is responsible for project graph discovery, repo-wide task orchestration, affected project selection, target defaults, cache policy, and AI-readable dependency visibility.

Why Nx

Prox OS now contains a browser OS shell, official app packages, UI packages, contracts, runtime registries, docs, Storybook, and a Cloudflare Worker. A plain script runner can execute tasks, but it does not explain the workspace to humans or AI agents. Nx gives the repo:

project graph visibility for shell, app packages, docs, and API boundaries;
affected commands for multi-agent branches;
target defaults for build, lint, typecheck, test, deploy, and Storybook;
named inputs for production and shared global files;
local cache for repeated validations;
one command vocabulary across apps and packages.

Common Commands

pnpm nx graph
pnpm nx show projects
pnpm nx run @prox-os/os-shell:dev
pnpm nx run @prox-os/os-shell:build
pnpm nx run-many -t lint typecheck --exclude=prox-os
pnpm nx run-many -t build --exclude=prox-os
pnpm nx affected -t lint typecheck build --exclude=prox-os
pnpm affected:quality
pnpm quality

Use package-specific Nx targets for local work and affected for branch validation when the change is scoped. Use run-many when a broad migration must prove the entire repo still works.

Adding Projects

When adding an app or package:

Add it under the pnpm workspace roots.
Give the package a name and local scripts for the targets it supports.
Keep scripts thin wrappers around the package's real tool.
Run pnpm nx show projects to confirm Nx sees it.
Update architecture docs when a new package boundary exists.

What Not To Do

Do not bypass Nx with long root-level workspace command chains.
Do not deep-import shell internals from official app packages.
Do not make UI packages depend on business state, app i18n, Zustand, or data fetching.
Do not hide missing targets by adding no-op scripts.
Do not make deployment targets perform real production changes without human approval.

Now / Next

Now:

root scripts use Nx;
nx.json defines named inputs and target defaults;
build, lint, typecheck, deploy, Storybook, and docs targets are wrapped by Nx where package scripts exist;
architecture scripts remain root-level quality gates and are documented as companions to Nx.

add Nx tags for packages and apps;
add boundary checks that mirror package taxonomy;
expose the project graph inside an OS app surface;
use Nx affected output in PR summaries and agent task handoff.