Behind the scenes · build machinery

Shipping Jones

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.

Stack
Expo SDK 57, React Native 0.86, Expo Router, TypeScript
Targets
iPhone, iPad, Android, plus a static web marketing site
Automation
One GitHub Actions workflow, five EAS workflows
Generated assets
Store screenshots, a promo film, a feature graphic, 90 social cards
the subject

What the thing is

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.

You may be reading this inside it

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.

the split

Two systems, on purpose

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.

WorkflowTriggerWhat 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.

guard one
the fingerprint

Don't build what you can update

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.

guard two
the runtime

The guard I had to write myself

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 interesting part is what it ignores

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.

Why .gitignore is in that list

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.

releasing

A release is a tag, not a push

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.

assets

Nothing is filmed, nothing is photographed

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.

The failure mode that looks like success

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 two voices

One app, two personalities, all the way down

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.

tests

What is tested, and what isn't

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.

in short

If you copy one thing

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.