Thanks for your interest in contributing! This guide will help you get started.
- Node.js 24 or later (see
.nvmrc) - npm 11 (see the root
packageManagerfield)
# Clone the repo
git clone https://github.com/cleverbrush/framework.git
cd framework
# Install dependencies
npm ci
# Build all packages
npm run build
# Run tests & typechecks
npm run testThe root build also refreshes workspace CLI links. On a fresh checkout npm cannot
link cb-orm until its generated dist/bin.js exists; the postbuild step makes
demo migration commands work without a second dependency installation.
In addition to lint, build and unit/type tests, CI runs:
npm run test:coverage
npm run test:packages
npm audit --audit-level=high
npm run typecheck:schema-site
npm run typecheck:docs-site
npm run build:schema-site
npm run build:docs-sitecoverage-thresholds.json sets per-package statement, branch, function and line
floors for unit coverage. New published packages need explicit floors; do not
lower existing floors to hide regressions. Refresh README badges explicitly with
npm run coverage:badges after a successful coverage run. Badges do not include
the dedicated database or S3 integration suites. Query, ORM and PostgreSQL
scheduler unit tests use the real Knex compiler with a simulated driver boundary
to check SQL, bindings, row decoding and failure paths. These do not prove database
locking, concurrent claims, lease recovery or transactional behavior: the real
PostgreSQL suites remain mandatory even when unit coverage reaches 100%.
The package smoke test packs every published workspace, installs the tarballs and peer dependencies in a disposable consumer, checks every export and TypeScript declaration, and bundles browser entry points without Node polyfills. It requires registry access and deletes only its own temporary directory on completion.
CI runs the query and durable scheduler integration suites against disposable
PostgreSQL in UTC and America/Los_Angeles, and the storage suite against Garage.
Locally, provide isolated QUERY_TEST_DATABASE_URL and
SCHEDULER_TEST_DATABASE_URL values, then run npm run test:queries:integration
and npm run test:scheduler:integration. npm run test:storage:integration
creates and cleans up its own Docker service. Never point tests at production.
The full demo API/browser/telemetry E2E stack and API-reference generation also
run in CI. Both beta and stable publication wait for this reusable validation
workflow. TypeDoc's non-exported internal-type warnings remain visible; they are
not suppressed by the documentation build.
This project uses npm workspaces with Turborepo for orchestration. All packages live under libs/:
| Package | Description |
|---|---|
@cleverbrush/schema |
Type-safe schema validation with immutable builders |
@cleverbrush/deep |
Deep equality & deep extend utilities |
@cleverbrush/async |
Async utilities (Collector, debounce, throttle, retry) |
@cleverbrush/mapper |
Schema-driven object mapping |
@cleverbrush/react-form |
React form library powered by schema PropertyDescriptors |
@cleverbrush/scheduler |
Typed durable jobs, recurring schedules and progress |
@cleverbrush/knex-clickhouse |
Knex dialect for ClickHouse |
This table highlights foundational packages. The root package inventory lists all published packages, including HTTP, persistence, storage and telemetry.
Biome handles both formatting and linting:
# Check for lint/format issues
npm run lint
# Auto-fix issues
npm run lint:fixTests use Vitest and are co-located with source files (*.test.ts):
# Run all tests with typechecking
npm run test
# Run tests for a specific package
npx vitest --run libs/schema# Build all packages (respects dependency order via Turbo)
npm run build
# Clean all build artifacts
npm run cleanThe extension system is the primary way to add new validators. See libs/schema/src/extensions/ for examples.
- Create your extension file (e.g.
libs/schema/src/extensions/myExtension.ts) - Define methods with
defineExtension()and return the new immutable builder - Add tests in a co-located
*.test.tsfile - Re-export from
libs/schema/src/extensions/index.ts
See the schema README's extension-system examples for defineExtension() and
withExtensions(). Do not discard the builder returned by an extension method.
Builders live in libs/schema/src/builders/. Each builder extends the base SchemaBuilder class.
- Create your builder file in
libs/schema/src/builders/ - Extend
SchemaBuilderwith appropriate type parameters - Add a factory function (e.g.
myType()) and export it - Add comprehensive tests in a co-located
*.test.tsfile - Export from
libs/schema/src/index.ts
- Create a feature branch from
developmentand targetdevelopmentin the PR - Make your changes with tests
- Add a changeset — every PR that changes package behavior needs one:
Follow the prompts to select affected packages and describe the change.
npx changeset
- Ensure all checks pass:
npm run lint npm run build npm run test - Open a PR against
master
- patch — bug fixes, internal refactors with no API change
- minor — new features, new extensions, new builders
- major — breaking API changes
All packages are versioned together (fixed release group), so a single changeset covers all packages.
Open a GitHub issue — we're happy to help.