Developer Guide

Single source of truth for setting up the monorepo, understanding its structure, and doing day-to-day development work.

For the branching strategy and PR process see WORKFLOW.md. For performing releases (local + NPM) see RELEASE_GUIDE.md.

#Prerequisites

#First-time setup

# 1. Clone
git clone https://github.com/yoltra/yoltra.git
cd yoltra

# 2. Install all workspace dependencies (Rush manages pnpm)
rush install

# 3. Build the entire monorepo (graph-aware, incremental)
rush build

Rush reads the project graph from rush.json, installs all packages into the shared common/temp/ store, and links them using pnpm workspaces.

#Repository structure

yoltra/
├── packages/
│   ├── core/                 @yoltra/core      — state container library
│   └── react/                @yoltra/react     — React bindings
│
├── tools/
│   ├── eslint-config-base/   @yoltra/eslint-config-base  — shared ESLint (Node + browser TS)
│   ├── eslint-config-react/  @yoltra/eslint-config-react — shared ESLint (React + TS)
│   └── registry/             Verdaccio local registry (Docker)
│
├── examples/
│   └── v0/
│       ├── yoltra-in-react/        Yoltra vs Redux Toolkit comparison app
│       ├── yoltra-in-nextjs/       Next.js integration example
│       └── yoltra-kinetic-logo/    SVG animation — fine-grained subscription demo
│
├── common/
│   ├── config/rush/          Rush config files (committed — never edit lockfile by hand)
│   └── scripts/              Shared helpers (copy-license.cjs, etc.)
│
└── docs/
    ├── en/                   English documentation (this folder)
    └── es/                   Spanish translations

#Everyday commands

#Monorepo-wide

rush install            # Install / sync all dependencies (after cloning or pulling)
rush update             # Regenerate lockfile (run after editing any package.json)
rush build              # Incremental build — uses cache, skips unchanged packages
rush rebuild            # Force full rebuild — bypasses cache, rebuilds everything
rush test               # Run Vitest across all packages
rush lint               # Run ESLint across all packages
rush typecheck          # Run tsc --noEmit across all packages

#Focused builds

Use --to and --from to narrow the build to a subset of the dependency graph:

rush build --to @yoltra/core           # Build core and its transitive deps
rush build --to @yoltra/react          # Build react (and core first)
rush build --from @yoltra/core         # Build core and every downstream dependent
rush build --to @yoltra/react --verbose  # Same, with detailed output

#Per-package commands (rushx)

rushx runs an npm script in the current package. Change to the package directory first:

cd packages/core
rushx build         # Build just this package
rushx test          # Run tests with coverage
rushx lint          # Check for lint errors
rushx lint:fix      # Auto-fix lint issues
rushx typecheck     # TypeScript type checking

cd packages/react
rushx build
rushx test
rushx docs          # Generate TypeDoc API docs

#Build cache

Rush's local build cache is enabled via common/config/rush/build-cache.json.

Each library package declares its cacheable output in rush-project.json:

{
  "operationSettings": [{ "operationName": "build", "outputFolderNames": ["dist"] }]
}

Key rules:

• rush build — reads and writes the cache; unchanged packages finish instantly.
• rush rebuild — always skips the cache; use this when you suspect a stale output.
• Cache lives in common/temp/build-cache/ (gitignored, local only).

#ESLint architecture

Lint configuration is extracted into two shareable packages under tools/:

Each library package has a thin eslint.config.mjs that just re-exports the shared config:

// packages/core/eslint.config.mjs
import baseConfig from "@yoltra/eslint-config-base";
export default baseConfig;

// packages/react/eslint.config.mjs
import reactConfig from "@yoltra/eslint-config-react";
export default reactConfig;

To add a rule globally — edit the config package in tools/. No need to touch each library's eslint.config.mjs. To override a rule for one package — extend the array in that package's eslint.config.mjs.

#Conventional commits + DCO

Every commit must:

1. Follow Conventional Commits:

   tsCopy

   <type>(<scope>): <short description>
   
   [optional body]
   
   Signed-off-by: Your Name <you@example.com>

2. Carry a DCO sign-off (git commit -s appends it automatically).

Allowed <type> values: feat, fix, perf, refactor, docs, test, build, chore, revert.

#Testing & coverage

• Runner: Vitest
• UI helpers: @testing-library/react (for @yoltra/react)
• Minimum coverage thresholds (lines / branches / functions / statements): 95%

# All packages
rush test

# Single package
cd packages/core && rushx test

Snapshot tests are only allowed for stable, deterministic output.

#Change files (required for every publishable PR)

Any PR that modifies @yoltra/core, @yoltra/react, or another published package must include a Rush change file. (There is no CI yet — verify it locally with the command below; wiring rush change --verify into CI is the recommended enforcement, see the Release Guide.)

# Interactive prompt — select the packages you changed and the bump type
rush change

# Verify a change file exists
rush change -v

Change files are committed to common/changes/ alongside the code change. When a release is prepared they are consumed by rush version --bump to update package.json versions and generate CHANGELOG.md entries.

#Adding a new publishable package

1. Create the folder under packages/ or tools/.
2. Add a package.json with "publishConfig": { "access": "public" }.
3. Add a minimal rush-project.json (declare outputFolderNames if the package builds).
4. Register the package in rush.json under "projects".
5. Run rush update to regenerate the lockfile.
6. If it ships in sync with the product suite, set "versionPolicyName": "yoltra" (the lockstep policy — see the Release Guide); otherwise leave it unset for independent versioning.

#Updating dependencies

1. Edit the relevant package.json.
2. Run rush update to recalculate and rewrite the lockfile.
3. Commit both the package.json change and the updated common/config/rush/pnpm-lock.yaml.

Never touch common/config/rush/pnpm-lock.yaml by hand.

#Troubleshooting