A self-hosted visual designer for home-lab server racks. Pick a 19″ or 10″ rack (1–32U), drag hardware from a researched catalog of ~340 parts into it, put desktop gear on shelves, and check the totals: power vs UPS capacity, PoE budget, mains outlets, weight and ports. Export the result as PNG, SVG, PDF, CSV or JSON.
Runs as a single Docker container with a SQLite database, or as a desktop app for Windows and Ubuntu (download). No accounts and no cloud; it's built for your LAN.
- Detailed faceplates, front and rear: every device is drawn as SVG from catalog data: RJ45 jacks with link/activity LEDs and latch notches, metallic SFP/QSFP cages, USB, HDMI, IEC and AU/NZ power, keystones, drive trays, displays, vents, fans and PSUs. Popular gear has a researched, sourced layout; everything else gets a sensible generated one. No logos or product photos.
- Style presets: UniFi-style silver/white/black, server bezel, NAS grey, PDU, UPS, patch and brush panels and more, all fine in light and dark mode. Lit LEDs, or switch them off for a clean print look.
- Rack frames: 2-post, 4-post, enclosed cabinet (with glass door) and 10″ mini racks including the DeskPi RackMate T1 / T2, with rails, EIA hole spacing (square cage-nut holes, or round tapped #10-32 holes on the RackMate rails) and free-slot hints.
- Shelf plans: a top-down view of every shelf showing how devices fit side by side, with overhangs flagged.
- Placement: drag and drop with U snapping, collision checks, front / rear / full-depth mounting, partial-width gear and desktop gear on shelves. Warns when something is too wide, deep or tall for its shelf.
- Wall area: an optional wall beside the rack for wall-mounted gear: nbn connection boxes, modems, and data, TV, phone, fibre and power wall plates (AU/NZ single, double and USB power points, UK, EU Schuko and US outlets), cabled to the rack like anything else. The power points count towards the outlets the rack's gear needs.
- Power sources: USB-C, DC adapters, plug-packs and IEC inlets per device, checked against the outlets your power boards provide.
- Cables: colour-coded port-to-port patch cables, with tooltips on every port ("Port 17 — 1 GbE (PoE+)").
- Zoom-aware detail: simplified blocks when zoomed out and full detail up close, so a full 32U rack stays smooth.
- Catalog: full UniFi lineup plus MikroTik, Synology, QNAP, UGREEN, TP-Link, Netgear, Cisco, Dell, HPE, Supermicro, APC, CyberPower, Eaton, DeskPi, Raspberry Pi and generic passive gear, with search, filters and a custom part builder.
- Designs, stats and exports: start empty or from a template, autosave, undo / redo, power / heat / UPS / PoE / weight totals with warnings (including mixed airflow), and PNG / SVG / PDF / CSV / JSON exports.
- Read-only share links: send someone a link to view a design, with no login needed.
- 3D-printed parts: paste a MakerWorld link to turn a printed mount, shelf or panel into a part, linked to the device it holds, with designer credit, licence and print status.
Front faceplates exported as SVG, straight from the renderer.
All images are generated by npm run screenshots (see Development); none are hand-edited, and none are manufacturer photos or logos.
⬇ Download the latest installers (Windows .exe, Ubuntu .deb)
RackPlanner also runs as a normal desktop app, no Docker or server needed. It's the same app: the server runs inside the window, bound to 127.0.0.1 only, and your designs are kept in your user profile:
| Installer | Designs are stored in | |
|---|---|---|
| Windows 10/11 (x64) | RackPlanner-Setup-<version>.exe |
%APPDATA%\RackPlanner\data |
| Ubuntu 22.04+ / Debian (x64) | rackplanner_<version>_amd64.deb |
~/.config/RackPlanner/data |
- Windows: run the installer. It isn't code-signed, so SmartScreen may say "Windows protected your PC": click More info → Run anyway. It installs for your user only (no admin prompt) and adds Start-menu and desktop shortcuts.
- Ubuntu:
sudo apt install ./rackplanner_<version>_amd64.deb, then open RackPlanner from the app grid or runrackplanner. Remove it withsudo apt remove rackplanner.
File → Open Data Folder shows where your designs live. To move designs between the desktop app and a server install, use Backup on the home page and Import on the other side.
Only Docker is needed:
desktop/build.sh # both; or: desktop/build.sh linux | winThis builds the web app and server, then packages them with Electron and electron-builder in the electronuserland/builder:wine image (Wine is used to stamp the Windows .exe's icon and version info). The installers land in desktop/dist/. The only native module, better-sqlite3, ships Node-API prebuilds that work in Electron on every platform, so nothing is compiled.
Releases are automated. Pushing a version tag runs .github/workflows/desktop-release.yml: it runs the checks, builds both installers with desktop/build.sh, installs the .deb on the runner to check it starts, and attaches the installers and SHA256SUMS.txt to a GitHub Release for that tag:
git tag -a v0.2.0 -m "RackPlanner 0.2.0" && git push origin v0.2.0The app version comes from the tag. Running the workflow by hand from the Actions tab builds the installers as a downloadable artifact without publishing anything.
To run the desktop shell from source (needs Node 22+ and a desktop): npm run build, then cd desktop && npm install && npm start.
-
Install Docker (skip if you already have it):
curl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker $USER # log out and back in afterwards
-
Get RackPlanner and start it:
git clone https://github.com/fipity/rackplanner.git cd rackplanner cp .env.example .env # optional: port, PUID/PGID, basic auth docker compose up -d
-
Open
http://<server-ip>:8085.
The first build takes a few minutes. The container restarts automatically (restart: unless-stopped), and docker compose ps shows its health (GET /api/health).
| Variable | Default | |
|---|---|---|
RACKPLANNER_PORT |
8085 |
Host port. Change it, then run docker compose up -d |
PUID / PGID |
1000 |
Owner of ./data on the host (run id to see yours) |
BASIC_AUTH_USER / BASIC_AUTH_PASS |
empty | Set both to require a password. /api/health and read-only share links stay open |
LOG_LEVEL |
info |
debug, warn, error, silent… |
cd rackplanner
git pull && docker compose up -d --buildDesigns and custom parts live in ./data and survive rebuilds. Catalog changes are applied on startup, and existing designs keep working: parts removed from the catalog are retired, not deleted.
Everything (designs, custom parts, catalog state) is in one SQLite database: ./data/rackplanner.db.
-
From the app: use the Backup button on the home screen, or run
curl -o rackplanner-backup.db http://<server-ip>:8085/api/backup. This is a consistent snapshot, taken safely while the app runs. Single designs can also be exported as JSON and re-imported. -
Manually:
docker compose stop && tar czf rackplanner-data-$(date +%F).tgz data && docker compose start -
Restore: stop the container, replace the database, and remove the leftover write-ahead files so SQLite doesn't replay them onto the restored copy:
docker compose stop cp rackplanner-backup.db data/rackplanner.db # or: tar xzf rackplanner-data-<date>.tgz rm -f data/rackplanner.db-wal data/rackplanner.db-shm docker compose start
The image supports amd64 and arm64. On a Pi 4/5 or other arm64 host, docker compose up -d --build builds natively. To build both architectures elsewhere, e.g. for a registry:
docker buildx build --platform linux/amd64,linux/arm64 -t <registry>/rackplanner:latest --push .| Action | How |
|---|---|
| Add a part | Drag it from the catalog into the rack, or click it to drop it in the first free slot |
| Move | Drag a placed part (red = blocked, with the reason shown next to the cursor) |
| Put desktop gear on a shelf | Drag it onto a shelf, or just click it in the catalog: it goes onto a shelf with room. It stands on the tray and snaps beside items already there |
| Lay shelf gear on its side | Select it and press R, or choose Orientation: On its side. It takes less height and more shelf width; its faceplate and ports turn with it, and cables stay connected. Gear that doesn't fit standing up is laid on its side for you: when it's too tall for the room above a shelf (like the nbn HFC NTD), when only that fits under the gear above, or near the top of the rack or wall. This applies when you drag, click to add from the catalog, duplicate or move it between the wall and the rack. Gear that only fits upright is stood back up |
| Put gear on the wall beside the rack | Turn on the wall with the wall button in the toolbar, then drag desktop gear or wall plates onto it (left of the rack in the front view, right of it in the rear view). Clicking a wall plate in the catalog turns the wall on and puts it there. For a selected desktop device, Where: In the rack / On the wall moves it without dragging. Turning the wall off asks before removing what's on it |
| Select a shelf that has gear on it | Click its ears or tray, or the shelf name in an item's details |
| Draw cables | Press C (or Cables in the toolbar), click a port or device, then the other end. Esc finishes |
| Edit / delete a cable | Click it to edit type, colour, ports, length, label; Del removes it |
| Partial-width position | Select a 10″ / half-width part (or a shelf item), choose Left / Centre / Right |
| Move by 1U | ↑ / ↓ (shelves take their contents with them) |
| Delete / duplicate | Del / Ctrl+D |
| Undo / redo | Ctrl+Z / Ctrl+Shift+Z |
| Measured power | Select a device and enter watts in Measured power |
| Export / print | Export menu in the header |
Changing the rack width, height or depth so that some parts no longer fit asks for confirmation and lists what would be removed. You can undo afterwards.
The canvas pans and zooms freely, like a map: you can move well past the rack in every direction (up to a full screen of empty space on each side). If the rack ends up off screen, a Back to rack button appears. Each design remembers its zoom and position. Press ? in the editor (or the keyboard button in the canvas corner) for this list.
| Pan | |
|---|---|
| Drag empty space | Left mouse button (a click without moving still deselects) |
| Space + drag | From anywhere, even over a device (the cursor becomes a hand) |
| Middle or right mouse button | Drag from anywhere |
| Two-finger trackpad scroll | Any direction, diagonally too |
| Shift + mouse wheel | Horizontal |
| Arrow keys | Pan when nothing is selected (Shift for bigger steps). With a device selected, ↑ / ↓ move it 1U as before |
| Touch | One finger on empty space pans; two fingers pinch to zoom and pan together |
| Zoom | |
|---|---|
| Mouse wheel | Zoom towards the cursor (no key needed) |
| Ctrl / ⌘ + wheel, trackpad pinch | Zoom towards the cursor |
| + / -, toolbar zoom buttons | Zoom around the centre of the view |
| Zoom % in the toolbar | Click it to type a zoom level, 10% to 800% (100% = 1 px per mm) |
| F or Shift+1 | Fit the whole drawing (rack and wall) to the screen |
| Shift+2 | Zoom to the selected device |
| 0 or Ctrl+0 | Reset to 100%, centred |
| Minimap | The map button in the canvas corner shows the whole rack with the visible area outlined; click or drag in it to move there. The choice is remembered |
Dragging a device near the edge of the canvas scrolls the view so you can drop it further away. The page itself never scrolls or zooms while you're over the canvas; the sidebars scroll as usual. Exports always show the whole rack, whatever the view.
Browsers don't say whether scrolling comes from a mouse wheel or a trackpad, so RackPlanner goes by how it scrolls: a wheel's notches zoom, and small, smooth or sideways movements (two fingers on a trackpad) pan. If it guesses wrong for your mouse, the scroll wheel button in the canvas corner (also in the ? popup) switches between Wheel zooms (automatic), Wheel always zooms (every scroll zooms, trackpads too) and Wheel pans (hold Ctrl to zoom). The choice is remembered.
Turn on Cables mode (C) and every drawn port becomes clickable. Click one end, then the other, to add a cable. You can connect two ports, or a port to a whole device when the port isn't drawn (e.g. the NIC on a desktop NAS). The cable type is guessed from the ports (copper, DAC, fibre, coax, phone or power) and can be changed. Select a cable to set its colour, change either end's port, add a label, or set a length. Use … m suggests a standard patch-lead length from the distance between the ends, plus slack.
When the rack has cable managers or brush panels, cables are routed the way they'd be dressed: from the port into the nearest manager (within about 2½U), along it, and up or down the side of the rack beside the posts when the two ends use different managers. Cables sharing a manager or a side run are spread a little apart, so they read as a bundle. D-ring and finger-duct managers work on the face they're mounted on; brush panels work from both sides, and a front-to-rear cable is drawn to the brush panel it passes through (marked with a small ring). Without any managers, cables are drawn as a loose curve between the ends, as before. The Use … m suggestion measures along the routed path.
Cables between the front and the rear (or to a device on the other face) are drawn dashed. The eye button hides them all. Deleting a device removes its cables, and undo brings everything back. Warnings flag two cables on one port, ports that don't exist on a device, and cables to deleted devices. The CSV, PDF and printable parts lists include a cable shopping list grouped by type and length.
The home screen lists your designs with live thumbnails. Create a new one by picking a width, a height preset and an optional depth, or start from a template: a 10″ mini rack, an nbn + UniFi starter in a DeskPi RackMate T1, a 12U 19″ homelab, or a 9U network cabinet. Rename, duplicate or delete designs from each card's menu, and Import a design exported as JSON. JSON exports include any custom parts the design uses, so they move cleanly between RackPlanner installs.
Share in the editor creates a read-only link (/s/<token>). Anyone with it sees both views, the stats and the parts list, and can print it or download it as PDF or JSON (to import into their own RackPlanner). They can't change anything. The link always shows the latest saved version. Stop sharing turns it off for good; sharing again makes a new link. Share links work without the basic-auth password: only the share page, its static files and GET /api/shared/<token> are open, so a link only reveals the one design behind it. In the desktop app the server only listens on this computer, so links only work there.
Changes save automatically as you work. If the same design is saved from another tab or device, you're asked whether to keep your version or load the latest one.
The Stats tab, next to the device details, updates live:
- Space: U used and free (a U counts as used if anything occupies it, front or rear), plus device and passive counts.
- Power: typical and max draw. A device's measured power (e.g. from a smart plug or PDU reading) replaces catalog figures. When a part only publishes one figure, it's used for both. Catalog max power excludes PoE output, so the expected PoE load you enter is added on top before comparing against total UPS capacity.
- Heat: the rack's heat output in BTU/h (typical to max draw × 3.412). PoE power delivered to cameras and access points is given off where they are, not in the rack.
- PoE: total PoE budget of the switches and gateways in the rack, compared with your expected PoE load.
- Weight and port counts by type.
- Cables: count by type and total length.
- Warnings: devices deeper than the rack, gear deeper than its shelf, desktop gear not on a shelf, collisions or bad widths (e.g. after an import), parts missing from the catalog, UPS or PoE overload, cable problems, mixed airflow (one device blowing hot air out of the rack face where another draws cool air in), and devices with no power data. Click a warning to select the device.
Rack servers and UPSs are assumed to breathe front to back; other gear has no airflow unless its catalog entry sets one (airflow: front-to-back, back-to-front, side-to-side or passive). Set your own in the inspector's Airflow field. Airflow is relative to the device's front panel, so gear mounted on the rear rails blows the other way through the rack.
| Format | Contents |
|---|---|
| PNG / SVG | Front, rear, or both side by side, with title. SVG is fully vector |
| Page 1: front + rear views (landscape for short racks). Page 2: parts list, 3D-printed parts (model URL, designer, licence), summary and warnings | |
| CSV | Bill of materials: brand, model, quantity, U, power, weight, labels, spec URL, model URL / designer / licence for 3D-printed parts, plus cables by type and length |
| JSON | Full design plus the custom parts it uses (re-importable), with 3D-printed parts' cached pictures unless you pick JSON without 3D-print thumbnails |
| Parts to print | 3D-printed parts with picture, filament, status, model link, designer and licence. Printable, or CSV / Markdown |
| Printable view | Light layout with both views, stats and the parts list. Print from the browser |
Images and PDFs always use full detail, whatever the editor's zoom. Tick Print style (LEDs off) in the Export menu (or use the LED button on the printable view) for a cleaner look without lit status LEDs.
~300 parts in versioned JSON files under catalog/:
| File | Contents |
|---|---|
unifi.json |
Full rack-relevant UniFi lineup: gateways, switches, UNAS/UNVR/ENVR, UPS/PDU/RPS, OCD panels, shelves, rack-mount kits, plus desktop gear for shelves |
mikrotik.json |
CRS/CSS switches, CCR/RB routers, RDS storage |
switching.json |
TP-Link Omada, Netgear, Cisco, legacy Ubiquiti EdgeMax/UISP |
storage.json |
Synology RackStation, QNAP rack NAS |
servers.json |
Dell PowerEdge, HPE ProLiant, Supermicro chassis, generic DIY cases |
power.json |
APC, CyberPower, Eaton UPS units and generic PDUs |
patch-panels.json |
Generic 19" patch panels, blanks, brush panels, cable managers, shelves, drawers |
mini-rack.json |
10" ecosystem: DeskPi RackMate shelves/panels, Pi and mini-PC mounts, 10" PDUs |
desktop.json |
Mini PCs, Raspberry Pis, UGREEN NASync desktop NAS, modems/ONTs that sit on shelves |
What verified means: true means every number in the part comes from the manufacturer's own spec page or datasheet, linked in sourceUrl. false means the figures come from resellers, rack-vendor guides or typical values for generic items. Unknown values are null, never guessed. catalog/UNVERIFIED.md lists every unverified part and every missing value.
On first start the catalog is loaded into the SQLite database in ./data. When a file's contents change, it's re-applied on the next start. Parts removed from a file are retired: hidden from the catalog but kept, so existing designs still render.
- Edit or add a JSON file in
catalog/. Your editor can autocomplete againstcatalog/schema.json. Bump the file'sversion. - Validate it:
npm run validate:catalog(or./dev.sh run validate:catalog). This lists every problem and exits non-zero, and the Docker build runs it too. - Deploy:
docker compose up -d --build. To skip rebuilding, uncomment the./catalogvolume indocker-compose.yml, then runcurl -X POST http://localhost:8085/api/catalog/reloadafter editing.
Use the + button in the catalog to build your own device, with a live front and rear faceplate preview. Pick a style preset, then tick Custom layout to place regions yourself (ports, SFP cages, drive bays, display, vents, fans, PSUs, labels…) with % positions, or press Start from generated layout to begin from what the app would draw. The builder warns when the layout's ports don't match the port list or regions overlap. The copy icon on any catalog part (or Customise a copy in the inspector) starts from an existing part. Custom parts are stored in the database, appear under My custom parts, and are never overwritten by catalog updates.
Click Add 3D-printed part (in the catalog, or at the top of the custom part builder) and paste a MakerWorld model link. Any form works: with or without /en/, the name slug or #profileId-…. RackPlanner keeps a cleaned link and reads the model page once, when you paste it: title, designer, licence, print profile, a short description and the cover picture, from the page's public meta tags and embedded JSON. Print files (STL / 3MF) are never downloaded; the part links to the model page.
MakerWorld often blocks automated requests. When it does, nothing breaks: the name comes from the link (unifi-nvr-instant-10-inch-rackmount → "UniFi NVR Instant 10 Inch Rackmount"), the other fields stay editable, you can paste or upload a picture yourself, and Refresh details tries again later.
Before saving you check and edit what was guessed from the title:
- Rack width (10″ / 19″) and U height (
1U,2U,1.5U…). When the title has no height it defaults to 1U, highlighted so you check it. - Part type: rackmount (holds a device), shelf, blank, cable management, patch panel / keystone, ear / bracket, other.
- Device it holds: the title is matched against the catalog ("UniFi NVR Instant" → the UniFi NVR Instant). Confirm it, pick another, add more (e.g. 2 × Raspberry Pi) or remove it.
- Name, depth, front / rear, filament colour, notes and print status (planned, printing, printed, installed).
The part is saved as a custom catalog part tagged 3d-printed (filter the catalog with 3D printed), reusable in any design. Placing a mount places the devices it holds inside it, showing their real front panels through the cutout; dragging the mount moves them too, and removing it asks whether to keep them (moved to the nearest free shelf) or remove them as well. The stats warn when a device is too wide, tall or deep for its mount or the rack.
Printed parts are drawn in their filament colour, matte, with printed-on rack ears, faint layer lines up close and a small printer badge. Selecting one shows its picture, the designer (linked), the licence (NonCommercial / NoDerivatives are called out), print status and filament per placement, and View on MakerWorld. The stats count printed parts and how many are still to print, and Export → Parts to print lists them with picture, colour, status and link (printable, or CSV / Markdown). The CSV bill of materials, the PDF and the printable view include each printed part's model URL, designer and licence, and JSON exports carry the source details plus the cached pictures (or choose JSON without 3D-print thumbnails).
Pictures are resized to 600 px and kept in ./data/thumbnails, so they show offline. Fetching is locked down: only https://makerworld.com pages (and pictures from MakerWorld's image host, bblmw.com), checked on the parsed hostname for every redirect, never private or local addresses, a 10 s timeout, 2 MB pages and 5 MB images, images checked by decoding them, all fetched text stripped to plain text, and at most 10 fetches a minute. The My RackMate T1 example holds its NVR Instant in a MakerWorld mount. The NVR is 220 mm deep in the T1's 212 mm frame, so that example shows a depth warning. Printables and Thingiverse links aren't supported yet; each site is a small "source adapter" (packages/shared/src/printed/sources.ts).
scripts/research/ has the scripts that built the catalog. They cache spec pages in ~/.cache/rackplanner-research:
python3 scripts/research/fetch_unifi.py # techspecs.ui.com (UniFi + EdgeMax/UISP)
python3 scripts/research/build_unifi.py # -> catalog/unifi.json
python3 scripts/research/fetch_mikrotik.py && python3 scripts/research/build_mikrotik.py
python3 scripts/research/build_misc.py # servers, storage, switching, power, passive, 10", desktop, UGREEN
python3 scripts/research/gen_unverified.py # -> catalog/UNVERIFIED.mdEach catalog entry can describe its front, rear and top faces declaratively; the renderer places the parts:
"layout": {
"layoutVerified": false,
"sources": ["https://techspecs.ui.com/unifi/cloud-gateways/ucg-ultra"],
"front": { "style": "unifi-white", "regions": [ { "type": "display", "x": 0.41, "w": 0.18 } ] },
"rear": {
"regions": [
{ "type": "usb_c", "count": 1, "portType": "none", "role": "Power in", "x": 0.05 },
{ "type": "rj45", "count": 4, "portType": "rj45_1g", "x": 0.25 },
{ "type": "rj45", "count": 1, "portType": "rj45_2_5g", "start": 5, "uplink": true, "role": "WAN", "x": 0.78 }
]
}
}- Positions (
x,w,y,h) are fractions of the face, so the same layout works on 19″, 10″ and half-width gear. A region withoutxfollows the previous one, and one withoutwtakes its natural size (scaled down to fit, never overlapping the next placed region). - Port regions (
rj45,sfp_plus,qsfp28,usb_a,usb_c,hdmi,iec_c14,outlet_au,keystone,punchdown,lc…) takecount,rows,grouping,poe/poePorts,uplink,colorsandnumbers. Two-row blocks number switch-style (odd on top, even below);portTypeties them to the entry'sportsfor cables and stats ("none"for pass-through backs). - Feature regions:
bays,display,vent,leds,ledbar,button,label,psu,fan,pcie,io_shield,ground,label_strip,cable_bar,brush,handle,thumbscrew,switch,breaker,slot,d_ring,panel. stylepicks a preset:unifi-silver,unifi-white,unifi-black,dell-bezel,hpe,synology,mikrotik,generic-black,generic-silver,patch-panel,brush-panel,shelf,pdu,ups,rpi-case.- Entries without a layout get one generated from their ports, bays and category.
npm run validate:catalogchecks every layout against the schema, that it stays inside its face without overlaps at each rack width, and that it draws each catalog port exactly once. Layouts withlayoutVerified: falseare listed incatalog/UNVERIFIED.mdwith what couldn't be confirmed.
powerInput records how a device is powered (usb_c, dc_barrel, iec_c14, poe…, via a plug-pack or brick), which feeds the outlet check in the stats.
| Method | Path | |
|---|---|---|
| GET | /api/health |
Health check (used by Docker) |
| GET | /api/backup |
Download a consistent SQLite snapshot |
| GET | /api/catalog |
All parts, retired ids, catalog files |
| POST | /api/catalog/reload |
Re-read catalog/*.json |
| POST / PUT / DELETE | /api/parts[/:id] |
Custom parts (imports keep custom-* ids) |
| GET / POST | /api/designs |
List / create ({name, rack} or import {design}) |
| GET / PUT / DELETE | /api/designs/:id |
Load / save ({design, revision, force?}, 409 on conflict) / delete |
| POST | /api/designs/:id/duplicate |
Copy a design |
| GET / POST / DELETE | /api/designs/:id/share |
Read / create / revoke the design's read-only share link |
| GET | /api/shared/:token |
A shared design and the parts it uses (open without basic auth) |
| GET | /api/templates |
Starting-point designs (examples/templates/*.json) |
| POST | /api/printed/resolve |
{url}: parse a MakerWorld link and read the model page once (cached; fetched: false with a reason when it's blocked) |
| POST | /api/printed/refresh |
{url}: read the model page again |
| POST | /api/thumbnails |
{data} (base64 or data: URL, ≤ 5 MB): store a picture, returns its id |
| GET | /api/thumbnails/:id |
A stored picture (WebP, open without basic auth like share links) |
There's no Node on the host? ./dev.sh runs npm inside a node:22 container:
./dev.sh install
./dev.sh test # vitest: placement, stats, exchange, schema, catalog files, API
./dev.sh run typecheck
./dev.sh run dev # API on :8085, Vite on :5173 (proxying /api)Every image in docs/images/ is produced by the app itself:
npx playwright install chromium # once
npm run screenshots # builds, starts a scratch server, captures, optimises3D-printed parts in screenshots always show a generated placeholder picture: model pictures belong to their designers and never go in the repository. It starts the built server on a temporary database (the example designs in examples/ seed themselves), drives Chromium, writes palette-optimised PNGs, the drag-and-drop GIF and the device SVGs, and fails if docs/images/ grows past 15 MB. If the browser runs under a different Node version from the server (for example inside the mcr.microsoft.com/playwright image), start the server yourself on an empty DATA_DIR and pass BASE_URL=http://127.0.0.1:<port>.
npm run examples rebuilds examples/*.json and the templates in examples/templates/ from the catalog, checking every placement and cable.
tests/visual holds Playwright snapshot tests: one reference device per style preset (see /_faceplates), front and rear, in light and dark mode, plus checks for port tooltips and self-contained SVG exports. Snapshots are rendered in the mcr.microsoft.com/playwright:v1.64.0-noble image:
BASE_URL=http://127.0.0.1:8097 npm run test:visual # against a server on a scratch DATA_DIR
BASE_URL=http://127.0.0.1:8097 npm run test:visual -- --update-snapshotsGitHub can't take the social preview image from the repository. Upload docs/images/social-preview.png (1280 × 640) under Settings → General → Social preview → Edit → Upload an image.
Layout:
packages/shared zod schemas, placement engine, faceplate layout engine, stats, power, import/export + BOM
apps/server Fastify API (SQLite via better-sqlite3 + Drizzle) + static hosting of the built web app
apps/web React + Vite + Tailwind editor (SVG rendering, dnd-kit, zustand + zundo, jsPDF)
catalog/ parts catalog JSON seed files (+ UNVERIFIED.md)
examples/ example designs, added to the design list once; templates/ for the New design dialog
scripts/ catalog validator, example builder, screenshot pipeline, research scripts
docs/images/ generated README images
MIT










