Sequence
Sequence lays out photos as a book (spreads of facing pages) or a run of frames (slides, an
Instagram carousel), and exports them as a PDF, images, an InDesign file, or an Instagram
post. It's a web app at sequence.photos and a Mac app on the
App Store, built from the same code.
This README is for working on it. What the app does, in detail, is in
docs/agent-context/.
Setup
You need Node 24 (.nvmrc; anything from 20.19 works). For the Mac app, also Rust and the
Xcode Command Line Tools: docs/setup.md has the details for a new machine.
nvm use
npm ci
npm run setup # the server's packages, and Playwright's browsers for test:e2e
The site
The website: the landing page, the app at /app/, and the privacy and support pages, all
in site/. The app's code is in src/.
npm run dev # http://localhost:5175 (the app is at /app/), reloading on changes
npm run build # type-check, then build to dist/
npm run preview # serve dist/ at http://localhost:4173
Netlify deploys it (netlify.toml): every push to main goes to sequence.photos, after
npm test && npm run build; pull requests get a preview deploy.
Public settings (the domain, the App Store link, the server's address) are in .env, which
is committed. Never put a secret there: see Secrets.
The server
Posting to Instagram goes through a Cloudflare Worker in server/, a package of its own.
server/README.md describes what it does, its API, and its setup. The
app imports its API types from server/src/api.ts.
npm run server:dev # a local Worker at http://localhost:8787 (the dev environment)
npm run server:deploy # deploy to production
npm run server:deploy:dev # deploy the dev environment
npm run server:metrics # a usage report from Cloudflare's analytics
The local Worker reads its secrets from server/.dev.vars (copy .dev.vars.example);
the deployed ones are set by the owner with wrangler secret put. Settings → Advanced in
the app switches between the production, dev, and local servers.
The Mac app
A Tauri app in src-tauri/, wrapping the same web app with a menu
bar, Save dialogs, and .photo-sequence files as documents. It runs sandboxed, as on the
App Store, local builds too.
npm run app:dev # run it, reloading on changes (the first build takes a few minutes)
npm run app:build # a standalone build: src-tauri/target/release/bundle/macos/
npm run app:store # a signed, universal .pkg for App Store Connect (and uploads it)
app:dev and app:build run app:ui:dev and app:ui:build, the app's web side, on their
own. app:store needs certificates and a provisioning profile, and says what's missing;
usually the Release workflow does it instead: see docs/releasing.md.
The website and the app share everything but src/platform/: each build imports
#platform, which is src/platform/browser.ts for the website and src/platform/macos/
for the app (see vite.config.ts). CI checks that neither build contains the other's code.
Testing
npm test # unit tests (vitest); test:watch re-runs them on save
npm run test:e2e # interaction tests in Chromium and WebKit (Playwright)
npm run test:app # the Mac app end to end: files, windows, the sandbox (a few minutes)
npm run server:test # the server's tests
npm run check # before a commit: secrets, formatting, lint, types, unit tests
test:app builds a test version of the Mac app and drives it on fixture projects (its
window shows for a while), keeping its storage apart from the real app's.
CI (.github/workflows/) runs the checks, both builds, and the e2e tests on every pull
request, and test:app on a Mac when a change touches the Mac side. Before a release, go
through docs/testing.md: what's automated and what to check by hand.
Secrets
Secrets live only in files whose names are git-ignored everywhere in the repo:
.env.local (or .env.*.local) and the server's .dev.vars. Committed .env files hold
public VITE_ values only, since they ship in the website and the app. Vite reads
.env.local as well and ships its VITE_ values, so no secret there starts with VITE_.
scripts/check-env.mjs checks that in npm run check and CI.
Directories
| Directory | What's in it |
|---|
src/ | The app: React and TypeScript, with its unit tests beside each file |
site/ | The website's pages (landing, app, privacy, support), the landing page's code, and public files |
server/ | The Cloudflare Worker for Instagram posting, with its own package and tests |
src-tauri/ | The Mac app's native side (Rust), its config, entitlements, and icons |
e2e/ | Playwright interaction tests |
scripts/ | Build and release scripts: the App Store build, version bump, icons, checks |
assets/ | Source art: the app icon's drawings (npm run icons makes the rest), and the screenshots' photos |
docs/ | Setup, testing, releasing, design proposals, and context for coding agents |
.github/ | CI, the Mac app test, and the release and App Store workflows |
