Design a complete breadboard project. We send you the kit to build it.
The website, the in-browser circuit editor, and the platform behind Breadboard, a Hack Club YSWS program.
Live site: breadboard.hackclub.com
Source
Table of Contents
Breadboard is a Hack Club YSWS program (You Ship, We Ship). A teen designs a real breadboard circuit, and a component kit gets mailed to them for free so they can build it.
Design it in the editor, submit the design, a reviewer approves it, we ship the kit, you build it, film a demo, submit again, and get paid in bread.
Designing a circuit on paper and hoping it works is a bad first experience for someone who has never touched a breadboard. When the design is a circuit that runs, you find your own wiring mistakes before a single part is mailed, and the kit arrives for something you've already seen work. That's why most of this repo is a simulator.
The program also pays for the hours you put in, so the editor counts them while you work and builds a timelapse of the circuit as it grows. Nobody has to fill in a spreadsheet at the end.
Next.js 16 on the App Router with React 19, TypeScript, Tailwind CSS 4, and Bun as the runtime and package manager. Postgres through Drizzle ORM. Auth is Better Auth with Hack Club as the OAuth provider, plus GitHub OAuth for publishing. Feature flags are GrowthBook. Charts are Recharts, the code editor is Monaco, the serial console is xterm, editor state is Zustand, and the 3D board on the landing page is Google's <model-viewer>.
The simulator runs in the browser: avr8js for AVR, rp2040js for the Pico, ngspice compiled to WASM for analog, and @wokwi/elements plus local custom elements for the parts.
editor-backend/ is a separate FastAPI service that shells out to arduino-cli and ESP-IDF to compile, and to QEMU to emulate the boards that don't run in a browser. Both halves build to Docker images in GitHub Actions and deploy to Hack Club's Orchard. Screenshots and evidence frames go to S3-compatible storage.
The landing page, the docs, and the gallery are open to anyone. The docs are what you read before submitting: requirements, breadboard basics, an LED workshop, the firmware guide, and how to journal your build.
Logging in with Hack Club gets you the editor and the shop. In the editor you wire a board on the canvas, write the code, compile it for real, and run it, with Arduino, Pico, ESP32, STM32, and Raspberry Pi boards supported and analog parts solved by SPICE. When the design works you submit it, and once it's approved the kit ships. You build it, film a demo, and submit that.
- Bun 1.3.6
- Postgres 16, or Docker to run the one in
docker-compose.yml - Docker, to compile firmware locally (the editor backend image ships arduino-cli and ESP-IDF)
bun install
cp .env.example .env.local
bun run db:migrate.env.example documents every variable and what happens when it's blank. Most integrations no-op without credentials, so a useful local install needs DATABASE_URL, BETTER_AUTH_SECRET, and the Hack Club OAuth pair.
bun dev # Next.js on http://localhost:3000
bun run editor:backend:docker # compile + emulate backend on :8001The site, the platform, and the schematic side of the editor work without the backend. Compiling and running firmware needs it. ESP32 and Raspberry Pi emulation also needs QEMU libraries, either prebuilt in editor-backend/prebuilt/qemu or fetched at image build time with VELXIO_LICENSE_KEY.
Everything at once, in containers:
make up # postgres + editor backend + next
make logs
make help # the restbun run lint # Biome
bun run format
bun test # simulation regression tests
cd editor-backend && pytest # backend tests (pytest isn't pinned in requirements.txt)Lint with bun run lint or the pinned binary in node_modules. npx biome resolves an ancient version that passes everything.
bun run db:generate # migration from schema changes
bun run db:migrate
bun run db:studioTanishq Goyal - @Tanuki on the Hack Club Slack - tanishq@hackclub.com
Program questions go to #breadboard.