// 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));

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, phantom types that prove invariants at compile time. If it compiles, the geometry is valid. It's strongest at exact, manufacturable geometry — precise booleans, fillets, chamfers and shells; real volumes, areas and clearances; watertight solids that round-trip through STEP — from a single part to a full assembly (enclosures, brackets, fixtures, gridfinity bins, machined and molded parts). It isn't built for organic sculpting or dense lattices; that's what field-based (implicit/voxel) modeling is for.

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: brepjs models exact mechanical solids — parts and assemblies; freeform/organic sculpting and dense lattices are out of scope (that's field-based implicit/voxel territory).
• 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

Starting fresh? npm create brepjs my-project scaffolds a TypeScript app with the kernel and the declarative family layer preconfigured.

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
• Declarative Models: React-like parametric components (brepjs-families), key-path identity, IFC export
• 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

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-cad)

brepjs-cad helps an AI agent (or you) author 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)
   In a Claude Code session:
/plugin marketplace add andymai/brepjs
/plugin install brepjs@brepjs
   …or from a terminal, non-interactively:
claude plugin marketplace add andymai/brepjs
claude plugin install brepjs@brepjs
2. The runtime - the CLI the skill drives
npm i -D brepjs-cad

With the skill installed, ask Claude for a part in plain English, or drive the pipeline explicitly with /brepjs:cad "a 40×20×10 mm bracket with two M4 holes".

brepjs-cad 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 -p brepjs-cad brep 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. For MCP-capable agents the package also ships a stdio MCP server (brep-mcp) exposing the same build-and-verify step as a run_program tool. See the Authoring with AI guide for the full loop, CLI reference, the MCP server, examples, and the measurement eval.

Declarative models and BIM (brepjs-families + brepjs-bim)

brepjs-families is a React-like component layer over the CSG IR: parametric parts are prop-driven, composable, zod-validated components, and identical subtrees materialize once because the IR is content-addressed. brepjs-bim projects the same tree to IFC4 with stable GlobalIds derived from component key paths — walls, slabs, columns, beams, roofs, stairs, and real openings (IfcOpeningElement + IfcRelFillsElement).

const Wall = family('Wall', (p: WallProps) =>
  el('Box', { size: [p.length, p.thickness, p.height], voids: p.voids ?? [] })
);
const wall = Wall({ key: 'south', length: 4000, thickness: 200, height: 2700 });
const tree = resolve(Storey({ key: 'ground', items: [wall] }));
evaluateModel(tree, evaluator); // viewport meshes, one per key path
familiesToBim(tree, { project }); // IFC via brepjs-bim

npm create brepjs my-building   # scaffold a project
npx brepjs add room storey slab # copy in starter families (code you own)

See the Declarative Models guide.

Projects Using brepjs

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

Get in touch

I'm Andy Aragon — I build and maintain brepjs and the geometry kernels beneath it (occt-wasm, brepkit). Building something on brepjs and want a hand, or just have a question? Get in touch →

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Acknowledgements

brepjs.dev and the playground are hosted on Vercel through its Open Source Program.

License

brepjs itself is Apache-2.0. The kernel you register carries its own license, and a shipped product must comply with both brepjs's license and the registered kernel's:

| Package | License | What it means for your product | | ------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | brepjs (this package) | Apache-2.0 | Use freely, open or proprietary | | occt-wasm kernel | LGPL-2.1-only (WASM output; tooling MIT OR Apache-2.0) | Proprietary use permitted under the LGPL's terms | | brepkit-wasm kernel (3.0.0+) | AGPL-3.0-only or commercial | Open-source products use it freely under the AGPL; proprietary products need a commercial license from Collective Context, LLC |

brepkit-wasm versions through 2.129.x were published under MIT OR Apache-2.0 and remain available under those terms.