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 });
Copy

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
Copy

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
Copy

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
Copy

The demo app can be started with:

npm run dev:demo
Copy

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/.

Quality Gates

Every change should leave these commands passing:

npm run lint
npm run build
npm run test
Copy

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.

npm run changeset
npm run version
npm run release
Copy

For beta releases:

npm run publish:beta
Copy

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.