tscircuit: designing PCBs in TypeScript and React with the tsci CLI

What tscircuit actually replaces in a hardware workflow

The README frames the project as "React for Electronics": you write TypeScript and JSX, and instead of rendering a web page you render a board that can be manufactured. The intended user is a software developer, not a hardware engineer with a schematic capture tool open on a second monitor. The pitch is that electronics development should feel like web development, with code in your IDE and changes appearing in real time.

The practical consequence is that a circuit becomes a text file you can diff, review in a pull request and reuse as a component. The README points to a keyboard as an example of something designed this way, and the repository layout backs the claim: the package ships a library, a CLI binary, a registry and an online editor rather than a single desktop application. If your team already has TypeScript tooling, linting and CI, the circuit definition joins that pipeline instead of sitting outside it.

How JSX becomes a board: React Fiber, core and runframe

The README states that tscircuit uses React Fiber, the same rendering mechanism behind React Native and react-three-fiber, to render PCBs and schematics. Elements such as chip, resistor, capacitor, ground and trace play the role that div and span play in a web app. A board element carries physical dimensions, and children carry placement coordinates plus a footprint name.

The package.json shows how the pieces are wired. The published package depends on @tscircuit/core, @tscircuit/cli, @tscircuit/eval and @tscircuit/runframe, and the upgrade-deps script updates all four together, so the version you get from npm is a bundle of those sub-projects rather than a single self-contained renderer. The build script copies a standalone runframe bundle and an eval web worker into dist, which is what lets the same circuit render in a browser preview and inside the CLI dev server. The exports map exposes a browser build at ./browser alongside the default entry point.

The README also shows that rendering is not limited to the CLI. A Schematic component from @tscircuit/schematic-viewer can be dropped into an ordinary React page next to regular web markup, which means a circuit viewer can live inside an existing web application.

Installing the tsci CLI and rendering a first board

The README's quickstart is a global npm install followed by the dev command. The package.json declares two binaries, tsci and tscircuit, both pointing at cli.mjs, so either name works on the command line.

npm install -g tscircuit

tsci dev

The README says to open your browser at http://localhost:3020 after starting the dev server. That port is the one the documentation gives; do not assume it is configurable, because the README does not describe a port flag.

A minimal circuit in the README's style places a component, a resistor, a ground and two traces. The trace path strings use a dotted reference syntax that names the component and then the pin, for example .U1 > .D0 for pin D0 on U1 and .R1 > .left for the left terminal of R1.

const Circuit = () => (
  <board width="50mm" height="50mm" center_x={0} center_y={0}>
    <MySubcomponent name="U1" center={[0, 0]} footprint="sot236" />
    <resistor
      x={2}
      y={-0.5}
      name="R1"
      resistance="10ohm"
      footprint="0805"
      pcb_x="4mm"
      pcb_y="-1mm"
    />
    <ground x={3} y={1} name="GND" />
    <trace path={[".U1 > .D0", ".R1 > .left"]} />
    <trace path={[".R1 > .right", ".GND > .gnd"]} />
  </board>
)

Two further commands matter once the design is more than a test. The README lists tsci add for pulling registry packages into a project and tsci push for publishing subpackages back to the registry. Neither is documented in the README beyond that one-line description, so budget time to read the docs site before relying on them in a release process.

Placement is manual, and the autorouter is unfinished

The README answers the placement question directly: you should specify pcbX and pcbY for components, nesting them inside group elements for convenience. Automatic placement in the style of flexbox or CSS Grid is described as something the project is working on, with the promise that manual overrides will remain possible wherever automatic placement happens. Until that lands, a board with fifty parts means fifty coordinate decisions, and moving one part does not reflow its neighbours the way a web layout would.

Autorouting gets a similarly candid answer. The README says the team is working towards a state-of-the-art web-based autorouting algorithm and points readers to a separate blog for progress. Simplified, extensible auto-routing is listed as a feature, but the FAQ does not claim it is finished. For a two-layer board with a handful of nets this is probably fine. For a dense design where routing decisions determine whether the board works, treat the autorouter as a starting point you will edit, not a finished result.

A second limitation is quieter. The README's example uses MySubcomponent and a footprint named sot236 without defining either. Footprints have to come from somewhere, whether you write them, import them from a third-party site as the feature list mentions, or generate them from text using the linked AI tool. The README does not explain what happens when a footprint you need does not exist, and it does not document rollback or versioning for published registry packages.

tscircuit compared with KiCad and the code-first alternatives

KiCad is the obvious reference point: a mature desktop schematic and PCB editor with a graphical canvas, a symbol library and a router that engineers have used on production boards for years. The difference is not features, it is the artifact. In KiCad the design lives in project files edited through a GUI; in tscircuit it lives in TypeScript source edited in an IDE. That makes tscircuit better suited to code review and worse suited to the kind of spatial editing where dragging a part with a mouse is faster than typing coordinates.

Among code-first tools, the comparison that matters is how much of the electronics domain is modelled for you. tscircuit's answer is a component vocabulary (resistor, capacitor, chip, trace, ground) plus a registry and package manager, so a subcircuit can be published and reused the way an npm package is. The trade-off is coupling: the package.json pins the CLI, core, eval and runframe together, so upgrading means moving all of them at once through the upgrade-deps script. A team that wants to control each layer separately will find that arrangement restrictive.

Licence, release cadence and upgrade cost

The repository is MIT-licensed, and the README states that tscircuit is completely free and MIT-licensed open source. MIT is permissive: it allows commercial use and modification, and it requires that the copyright notice and licence text be preserved. That is the general shape of the licence, not legal advice for your situation; if you are shipping a product that embeds the library, have your own counsel read the LICENSE file at the repository root.

The version in package.json is 0.0.2561. A zero-major version with a four-digit patch number signals frequent releases and no stability promise on the API. The repository has no retrieved releases, so you cannot plan upgrades by reading release notes, and nothing in the README describes a deprecation policy for the core package. The upgrade-deps script is the project's own answer to keeping the four @tscircuit packages aligned, which implies that mismatched versions are a real failure mode rather than a theoretical one. Expect to pin versions and re-test your board render after each bump.

What to check before you commit a design to tscircuit

The README is explicit that you can export Gerbers, Pick'n'Place and BOM for manufacturing, and it links to a guide on understanding fabrication files. That export step is the one to verify first, because it is the boundary between a rendered preview and a board a factory will build. The README does not document design rule checks, layer stack configuration or a preview of the fabrication output, so confirm those in the docs site rather than assuming they exist.

A second check is the registry. tsci add and tsci push are listed as features with a single line each, and the registry is central to the reuse story: a subcomponent you publish is only useful if someone else can pull it and get the same footprint. If your parts are custom, the value of the registry drops sharply and you are left with the rendering and export pipeline, which is still a reasonable reason to use the tool.

The third check is your own tolerance for manual placement. Open a board roughly the size of a real project, place the parts by hand with pcbX and pcbY, and route it. If that exercise is pleasant, tscircuit fits. If it is not, no amount of React familiarity will make up for it.

Editorial conclusion

Adopt tscircuit if your team already writes TypeScript and wants circuit definitions in the same IDE, review flow and version control as the rest of the codebase, and if you are willing to place components by hand with pcbX and pcbY. Do not adopt it if you need an autorouter you can trust on a dense board, because the README describes the autorouter as something the project is still working towards. Before committing, install the CLI, run tsci dev, and confirm that the parts you need exist as footprints in the registry; then export Gerbers, Pick'n'Place and BOM from a small board and check them against your fabricator's requirements.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository