Development Workflow

This guide covers the essential steps for setting up the UCD.js monorepo, building packages, running tests, and performing common development tasks.

Setup

UCD.js is a monorepo managed with pnpm workspaces and Turborepo.

Node.js: >= 24.13
pnpm: Check the packageManager field in package.json for the exact version.

Clone the repository and install dependencies:

git clone https://github.com/ucdjs/ucd.git
cd ucd

pnpm install

The monorepo separates building packages, applications, and the VS Code extension.

Build all JavaScript and TypeScript packages in the packages/ directory:

pnpm run build

Build all applications in the apps/ directory (API, Store, Web, Docs):

pnpm run build:apps

Build the VS Code extension:

pnpm run build:vscode

Build a specific package using Turborepo filtering. Always run this from the repository root.

turbo run build --filter "@ucdjs/<package>"

Do not run pnpm run build --filter <package> for individual packages. Always use the turbo filter to specify packages if needed.

UCD.js uses Vitest for testing. By default, running tests will output coverage reports.

Run all tests across the monorepo:

pnpm run test

Run tests in watch mode during development:

pnpm run test:watch

Run tests with the Vitest UI:

pnpm run test:ui

Run tests for a specific project from the repository root. The project name corresponds to the folder name in packages/ or apps/.

vitest run --project=<project>

When writing tests, follow these common patterns:

HTTP Mocking: Use mockFetch from #test-utils/msw for HTTP/MSW-driven tests.
API Mocking: Prefer mockStoreApi from #test-utils/mock-store so tests stay consistent with the API surface.
Filesystem Tests: Use testdir() from vitest-testdirs to get a temporary directory that is cleaned up automatically.
Shared Helpers: Rely on @ucdjs/test-utils (via #test-utils/*) for helpers that need to be shared across packages.

Ensure your code meets the project's quality standards before submitting a pull request.

# Run ESLint across the monorepo
pnpm run lint

# Run TypeScript type checking
pnpm run typecheck

Packages: Run pnpm dev for package watch mode and test with vitest run --project=<project>.
Apps: Run pnpm dev:apps for app development servers when needed.
CLI: Run the CLI from the repository root using the workspace sources:
```
./packages/cli/bin/ucd.js <command>
```

After changing API routes or Zod schemas in apps/api:

Learn about the monorepo structure and core systems.