Factory Graph
A node editor for Factorio production chains. Nodes are recipe steps, edges are item
flows, and a linear-programming solver keeps every rate consistent as you edit. The
result is a ratio sheet you can read spatially and share as a URL.
basta.github.io/factory-graph
Static site, no backend. Factorio 2.0 base + Space Age.
Running it
npm install
npm run dev # http://localhost:5173
npm run build # type-check and build to dist/
npm test # unit tests: solver, store, serializer, library, layout, data
npm run smoke # drives the built app in a real browser (needs `build` first)
npm run check # lint + test + build + smoke, what CI runs
npm run shot -- name # screenshot the built app into shots/
npm test covers everything that is a pure function. npm run smoke covers what
is not: port-to-port drags, the drop-on-empty-canvas search, click-to-select,
the clipboard, a real file download and re-import, auto-layout, switching
between saved plans, and the reduced-motion path. Both run in CI.
To poke at a specific graph, npx tsx scripts/make-fixture.ts <name> prints a
share hash you can paste after the # — green-circuits, unbalanced,
saturated-belt, over-belt, blocks, kovarex, tangle, beacons,
no-constraint.
Refreshing the game data
Recipe data is vendored, not fetched at runtime. To move to a newer game version:
npm run data:fetch # download FactorioLab's raw data set into vendor/
npm run data:import # transform it into public/data/2x1.json + public/sprites/2x1.webp
vendor/ is gitignored; the committed artefacts are the two scripts and their output.
The importer validates its own output against src/data/schema.ts and fails loudly if a
recipe references a machine or item that is not in the set.
Deploying
The build is a static site. base comes from the BASE_PATH environment variable, so a
GitHub Pages project site works with BASE_PATH=/factory-graph/ npm run build.
.github/workflows/deploy.yml does exactly that on a push to main.
npm run check:base serves that build from a sub-path and asserts the app boots, the
fonts and sprite sheet load, and nothing 404s — the failure it exists to catch is an
asset referenced from the site root, which works locally at / and breaks the moment
the site lives at /<repo>/. CHECK_BASE_PATH=/factory-graph/staging points it at a
staging build.
Staging
The staging branch is a preview of the next release, at
basta.github.io/factory-graph/staging.
Push to staging to update it; merge into main to ship it.
Pages holds one artifact for the whole site, so every deploy builds both branches —
main at the root, staging under /staging/. A push to staging runs the checks and
then asks main to redeploy, because the Pages environment takes deploys from the default
branch only.
Staging shares an origin, and so localStorage, with the live site. It is built with
VITE_CHANNEL=staging, which gives it its own storage keys: on first visit it starts
from a copy of the live site's plans, and nothing it saves ever reaches them. The header
and the tab title both say Staging.
Layout
src/
data/ GameData types, zod schema, loader, sprite lookup
solver/ rates.ts (formulas), lp.ts (LP build), index.ts (solve), tests
graph/ zustand store, history, serializer, url, saved-plan library
canvas/ React Flow setup and custom nodes, edges, handles, grid
ui/ Header, Inspector, Search, Toast, ShortcutsOverlay
tokens.css
scripts/ data fetch, data import, screenshots
public/ data/, sprites/, fonts/
DESIGN.md is the visual brief. NOTES.md is the running log of what each screenshot
showed and what changed because of it.
Credits and licence
The application code is MIT licensed — see LICENSE.
Recipe data and the icon sprite sheet under public/ are derived from
FactorioLab, which is MIT licensed.
The icons themselves are game assets belonging to
Wube Software; they are used here the way every community
calculator uses them, and are not covered by this project's licence. Factorio is
a trademark of Wube Software. This project is not affiliated with Wube or with
FactorioLab.
