kicadts

kicadts is a TypeScript-first toolkit for reading, editing, and generating KiCad S-expression documents. Every KiCad token is modeled as a class, so you can compose schematics, boards, and footprints entirely in TypeScript and emit KiCad-compatible files with deterministic formatting.

Local Setup

This repository uses Bun for scripts and testing.

bun install
bun test — optional, but handy to confirm we still round-trip the KiCad demo files

Build KiCad Schematics

The high-level classes (KicadSch, Sheet, SchematicSymbol, Wire, …) expose setters and getters for their children. Populate the model, then call getString() to emit KiCad’s S-expression.

import { promises as fs } from "node:fs"
import {
  At,
  KicadSch,
  Paper,
  Property,
  Sheet,
  SchematicSymbol,
  TitleBlock,
  Wire,
  Pts,
  Xy,
} from "kicadts"

const schematic = new KicadSch({
  version: 20240101,
  generator: "kicadts-demo",
  titleBlock: new TitleBlock({
    title: "Demo Schematic",
    company: "Example Labs",
  }),
  paper: new Paper({ size: "A4" }),
  properties: [new Property({ key: "Sheetfile", value: "demo.kicad_sch" })],
  sheets: [
    new Sheet({
      position: [0, 0, 0], // Can use array instead of new At([0, 0, 0])
      size: { width: 100, height: 80 },
    }),
  ],
  symbols: [
    new SchematicSymbol({
      libraryId: "Device:R",
      at: { x: 25.4, y: 12.7 }, // Can use object instead of new At([25.4, 12.7])
    }),
  ],
  wires: [
    new Wire({
      points: new Pts([new Xy(0, 0), new Xy(25.4, 12.7)]),
    }),
  ],
})

await fs.writeFile("demo.kicad_sch", schematic.getString())

Build KiCad PCBs

Boards follow the same pattern. Compose KicadPcb with nets, footprints, segments, and zones. Footprints are reusable whether you embed them on a board or export them as .kicad_mod files.

import { promises as fs } from "node:fs"
import {
  At,
  Footprint,
  FootprintPad,
  FpText,
  KicadPcb,
  PadLayers,
  PadNet,
  PadSize,
  PcbNet,
  TextEffects,
} from "kicadts"

const netGnd = new PcbNet(1, "GND")
const netSignal = new PcbNet(2, "Net-(R1-Pad2)")

const makeText = (
  type: string,
  text: string,
  x: number,
  y: number,
  layer: string
) =>
  new FpText({
    type,
    text,
    position: { x, y },
    layer,
    effects: new TextEffects({
      font: { size: { height: 1, width: 1 }, thickness: 0.15 },
    }),
  })

const pad = (number: string, x: number, net: PcbNet) =>
  new FootprintPad({
    number,
    padType: "smd",
    shape: "roundrect",
    at: { x, y: 0 },
    size: { width: 1.05, height: 0.95 },
    layers: ["F.Cu", "F.Paste", "F.Mask"],
    roundrectRatio: 0.25,
    net: new PadNet(net.id, net.name),
    pinfunction: number,
    pintype: "passive",
  })

const pcb = new KicadPcb({
  version: 20240101,
  generator: "kicadts-demo",
  nets: [netGnd, netSignal],
  footprints: [
    new Footprint({
      libraryLink: "Resistor_SMD:R_0603",
      layer: "F.Cu",
      position: { x: 10, y: 5, angle: 90 },
      fpTexts: [
        makeText("reference", "R1", 0, -1.5, "F.SilkS"),
        makeText("value", "10k", 0, 1.5, "F.Fab"),
      ],
      fpPads: [pad("1", -0.8, netGnd), pad("2", 0.8, netSignal)],
    }),
  ],
})

await fs.writeFile("demo.kicad_pcb", pcb.getString())

Build Stand-Alone Footprints

Footprints can live outside a board file (for library .kicad_mod entries). Populate Footprint and write the S-expression to disk.

import { promises as fs } from "node:fs"
import {
  At,
  Footprint,
  FootprintPad,
  FpText,
  PadLayers,
  PadSize,
  TextEffects,
} from "kicadts"

const footprint = new Footprint({
  libraryLink: "Demo:TestPad",
  layer: "F.Cu",
  position: [0, 0], // Array format
  fpTexts: [
    new FpText({
      type: "reference",
      text: "REF**",
      position: { x: 0, y: -1.5 },
      layer: "F.SilkS",
      effects: new TextEffects({
        font: { size: { height: 1, width: 1 }, thickness: 0.15 },
      }),
    }),
  ],
  fpPads: [
    new FootprintPad({
      number: "1",
      padType: "smd",
      shape: "rect",
      at: [0, 0], // You can also use { x, y } form
      size: { width: 1.5, height: 1.5 },
      layers: ["F.Cu", "F.Paste", "F.Mask"],
    }),
  ],
})

await fs.writeFile("Demo_TestPad.kicad_mod", footprint.getString())

Load Existing KiCad Files

Use the specialized parse functions to load and validate schematics, boards, or footprints. Each function ensures the root element is the expected type.

import { promises as fs } from "node:fs"
import { parseKicadSch, parseKicadPcb, parseKicadMod } from "kicadts"

// Load and modify a schematic
const schematic = parseKicadSch(await fs.readFile("existing.kicad_sch", "utf8"))
schematic.generator = "kicadts"
await fs.writeFile("existing.kicad_sch", schematic.getString())

// Load and modify a PCB
const pcb = parseKicadPcb(await fs.readFile("existing.kicad_pcb", "utf8"))
pcb.generatorVersion = "(generated programmatically)"
await fs.writeFile("existing.kicad_pcb", pcb.getString())

// Load and modify a footprint
const footprint = parseKicadMod(await fs.readFile("Demo_TestPad.kicad_mod", "utf8"))
footprint.descr = "Imported with kicadts"
await fs.writeFile("Demo_TestPad.kicad_mod", footprint.getString())

For generic S-expression parsing, use parseKicadSexpr which returns an array of SxClass instances. Any class exposes getChildren() if you need to walk the tree manually, and snapshot tests (bun test) ensure the emitted S-expression stays identical to KiCad's own formatting.