SketchForge engine

@constructorfleet/sketchforge-engine is the TypeScript package for SketchForge's project model and geometry operations. It is intended for Node.js applications that need to read or change SketchForge projects, construct parameterized shapes, or import and export geometry without running the web editor.

Node compatibility

The package manifest declares Node.js 20 or newer, but that range is broader than the runtime supported by its full geometry stack: the locked brepjs dependency requires Node.js 24 or newer. Use Node.js 24+ for the complete engine, including exact CAD and kernel-backed operations. On Node.js 20–23, npm may warn about the dependency engine requirement, and full engine behavior is unsupported. The package's engine range should be aligned with this dependency in a future package release.

Installation

npm install @constructorfleet/sketchforge-engine

The package is ECMAScript modules (ESM). TypeScript declarations ship with the package; no separate @types package is needed.

Quick start

Build a shape from parameters without starting the editor or opening a project:

import { shapeFromRequest } from "@constructorfleet/sketchforge-engine";

const shape = shapeFromRequest({ kind: "box", width: 20, depth: 10, height: 5 });
if (!shape) throw new Error("The requested shape could not be built");
console.log(shape.kind, shape.width, shape.depth, shape.height);

The shape request is plain data and can be stored or passed to createEngine. shapeFromRequest returns null for kinds that cannot be created from parameters alone (for example, a mesh with no geometry).

To run project operations, bind an engine to the directory store used by SketchForge:

import { createEngine, directoryProjectStore } from "@constructorfleet/sketchforge-engine";

const projectsDirectory = process.env.SKETCHFORGE_PROJECTS_DIR;
if (!projectsDirectory) throw new Error("Set SKETCHFORGE_PROJECTS_DIR to the project directory");
const engine = createEngine(directoryProjectStore(projectsDirectory));
const result = await engine.project("project-id");
if (!result.ok) throw new Error(`Could not read project: ${result.failure.reason}`);
console.log(`Revision ${result.value.revision}; ${result.value.shapes.length} shapes`);

Set SKETCHFORGE_PROJECTS_DIR to the directory already used by SketchForge, and replace project-id with an existing project ID. The directory must contain projects in the supported on-disk format. Keep access to that directory restricted to trusted local code: this package is a geometry/project library, not an HTTP service or an access-control boundary.

Public API

The package root is the supported import surface. Its main engine facade is Engine, created with createEngine(store). Every operation returns an EngineResult<T>; check ok before reading value or failure.

Area	Engine methods	What they do
Read and edit a project	project, addShapes, changeShape, removeShape	Read placed shapes and project metadata; add parameterized shapes or change/remove an existing shape.
Arrange and repeat	align, distribute, pattern, mirrorBaked	Place selected shapes on a shared axis, spread them, create linear/circular copies, or mirror supported solids.
Import and combine	importMesh, cut, group, ungroup, separate, explode	Import model files, subtract/group solids, split groups/bodies, or explode a retained STEP assembly.
Inspect and measure	edges, faces, measurements, properties, measureBetween, interference	Query exact geometry topology, shape properties, distances/angles, and gaps/overlaps.
Modify exact geometry	treat, draftPrism, shell, changeShape	Apply edge treatments, draft an extruded prism, retain bounded sketch face drafts, or hollow a shape.

These operations address an existing project ID in a ProjectStore; this package does not create projects, project records, or initialize a project directory. addShapes is the first write operation for a project that already exists. All writes persist to the configured store.

The main entry point also exports these API areas:

• Projects and operations: directoryProjectStore, createEngine, Engine, EngineResult, EngineFailure, project and operation request/result types.
• Shape requests: shapeFromRequest, shapeWithRequestedChanges, REQUESTABLE_SHAPE_KINDS, plus types describing parameterized shapes.
• Project files and exchange: .skf import/export and inspection; mesh import; STEP and scene export; SVG/DXF section output; STEP assembly explosion.
• Geometry and CAD: primitive builders, exact solids, sectioning, topology analysis, shape bounds, CAD measurements, shelling, edge treatments, wall thickness, and projection layouts.
• Placement and repetition: align/distribute helpers, pattern placement helpers, shape bounds, mirror, canonicalization, and workplane hole-mode helpers.

See the generated TypeScript API reference for every symbol and declaration. The reference links back to this usage guide. Related documentation: REST API, project format, and TypeScript client.

Editing a sketch-backed feature

Sketch extrusions, revolves, and sweeps expose a stable sketchSourceId on the generated shape. Pass that ID to engine.changeShape(projectId, sketchSourceId, { sketchProfile }) to rebuild the feature. For a persisted sketch revolve, the same source ID also accepts operation-setting updates such as { sides: 64 }. A draft prism retains its draftPrismAngle; source edits accept { draftPrismAngle: 12 } and reapply the draft when the extrusion profile changes. Retained sketch extrusions, sweeps, and eligible revolves can store one face draft with { faceDraft: { sourceFaceId, angle, pullDirection } }; use the ID from engine.faces, and use null to clear it. Profile edits resolve the selected planar face by its stored normal and require exactly one match; they never carry the old face index forward. .skf round trips preserve the face draft and source frame. A single-loop sketch extrusion can combine one face draft followed by one all-edge fillet. A single-section, no-hole sketch sweep can combine one face draft followed by one all-edge fillet or one symmetric 45° all-edge chamfer. Sweep treatments replay the source, draft, then treatment on profile edits, including after archive import; tests cover the round trip, replay, unsupported angles, and atomic refusal. Sweep face drafts do not support multiple sections, section holes, selected-edge treatments, or additional treatments. A plain single-region full-turn sketch revolve can combine one face draft followed by either one symmetric 45° all-edge chamfer or one all-edge fillet; profile and setting edits replay the source, draft, then treatment, including after archive import. Other face-draft treatment combinations, prism drafts, and shelling remain unsupported. When the output is nested inside a baked boolean group, the engine updates the sketch output and recomputes its boolean ancestors from their retained operands before writing the project. Each rebuilt ancestor is placed through its group's frame the way ungrouping places the group's children, so a group that was moved, turned, mirrored or resized after creation keeps that placement, mirror and scale across the edit. The edit is atomic: invalid profiles, missing or ambiguous face matches, or a failed dependent rebuild leave the stored project unchanged.

This recomputation currently covers sketch-backed extrusions, revolves, and sweeps nested under boolean groups, plus a retained prism-draft angle applied to a sketch extrusion. Other downstream operations remain baked or unsupported for source-driven recompute, and a general-purpose feature graph is not yet available. .skf export preserves the updated sketch profile, draft angle, and recomputed boolean result.

Limitations

• The package does not provide the SketchForge web UI, HTTP routes, authentication, or a remote project client. Use the TypeScript client for the REST API.
• There is no package-level meshForShape dispatcher yet; use the primitive builders or exact-solid helpers for the specific shape kinds they support.
• The engine reads and writes SketchForge projects through a ProjectStore; directoryProjectStore is a local filesystem implementation. It expects valid project files and a directory managed with SketchForge's project conventions.
• Parameter-only shape creation does not create drawn sketches or arbitrary mesh geometry. Import mesh data through engine.importMesh or use the editor for drawing workflows.
• CAD, STEP, and exact-solid operations rely on native/WASM geometry dependencies and can be more resource-intensive than pure parameter and placement helpers. Kernel-specific modules are loaded when those operations run.
• Use the package root as the supported public API. The export map also permits subpath imports for compiled modules, but undocumented internal modules are not a compatibility promise.

License

This package is licensed under AGPL-3.0-only.

---

Documentation version: 1.30.0 · Repository revision: 1cb9fee8dff4d394684c229dd67a21da539d167f · View source