🧰 Getting started
typeCAD/pcb designs circuit boards in TypeScript: you write code, and the build produces a KiCAD project — board, schematic, netlist, and BOM — that you open in KiCAD for the final visual layout pass.
🧰 Requirements
Make sure your system has the required software. KiCAD and Node.js are the only hard requirements; everything else is optional depending on how you work.
Example first
| Software | Notes | Link |
|---|---|---|
| KiCAD | version 10.0 — required for the part libraries and the final layout pass; the build, checks, and gerber export run without it | kicad.org |
| npm / Node.js | version 18 or later — required | nodejs.org |
| Visual Studio Code | Not required, but highly recommended — new projects bundle the typeCAD/pcb extension (board viewer, pin hovers) | code.visualstudio.com |
| typeCAD/hal | Optional — firmware projects scaffolded by create use it | typecad.dev/hal/docs |
| git | Optional — used for version control features; keep git in your PATH | git-scm.com |
| ngspice | Optional — used for circuit simulations, see the Simulation page | ngspice.sourceforge.io |
📦 Create a project
One command scaffolds a project. You'll be prompted for the project name, whether to also scaffold a typeCAD/hal firmware project (and its board target), and whether to create a git repository.
Example first
npx @typecad/pcb createNo install step — npx fetches the package and scaffolds the project. The project
is created in the current directory, including a VSCode workspace file — open it
and the project comes up ready to work. All the prompts can also be passed as flags:
npx @typecad/pcb create --name=typecad_project --git=false --hal=false--help npx @typecad/pcb create --help
Lists every parameter for scripted project creation.
➡️ Build
Builds the project: runs the TypeScript entry file and generates the KiCAD outputs into ./build/. Run it from the hw/ directory, or click the build script in VSCode's NPM Scripts sidebar.
Example first
npx @typecad/pcb buildProject layout
| Path | What it is |
|---|---|
| hw/ | The project directory — build commands run from here |
| hw/src/index.ts | The TypeScript entry file your board is defined in |
| hw/typecad.conf.ts | Optional build configuration (entry, KiCAD paths, verbosity) |
| build/ | Generated output — .kicad_pcb, .kicad_sch, .net, and BOM .csv |
🧩 VSCode
Not required, but the recommended editor. The generated workspace file opens the project with everything wired up — including the bundled typeCAD/pcb extension, installed workspace-scoped so it never touches your global setup. It adds pin hovers, a board viewer panel with Gerber and assembled-board views, and click-through cross-probing between board and source. The NPM Scripts sidebar also exposes the CLI as clickable scripts — build and Add Component are the two you'll use constantly.
Example first
npx @typecad/pcb add componentWhat the extension gives you day-to-day — hovers, viewer, cross-probing — is covered on The VS Code extension page.
add component asks for the symbol/footprint source — the installed KiCAD library,
a local file, or an EasyEDA/JLCPCB C### part — then generates a typed [component].ts file with usage instructions. There's no need to add passives
(resistors, capacitors, etc.) this way — they come built into @typecad/pcb.
⌨️ The CLI
All commands are accessed through the typecad-pcb binary that ships with @typecad/pcb.
Every command supports --json for machine-readable output, --help for usage, and --version.
Example first
| Command | What it does |
|---|---|
| create | Scaffold a new project (interactive, or fully scripted with flags) |
| build | Run the entry file and generate the KiCAD outputs into ./build/ |
| add component | Generate a component .ts file from KiCAD, a local file, or JLCPCB |
| add package | Scaffold a reusable, publishable typeCAD package |
| search | Fuzzy-search the KiCAD symbol libraries |
| import | Convert an existing .kicad_pcb file into typeCAD TypeScript |
| diff | Visually diff two KiCAD PCB files, netlists, and BOMs |
| doc | Generate HTML documentation from Markdown and PCB files |
| doctor | Verify the environment; --fix attempts automatic fixes |
| validate | Check source code without a full build |
| drc / erc | Run the built-in design and electrical rule checks — --kicad for KiCad's own |
| --json / --help / --version | Global options on every command |
Something here unclear or out of date? Open an issue — we'd rather hear about it.