circuit-json-to-step

Convert Circuit JSON to STEP format for CAD integration.

Installation

npm install circuit-json-to-step
# or
bun add circuit-json-to-step

Usage

Basic Example

import { circuitJsonToStep } from "circuit-json-to-step"

const circuitJson = [
  {
    type: "pcb_board",
    pcb_board_id: "pcb_board_1",
    width: 20,
    height: 15,
    thickness: 1.6,
    center: { x: 0, y: 0 },
  },
  {
    type: "pcb_hole",
    pcb_hole_id: "pcb_hole_1",
    hole_shape: "circle",
    hole_diameter: 3.2,
    x: 2.5,
    y: 2.5,
  },
]

const stepText = await circuitJsonToStep(circuitJson, {
  boardWidth: 20,
  boardHeight: 15,
  boardThickness: 1.6,
  productName: "MyPCB",
})
await Bun.write("output.step", stepText)

Assemblies

circuitJsonToStep(circuitJson) exports the complete design by default and always returns one STEP string. The file contains one named parent assembly with separate named children for the PCB, printed parts, ordinary assembly parts, and PCB component models. Touching parts remain separate bodies. The converter does not create ZIP archives or filename-to-content maps.

const stepText = await circuitJsonToStep(circuitJson, {
  productName: "My device",
  fsMap: { "./models/bracket.step": preloadedStepText },
})
await Bun.write("my-device.step", stepText)

JSCAD and imported STEP parts retain their geometry, colors, model origins, uniform unit scales, rotations, and placements. Each CAD model becomes a named child; multiple models can share the same part name. PCB components and imported STL, OBJ, GLB, and GLTF printed parts use the existing scene geometry converter. Mesh bodies share their vertices and edges. Failed external meshes, unsupported or missing geometry produce an error instead of a partial assembly. Relative STEP paths must be provided as plain STEP text in fsMap, keyed by the exact model_step_url; uncached STEP files require an HTTP(S) URL. Imported STEP files that contain their own assembly occurrences are rejected with the offending part name; nested imported assembly hierarchies are not yet supported.

Multi-board assemblies include every board, named by its pcb_board_id; a single board retains the name "PCB". Holes use explicit board/subcircuit ownership when available, or their location when exactly one board contains them. Ambiguous hole ownership is an error. PCB components infer board thickness from a unique subcircuit match; ambiguous ownership with different board thicknesses is an error.

Omitting exportMode always selects the complete assembly, including PCB-only designs with component models, mixed PCB and assembly designs, printed-only designs, multiple boards, and CAD models without source components. No special part tags or component-inclusion flags are required for the default export. Passing exportMode: "assembly" is equivalent to omitting it.

exportMode: "pcb" retains the existing PCB behavior. includeComponents and includeExternalMeshes default to false in PCB mode. Assembly mode includes all CAD parts and PCB components; includeExternalMeshes defaults to true for its non-STEP mesh fallback. productName defaults to "PCB" in PCB mode and "Combined Assembly" in assembly mode. Empty assemblies produce an error.

This changes the assembly-mode return type from Record<string, string> to string. Consumers should download that string as a single .step file.

Related Projects

• circuit-json - Circuit JSON specification
• stepts - STEP file generation library
• tscircuit - Design circuits with code

License

MIT