Release build

The release build packages the API and the web app into a single self-contained executable. It is what the GitHub release workflow produces and what end users download.

Building

From the repo root:

bun run build:release

The script does three things in order:

1. Builds the SvelteKit web app into apps/web/build/.
2. Compiles the Bun API entrypoint into a single executable at apps/api/dist/rewind.
3. Bundles the two together into a platform-specific archive under release/.

The exact output directory looks like:

release/
  rewind-<version>-<platform>-<arch>/
    rewind                  # the compiled launcher
    web/                    # the static web app
  rewind-<version>-<platform>-<arch>.tar.gz

The exact platform and arch match the host that ran the build. A build on linux x64 produces rewind-<version>-linux-x64. To cross-compile, pass --target to the bun build invocation in apps/api/package.json.

What the launcher does

rewind is a single-file Bun executable. On startup it:

1. Resolves the data directory from REWIND_DATA_DIR or the platform default.
2. Opens the SQLite database under that directory (creating it on first run).
3. Migrates the schema if needed.
4. Starts the Elysia API on 127.0.0.1:8000 (or HOST/PORT).
5. Serves the bundled web/ directory from the same process, so visiting http://127.0.0.1:8000 lands on the workspace.
6. Optionally opens the default browser to that URL, after a short delay so the server is ready.

The launcher's bootstrap code is in apps/api/src/index.ts.

What the launcher does NOT do

• It does not install itself. Drop the binary anywhere on your PATH if you want a system command, or run it from wherever you unpacked the archive.
• It does not create a desktop shortcut or a launchd/systemd unit. Run it manually, or wrap it in your own service definition.
• It does not phone home. The binary is fully self-contained: API, web bundle, and Drizzle migrations.

Smoke test

A small smoke script is included to verify the built binary:

bun run scripts/smoke-release.ts

It unpacks the release archive into a temp directory, starts the binary, hits /health, and checks the response. It also exits with a non-zero code on any failure, so it can run in CI.

CLI build (optional)

If you only want the command-line runner (no UI, no server), build it separately:

bun run --filter '@rewind/api' build:cli

This produces apps/api/dist/rewind-cli. The CLI requires a separately-running API to talk to; it does not start its own. See Running a collection for usage.

Versioning

The API exposes its version through the version field in the diagnostic archive. The launcher's version is currently the workspace package version (2.0.0 at the time of writing), hard-coded in apps/api/src/index.ts. The web app reads the same value.

Distribution

Releases are published through the GitHub Actions release.yml workflow. The workflow:

1. Builds the web app and the launcher.
2. Runs the smoke test against the produced binary.
3. Creates a GitHub release with the .tar.gz and a checksums file.
4. Attaches the diagnostic script and any release notes.

You can run the same steps locally with bun run build:release followed by bun run scripts/smoke-release.ts and a manual gh release create.

What's next?

• Environment variables — the knobs the launcher reads
• Data and storage — what the launcher writes
• Contributing — making changes that should ship in the next release