brepjs

CAD modeling for JavaScript.

▶ Try the live playground — write code, watch the solid render, and export STEP, all in your browser.

Getting Started · Cheat Sheet · Docs

Shapes are exact mathematical boundaries — not triangle meshes — so booleans are precise, measurements are real, and you can export to STEP. TypeScript types prove the geometry is valid at compile time.

// Drill a hole, fillet the vertical edges, export to STEP
import { box, cut, cylinder, fillet, edgeFinder, exportSTEP, unwrap } from 'brepjs/quick';

const b = box(30, 20, 10);
const hole = cylinder(5, 15, { at: [15, 10, -2] });
const drilled = unwrap(cut(b, hole));

const edges = edgeFinder().inDirection('Z').findAll(drilled);
const part = unwrap(fillet(drilled, edges, 1.5));

const step = unwrap(exportSTEP(part));

Why?

brepjs grew out of the love and care I put into gridfinitylayouttool.com. I needed parametric CAD in the browser and I'm not a 3D modeler, but I know TypeScript. OpenSCAD nailed code-first CAD but lives outside the JS ecosystem. replicad proved OpenCascade works in JS but I kept hitting performance walls and fighting the API.

Neither had the type safety I wanted, so brepjs leans hard on it: branded types, Result<T,E>, phantom types that prove invariants at compile time. If it compiles, the geometry is valid. Best for parts defined by parameters (enclosures, brackets, fixtures, gridfinity bins) rather than organic sculpting.

Scope

To set expectations, this project deliberately does not:

• Render or display geometry — brepjs produces shape data; pass mesh output to Three.js, Babylon.js, or raw WebGL for rendering.
• Support organic or sculpting workflows — the API is built for parametric parts (enclosures, brackets, fixtures); freeform sculpting is out of scope.
• Output SVG or 2D files — 2D drawing primitives exist solely as an intermediate step toward extruded 3D solids, not as a standalone 2D output format.
• Run server-side (SSR) — WASM requires a browser or Node.js environment with WASM support; server-side rendering frameworks (Next.js, Nuxt, Remix) need a client-only import.
• Provide a GUI — brepjs is a pure programmatic API; there is no visual editor, viewport, or file picker.

Status

occt-wasm (OpenCascade compiled to WebAssembly) is the default kernel. brepkit, a Rust-based kernel, is in active development as a faster replacement but not yet ready for production use. The kernel abstraction layer means switching is a one-line change. See benchmarks for performance comparisons.

Install

npm install brepjs occt-wasm

brepjs/quick handles WASM init automatically via top-level await (ESM only). Other options:

// Auto-detect kernel
import { init } from 'brepjs';
await init();

// Or manual setup
import { OcctKernel } from 'occt-wasm';
import { registerKernel, OcctWasmAdapter } from 'brepjs';
const kernel = await OcctKernel.init();
registerKernel('occt-wasm', OcctWasmAdapter.fromKernel(kernel));

Usage

The chapter-based guide is the recommended starting point:

• Why brepjs — what makes it different, who it's for
• Install & Initialize — three init styles, bundler notes
• Your First Solid — the canonical drill-fillet-export workflow
• Cheat Sheet — single-page reference
• Core Concepts — B-Rep, topology, types, kernels, tolerance
• Common Tasks — booleans, fillets, sketching, lofts, sweeps, finders, measurement, IO
• Three.js Integration — meshing and rendering
• Migration — coming from Replicad, OpenSCAD, or Three.js
• Extending brepjs — custom kernels, custom operations, architecture
• Reference — glossary, function lookup, error codes, ADRs
• API Reference (TypeDoc) — searchable type-level reference

Legacy single-page docs in ./docs/ remain available; the chapter site is the canonical location going forward.

Architecture

Layer 3  sketching/, text/, projection/   High-level API
Layer 2  topology/, operations/, 2d/ ...  Domain logic
Layer 1  core/                            Types, memory, errors
Layer 0  kernel/, utils/                  WASM bindings

Imports flow downward only. Boundaries are enforced in CI.

Authoring CAD with AI (brepjs-verify)

brepjs-verify helps an AI agent (or you) author parametric CAD in brepjs and prove it is correct before handing it off. An LLM can't see geometry — so it writes a .brep.ts part, runs it on a real kernel, and reads a deterministic report instead of guessing from how the code reads. It ships as two cooperating pieces: a Claude Code skill (the authoring loop) and a verification CLI (validity + measured dimensions + multi-view snapshots + STEP export).

Install both — they ride on two rails:

# 1. The skill — Claude Code plugin (delivered via this repo's marketplace)
/plugin marketplace add andymai/brepjs
/plugin install brepjs-verify@brepjs

# 2. The runtime — the CLI the skill drives
npm i -D brepjs-verify

brepjs-verify bundles its own brepjs + occt-wasm, so it runs in an empty directory; inside an existing brepjs project it prefers your installed versions so verified parts match what you ship. A model is a module that default-exports a zero-arg function returning a shape:

// bracket.brep.ts
import { box } from 'brepjs';
export const expected = { volume: 8000, tolerancePct: 1 }; // optional: assert intent
export default () => box(40, 20, 10, { centered: true });

npx -y brepjs-verify bracket.brep.ts --check --step bracket.step --json report.json

The command exits non-zero unless the report is ok (valid and every declared dimension within tolerance), so it drops straight into CI or an agent loop. See the Authoring with AI guide for the full loop, CLI reference, examples, and the measurement eval.

Projects Using brepjs

• Gridfinity Layout Tool: Web-based layout generator for Gridfinity storage systems

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache-2.0