Behind the scenes · build machinery
Jones is a small offline vault for Claude artifacts. Almost everything around it is automated — and the interesting parts are not the pipelines that run, but the two guards that decide whether they should.
Jones collects Claude artifacts the way an archaeologist collects relics: recover them from the field, seal them so they survive, and keep them in a vault that works with the radio off. Share an artifact to it — or paste a link, or hand it raw HTML — and it pulls every script, stylesheet, typeface and image inside the file itself. What lands on the device is a single HTML document that still runs, rendered in a WebView with JavaScript enabled, on a plane or three years later when the CDN path it used has quietly 404'd.
It is one person's app. No account, no server, no analytics. That matters for what follows, because it sets the budget: every piece of automation here has to earn its keep against the alternative of just doing the thing by hand once a month.
This page is served from the marketing site at a plain address so it can be imported into the app. If you did that, the copy you are reading was pulled onto your device and sealed by the machinery it describes — the typefaces below arrived as a stylesheet from Google Fonts and now live inside the file. Turn the radio off and it will not notice.
GitHub Actions verifies. EAS distributes. The split is deliberate: verification should run on every branch of every fork with no secrets and no Expo account attached, and distribution needs credentials and a build farm. Keeping them apart means a pull request from anywhere gets the full check, and nothing that can publish is reachable from it.
| Workflow | Trigger | What it does |
|---|---|---|
ci.yml |
every push and PR | Runtime-version guard, typecheck, both test suites, and a real
Metro bundle for each platform. On a v* tag it also
publishes the production update. |
branch-update.yml |
every push | Fingerprints the native layer, then either ships the branch to the
development channel or builds a fresh dev client. |
preview.yml |
push to main |
Deploys the web preview, promotes that same commit to the production domain, then fingerprints and either builds installable binaries or ships an update. |
web-preview.yml |
pull request | Deploys the marketing site to an isolated URL and comments it on the PR. |
development-build.yml |
manual | Dev-client builds — the Expo Go replacement. |
production.yml |
manual | Store builds for both platforms, with an approval gate before anything is submitted. |
The one thing CI does that typecheck does not is bundle. Metro resolves
differently from tsc, and a clean bundle for both platforms is
the only real proof that every import survives into the app.
Most pushes to a React Native project change JavaScript and nothing else.
Those can go out over the air in about a minute. A few pushes touch the
native layer — a new native dependency, an app.json native key
— and those need a fresh binary that somebody has to install. Getting that
distinction wrong in either direction is expensive: build every push and you
burn build minutes and reinstall constantly; update every push and one day
you ship JavaScript that calls native code the installed binary does not
have.
So the workflows don't guess. They hash the project's native characteristics, then ask EAS whether a build with that hash already exists.
The same gate runs twice, pointed at different profiles.
preview.yml uses it so that pushes to main reach
the phone in my pocket; branch-update.yml uses it so that any
branch, pushed from anywhere, becomes the thing the development build
loads. That second one has a nice property: a branch that adds a native
dependency replaces the dev client by itself, rather than going quiet until
someone works out why their build is behaving strangely. Builds are billed,
but the gate bounds them — one per new fingerprint, not one per push. And
[eas skip] in a commit message opts a push out entirely.
Expo can compute runtimeVersion from a fingerprint policy, so
that an update only ever reaches binaries it fits. This project doesn't do
that. It pins the string to a literal "1", which is what makes
JavaScript changes cheap: one string, every install, no per-build runtime
churn. It is also the one way to break an app that is already out there.
Publish JavaScript that calls native code the binary lacks, and it crashes
on launch — for everyone on that runtime, TestFlight and App Store alike.
The rule is therefore "bump the string whenever the native layer moves", and
the problem with that rule is that nothing about editing a dependency
looks like a native change. So scripts/runtime-version.mjs
remembers instead. It hashes the native layer with the same library EAS uses
and compares the result against a committed record of what the current
string was accepted for:
{
"runtimeVersion": "1",
"sourceSkips": 3587,
"fingerprints": {
"ios": "61745bec72bb9e0594facdba1a5fea526f318203",
"android": "8c54598153e0c5b39d37968b15637fa88e958ec5"
}
}
npm run runtime:check is what CI runs, and the publish job
depends on it, so a native change that forgot to bump the string fails
before it can ship rather than after. npm run runtime:accept
re-records — and refuses to, if the native layer moved while the string
stayed the same.
The question this guard asks is narrower than EAS's own. Not "would this
produce a different binary" but "could JavaScript published against this
reach a binary that cannot run it". Four inputs move without ever changing
that answer, and hashing them would cost a runtime bump — orphaning every
install — for nothing: the version and build number, which
autoIncrement changes on every single build; the
runtimeVersion string itself, whose inclusion would make every
bump self-justifying; npm scripts, which never reach the binary; and
.gitignore.
It cost a false alarm. Adding a build artifact to the ignore file moved the hash, and the guard read that as a native change — which is precisely the mistake it exists to prevent, running in the other direction. Skipping the file's contents loses nothing, because its real influence is indirect and still fully captured: the file decides which paths get hashed at all, so ignoring one that held a native source removes that source from the fingerprint and moves the hash anyway. What is skipped is only the claim that editing an ignore list is itself a native change, which it never is.
That skip set is stored in the record as a number, which is the detail I'd keep if I kept nothing else. Hashes are only comparable against the skip set that produced them. Change the set and every stored hash means nothing at once — and the guard says so, rather than reporting a native change that did not happen.
Pushing to main does not touch anybody's installed app. It
reaches the preview channel, which is my phone and nobody
else's. The production channel is served by a version tag and
nothing else:
git tag v1.0.2 && git push origin v1.0.2
A release is then something you decide rather than something that happens.
The tag does double duty: it is bundled in as
EXPO_PUBLIC_JS_VERSION, so Metro inlines it into the JavaScript
and the app's debug section can name the build it is running. What a phone
has can be read off its screen and matched to a commit. A bundle built any
other way — a dev server, a local build, the one embedded in a store binary
— has no tag and shows an em dash there instead, which is itself useful
information.
The website rides along on the same push. preview.yml deploys
the export to a preview alias, and only once that succeeds promotes the same
commit to the production domain — so a push that fails typecheck, tests or
the preview deploy never reaches the live site. Pull requests get their own
isolated URL, commented onto the PR by a workflow that is four lines long.
The other half of the automation makes pictures. Store screenshots in five canvases, a 27-second silent promo film in two shapes, the Play feature graphic, and a kit of social cards. Every one of them comes out of a command, and none of them involves a screen recording or a simulated tap.
The screenshot run boots a simulator, installs a release build, replaces the app's container with a deterministic demo vault, and then walks the screens by deep link. Every screen the store shows is reachable from a URL alone, so a route cannot drift when a control moves, and two runs a month apart produce the same pixels. The promo film is built from those same stills and an ffmpeg graph — the camera moves, the app doesn't.
Deep-link navigation only works when EXPO_PUBLIC_SCREENSHOT_MODE
is set at bundle time; without it Metro dead-code-eliminates the route
reader away. Such a build installs and launches perfectly happily — and
lands on the home screen for every single shot, which comes back as a set
of identical captures rather than as an error. So the capture step refuses
a build it cannot steer, instead of producing six copies of the same
screenshot and letting you find out at the store listing.
Everything with type on it — the framed screenshots, the film's captions, the feature graphic, the social cards — is plain HTML rendered by headless Chrome through one shared module, with the app's real Cinzel, IM Fell English and Special Elite embedded as data URIs and its own textures behind them. The marketing artwork is set in the app's actual typefaces rather than an approximation, because it is the same fonts off disk. Each render runs at 2× and resamples down; the medallion is a 1024px PNG drawn at a third of its size, and Chrome's 1× downscale crawls along the ring of ticks.
The generated trees are gitignored — 80 MB of screenshots, 31 MB of social cards — because one command rebuilds them. The two exceptions are the feature graphic, which is small and changes rarely, and the web copies of the film, which are committed precisely because the deploy runs on EAS, where there is no simulator and no Chrome. A film that only exists on the machine that made it never reaches the site.
The app ships in two interface styles. Explorer is the original field-archive theme: brass, Cinzel, and a vocabulary to match — a saved page is a relic, its size is its mass, the details behind it are its provenance. The plain mode is the same app in system type and direct language: item, size, source.
That pair is not just a setting. It runs through the app's copy table, both store screenshot sets, both cuts of the film, the feature graphic, both store listings and every social card — all generated from the same two keys. Which means a store A/B test measures positioning rather than build quality: same binary, same seeded vault, same simulator, different words.
My favourite detail in the whole project is one line of asymmetry in that table. Explorer mode calls the plain one Boring. The plain one calls itself Normal. Nobody in it thinks they are boring.
68 tests, in two suites, both bundled with esbuild and run on plain Node.
Expo's device modules — the filesystem, crypto, expo/fetch —
are aliased to stubs at bundle time, so the production code runs unmodified
against an in-memory device.
The first suite exercises recovery and sealing end to end against a local
stand-in for a share page served out of node:http: candidate
extraction, URL normalisation, frame hosts out of a CSP, asset inlining,
content-addressed shared scripts. The second runs the acquisition,
catalogue and persistence journeys — importing, filtering and sorting,
favourites, seal colours, home-screen links, the daily snapshot's
keep-and-prune behaviour.
There are no UI snapshot tests and no device tests. The interesting failure modes in this app live in parsing and inlining, not in whether a row renders, and a bundle that compiles for both platforms plus a real deterministic screenshot run covers more of the rest than a wall of shallow render assertions would.
Copy a gate, not a pipeline. The pipelines here are unremarkable — check out, install, typecheck, test, build, deploy — and any project has them. What makes this one cheap to run is the two places where something asks a question before spending anything: is this change native?, which decides between a one-minute update and a fifteen-minute build, and does the runtime string still cover the native layer?, which is the only thing standing between a convenient release process and a crash loop on somebody else's phone.
Both are about twenty lines of workflow and one script. Neither is clever. They are just the two questions I would otherwise have to remember to ask myself, every time, forever.
Jones is an offline vault for the things you build with Claude. It is free, and there is no account — jones.expo.app. The source is on GitHub.