Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (88 loc) · 3.42 KB

CONTRIBUTING.md

File metadata and controls

125 lines (88 loc) · 3.42 KB

Contributing to @cleverbrush/framework

Thanks for your interest in contributing! This guide will help you get started.

Prerequisites

  • Node.js 20 or later (22 recommended — see .nvmrc)
  • npm (ships with Node)

Getting Started

# 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 test

Monorepo Structure

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 Cron-like job scheduler with schema-validated config
@cleverbrush/knex-clickhouse Knex dialect for ClickHouse

Development Workflow

Code Style

Biome handles both formatting and linting:

# Check for lint/format issues
npm run lint

# Auto-fix issues
npm run lint:fix

Testing

Tests 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

Building

# Build all packages (respects dependency order via Turbo)
npm run build

# Clean all build artifacts
npm run clean

Adding a Schema Extension

The extension system is the primary way to add new validators. See libs/schema/src/extensions/ for examples.

  1. Create your extension file (e.g. libs/schema/src/extensions/myExtension.ts)
  2. Export extension functions that call the builder's .extend() method
  3. Add tests in a co-located *.test.ts file
  4. Re-export from libs/schema/src/extensions/index.ts

Look at libs/schema/src/extensions/string.ts for a complete example of how extensions add validators like email(), url(), uuid(), etc.

Adding a New Builder

Builders live in libs/schema/src/builders/. Each builder extends the base SchemaBuilder class.

  1. Create your builder file in libs/schema/src/builders/
  2. Extend SchemaBuilder with appropriate type parameters
  3. Add a factory function (e.g. myType()) and export it
  4. Add comprehensive tests in a co-located *.test.ts file
  5. Export from libs/schema/src/index.ts

Pull Request Process

  1. Fork the repo and create a feature branch from master
  2. Make your changes with tests
  3. Add a changeset — every PR that changes package behavior needs one: 
    npx changeset
    Follow the prompts to select affected packages and describe the change.
  4. Ensure all checks pass: 
    npm run lint
npm run build
npm run test
  5. Open a PR against master

Changeset Guidelines

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

Questions?

Open a GitHub issue — we're happy to help.