circuit-json-to-kicad

Convert Circuit JSON files to KiCad schematic (.kicad_sch), PCB (.kicad_pcb), and project (.kicad_pro) files.

Circuit JSON is an open-source file format for describing electronic circuits. This library enables you to generate KiCad-compatible files from Circuit JSON, allowing you to use KiCad's powerful PCB design tools with circuits defined in code.

Installation

``bash
npm install circuit-json-to-kicad


or


bun add circuit-json-to-kicad
`

Usage

$3

`typescript
import { CircuitJsonToKicadSchConverter } from "circuit-json-to-kicad"

// Assuming you have circuit JSON from tscircuit or another source
const circuitJson = / your circuit JSON /

const converter = new CircuitJsonToKicadSchConverter(circuitJson)
converter.runUntilFinished()

// Get the KiCad schematic file content
const kicadSchContent = converter.getOutputString()

// Write to file
Bun.write("output.kicad_sch", kicadSchContent)
`

$3

`typescript
import { CircuitJsonToKicadPcbConverter } from "circuit-json-to-kicad"

const circuitJson = / your circuit JSON /

const converter = new CircuitJsonToKicadPcbConverter(circuitJson)
converter.runUntilFinished()

// Get the KiCad PCB file content
const kicadPcbContent = converter.getOutputString()

// Write to file
Bun.write("output.kicad_pcb", kicadPcbContent)
`

$3

`typescript
import { CircuitJsonToKicadProConverter } from "circuit-json-to-kicad"

const circuitJson = / your circuit JSON /

const converter = new CircuitJsonToKicadProConverter(circuitJson, {
projectName: "my_project",
schematicFilename: "my_project.kicad_sch",
pcbFilename: "my_project.kicad_pcb",
})

converter.runUntilFinished()

const kicadProjectContent = converter.getOutputString()

Bun.write("my_project.kicad_pro", kicadProjectContent)
`

$3

`typescript
import { Circuit } from "tscircuit"
import {
CircuitJsonToKicadSchConverter,
CircuitJsonToKicadPcbConverter,
} from "circuit-json-to-kicad"

// Define your circuit
const circuit = new Circuit()
circuit.add(


name="C1"
capacitance="1uF"
footprint="0603"
connections={{ pin1: "R1.pin2" }}
/>
,
)

await circuit.renderUntilSettled()

// Get Circuit JSON
const circuitJson = circuit.getCircuitJson()

// Convert to KiCad schematic
const schConverter = new CircuitJsonToKicadSchConverter(circuitJson)
schConverter.runUntilFinished()
Bun.write("output.kicad_sch", schConverter.getOutputString())

// Convert to KiCad PCB
const pcbConverter = new CircuitJsonToKicadPcbConverter(circuitJson)
pcbConverter.runUntilFinished()
Bun.write("output.kicad_pcb", pcbConverter.getOutputString())
`

Features

- Schematic Conversion: Convert Circuit JSON to KiCad schematic files (.kicad_sch)
- Library symbols
- Component placement
- Wire routing
- Net connections

- PCB Conversion: Convert Circuit JSON to KiCad PCB files (.kicad_pcb)
- Footprint placement
- Trace routing
- Vias
- Board outlines and graphics
- Net assignments
- Project Generation: Produce KiCad project files (.kicad_pro) that reference the generated schematic and PCB outputs

Development

This project uses Bun as its runtime and package manager.

$3

- Bun (latest version)
- KiCad (for testing generated files)

$3

`bash


Install dependencies

bun install

Download KiCad demo files (used for reference)

bun run download-demos

Run tests

bun test
`

$3

Tests generate visual PNG snapshots for comparison:

`bash


Run a specific test

bun test tests/sch/basics/basics01.test.tsx

Run all tests

bun test

Update snapshots (if needed)

BUN_UPDATE_SNAPSHOTS=1 bun test
`

Generated debug output is saved to the debug-output/ directory.

$3

`
lib/
├── index.ts # Main exports
├── types.ts # Shared types
├── schematic/
│ ├── CircuitJsonToKicadSchConverter.ts # Schematic converter
│ └── stages/ # Conversion pipeline stages
└── pcb/
├── CircuitJsonToKicadPcbConverter.ts # PCB converter
└── stages/ # Conversion pipeline stages
``

About Circuit JSON

Circuit JSON is an open-source file format for representing electronic circuits. Learn more:

- Circuit JSON on npm
- Circuit JSON README
- tscircuit - Create circuits using React/TSX

License

MIT License - see LICENSE for details.

Some interoperability test artifacts are generated from assets by KiCad. See KiCad licenses for more information.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.