Building a Static Site
tsci build --site
packages your tscircuit project into a static website that anyone can browse without running a server. The command evaluates your circuits, exports the generated assets into a dist
folder, and wires them up to the tscircuit RunFrame viewer so visitors can flip between PCB, schematic, and 3D previews right in the browser.
The Common tscircuit gallery is an example of a site generated with this workflow.
Prerequisites
Before building a site, make sure you have:
- A tscircuit project with one or more
*.circuit.tsx
files or another supported entrypoint. - The tscircuit CLI installed (
npm install -g tsci
,bunx tsci
, ornpx tsci
). - Any dependencies that your circuits import (registry components, local packages, etc.).
Building the site
Run the build command from the root of your project:
# generates dist/index.html and other assets
npx tsci build --site
The CLI resolves your entrypoint, evaluates every circuit, and then writes a static site to dist/site/
alongside the usual dist/circuit.json
outputs. The generated folder contains:
index.html
– a ready-to-host viewer.lib/…/circuit.json
– one JSON file per design so the viewer can lazy load each project.- Supporting JavaScript, CSS, and WebAssembly bundles for the RunFrame UI.
You can inspect the result locally with any static file server, for example:
npx serve dist
Opening http://localhost:3000
(or the port reported by your static server) shows the same interactive viewer experience used at common.tscircuit.com.
Customizing the catalog
The site automatically lists every circuit that tsci build
evaluates. If you already use a tscircuit.config.json
file, the same settings shape the static catalog: mainEntrypoint
lets you pick a custom starting file, and the existing include/exclude patterns limit which *.circuit.tsx
sources are exported.
When you add extra documentation or screenshots, keep them in a public asset folder (for example public/
), then point to them from your circuits. Static assets referenced at build time are copied into dist
so they ship with the site bundle.
Deploying to Vercel
Vercel can host the generated site without any special adapters:
- Push your project to GitHub or GitLab.
- Create a new Vercel project that points to the repository.
- Set the Build Command to
npx tsci build --site
(orbunx tsci build --site
if you prefer Bun). - Set the Output Directory to
dist
. - Trigger a deploy – Vercel runs the build, uploads the static folder, and serves it on your chosen domain.
For preview deployments, Vercel repeats these steps on every pull request so reviewers can browse the circuits before merging.
Deploying elsewhere
Because the output is plain HTML/JS/CSS, you can host it almost anywhere:
- GitHub Pages – run
npx tsci build --site
in CI and publish thedist
folder togh-pages
. - Netlify – configure the build command and output directory just like Vercel.
- S3/CloudFront or static buckets – upload the generated files with
aws s3 sync dist s3://your-bucket
.
Once deployed, the site stays fast and inexpensive to serve because no server-side rendering or API proxy is required—the viewer fetches the prebuilt circuit.json
files directly from storage.