Cleverbrush Framework

Cleverbrush is a schema-first TypeScript framework monorepo. It provides the building blocks for contract-driven web applications: validation, object mapping, React forms, typed HTTP clients, server endpoint contracts, OpenAPI, dependency injection, environment parsing, persistence helpers, logging, and OpenTelemetry.

@cleverbrush/schema is the foundation. A single schema definition can drive runtime validation, TypeScript inference, property descriptors, forms, mappers, JSON Schema, API contracts, and Standard Schema integrations.

Packages

Package	Description
@cleverbrush/schema	Immutable fluent schemas with runtime validation, type inference, property descriptors, extensions, and Standard Schema v1 support.
@cleverbrush/server	Schema-first HTTP endpoint contracts, validation, authorization, dependency injection, and RFC 9457 errors.
@cleverbrush/client	Type-safe HTTP client for @cleverbrush/server contracts, with optional batching, retries, dedupe, cache tags, offline queue, and React integration.
@cleverbrush/server-openapi	OpenAPI 3.x generation from server endpoint metadata.
@cleverbrush/mapper	Schema-driven object mapping with compile-time completeness checks and type-safe property selectors.
@cleverbrush/react-form	Headless React form primitives powered by schema property descriptors.
@cleverbrush/schema-json	JSON Schema generation and JSON Schema to Cleverbrush schema conversion.
@cleverbrush/di	Small dependency-injection container used by server and application code.
@cleverbrush/auth	Principal and authorization utility types.
@cleverbrush/env	Environment-variable parsing and validation with schema builders.
@cleverbrush/orm	Knex-backed ORM layer with typed entity maps and query helpers.
@cleverbrush/orm-cli	CLI tooling for ORM migrations.
@cleverbrush/knex-schema	Knex schema helpers that connect database names to schema metadata.
@cleverbrush/knex-clickhouse	ClickHouse dialect support for Knex.
@cleverbrush/log	Structured logging pipeline, sinks, batching, redaction, and context helpers.
@cleverbrush/otel	OpenTelemetry setup and instrumentation helpers for apps and clients.
@cleverbrush/async	Async utilities including collector, debounce, throttle, and retry.
@cleverbrush/deep	Deep equality, deep extension, flattening, and object utilities.
@cleverbrush/scheduler	Typed durable jobs, recurring triggers and ordered progress.
@cleverbrush/scheduler-postgres	PostgreSQL job persistence, transactional enqueue and fenced leases.
@cleverbrush/storage	Provider-neutral object storage contracts and public URL mapping.
@cleverbrush/storage-s3	Streaming S3-compatible storage for self-hosted and hosted providers.

How The Pieces Fit

import { object, string, number, type InferType } from '@cleverbrush/schema';
import { endpoint, route } from '@cleverbrush/server/contract';

const UserSchema = object({
    id: number().isInteger().min(1),
    email: string().email(),
    displayName: string().minLength(2)
});

type User = InferType<typeof UserSchema>;

const GetUserEndpoint = endpoint
    .get('/api/users', route({ id: number().coerce().isInteger().min(1) })`/${p => p.id}`)
    .responses({ 200: UserSchema });

That same schema can be reused across the stack:

• Runtime validation through .validate() and .validateAsync().
• Type inference through InferType.
• API input and response contracts in @cleverbrush/server.
• Typed clients through @cleverbrush/client.
• OpenAPI documents through @cleverbrush/server-openapi.
• Type-safe object mapping through @cleverbrush/mapper.
• React form fields through @cleverbrush/react-form.
• JSON Schema interop through @cleverbrush/schema-json.
• Standard Schema compatible integrations such as TanStack Form and T3 Env.

Repository Layout

libs/          publishable @cleverbrush/* packages
demos/         demo applications and e2e setup
websites/      docs, schema site, playground, and shared website UI
scripts/       build, release, docs, and website helper scripts

The repository uses npm workspaces, Turborepo, TypeScript, Biome, Vitest, and ES modules.

Development

Use Node.js 24 or newer and npm 11. Install the Node version in .nvmrc.

npm ci
npm run lint
npm run build
npm run test

Useful targeted commands:

npx vitest --run libs/schema
npm run typecheck:schema-site
npm run typecheck:docs-site
npm run build:schema-site
npm run build:docs-site

The demo app can be started with:

npm run dev:demo

This starts the todo backend, frontend, and local database stack used by the demo workflow.

Documentation

• Migrating from v4.x to v5

• Security guidance

• Framework docs: https://docs.cleverbrush.com

• Schema docs and playground: https://schema.cleverbrush.com

• Standard Schema: https://standardschema.dev

Each package also has local source, tests, and exports under libs/.

Generate the API reference from the current package sources and READMEs:

npm run build
npm run docs
npm run docs:snapshot

Generation writes websites/docs/public/api-docs/latest/ using the next version planned by pending changesets, or the shared package version when none remain. It leaves package versions, changelogs, and changesets untouched. The snapshot command archives that output under v<version>/ and updates the version picker. It rejects stale output and existing snapshots. Commit the numbered archive; latest/ is generated during the docs container build and remains ignored by Git. To generate and archive an explicit version, set VERSION=1.2.3 for both documentation commands.

Quality Gates

Every change should leave these commands passing:

npm run lint
npm run build
npm run test

Website changes should also run the relevant site typecheck or build command. Published package behavior changes require a changeset.

Release

This repository uses Changesets and fixed-version package releases. Add a changeset with your package changes:

npm run changeset

After merging to master, the release workflow opens a version PR that runs npm run version. Merging that PR runs npm run release to publish on npm. Documentation generation does not require either command.

For beta releases:

npm run publish:beta

License

All Framework libraries are licensed under BSD-3-Clause. See LICENSE. Each published package includes the same license text; npm run test:packages verifies license text and metadata in both source packages and installed tarballs.