Reference

Contributing

Set up the monorepo from source, run tests, and contribute to OXP.

OXP is open source and contributions are welcome. This guide covers setting up the monorepo, understanding the codebase, and submitting changes.

Prerequisites

ToolVersionPurpose
Node.js≥ 22Runtime
pnpm≥ 10Package manager (monorepo workspaces)
DockerAnyLocal Postgres + MinIO
RuststableFor hello-rust example and component testing
GitAnyVersion control

Clone and Setup

bash
git clone https://github.com/oxp-dev/oxp.git
cd oxp
pnpm install

Build Everything

bash
pnpm build

This builds all packages in dependency order:

  1. @oxprotocol/types → 2. @oxprotocol/schema → 3. @oxprotocol/wit → 4. @oxprotocol/ui → 5. @oxprotocol/sdk → 6. @oxprotocol/bundle → 7. @oxprotocol/host-runtime → 8. @oxprotocol/host-core → 9. @oxprotocol/cli → 10. @oxprotocol/web

Local Development

Start Infrastructure

bash
docker compose up -d

This starts:

  • Postgres on port 5432 (user: oxp, password: oxp, db: oxp)
  • MinIO on port 9000 (console on 9001, user: minioadmin, password: minioadmin)

Data persists in .docker/ (gitignored). Wipe with docker compose down -v.

Database Setup

bash
cp apps/web/.env.example apps/web/.env.local
pnpm --filter @oxprotocol/web db:push

Start the Registry

bash
pnpm dev

Opens the registry at http://localhost:3000.

Running Tests

bash
pnpm test                  # all packages
pnpm -r --filter <pkg> test  # specific package

Key test suites:

PackageTestsWhat They Cover
@oxprotocol/bundlesecurity.test.ts, wit-pin.test.tsBundle policy, WIT pinning
@oxprotocol/host-coretofu-pinning.test.ts, permission-prompt.test.ts, activator.test.tsTOFU, permissions, e2e activation
@oxprotocol/host-runtimebroker.test.tsCapability broker, permission denial
@oxprotocol/typestoken-scopes.test.tsScoped token validation
@oxprotocol/witcanonical.test.tsWIT canonical form + sha256

Project Structure

DirectoryPurpose
spec/v1/Normative specification (schema, protocol, bundle format)
packages/npm packages published under @oxprotocol
hosts/IDE host adapters (VS Code, Piye)
apps/web/Registry website + API (Next.js)
examples/Example extensions and test fixtures

Key Scripts

ScriptDescription
pnpm buildBuild all packages
pnpm devStart the registry dev server
pnpm testRun all tests
pnpm lintLint all packages
pnpm cleanRemove all build artifacts
pnpm release:dryDry-run publish to npm

TypeScript Configuration

The monorepo uses a shared tsconfig.base.json:

  • Target: ES2022
  • Module: ESNext with Bundler resolution
  • Strict mode enabled
  • Declaration maps for debugging

Each package extends the base config and adds its own outDir, rootDir, and references.

Code Style

  • TypeScript for all packages
  • ESM ("type": "module") everywhere
  • No external CLI libraries in the CLI package (keep install lean)
  • Vitest for testing
  • Explicit noUncheckedIndexedAccess for safety

Pull Request Guidelines

  1. One concern per PR — keep changes focused
  2. Tests required — add or update tests for behavioral changes
  3. Security review line — if your change touches security controls, confirm it doesn't regress Phase A/B/C
  4. Build must pass — pnpm build && pnpm test must succeed
  5. Update roadmaps — if your PR completes a roadmap item, tick it off