Release Flow

Releasing a version takes a change from the workspace to your customers: you preview a version, deploy your frontend against it and test it, then publish it. This page walks through each step, the version keys that tie a frontend to an API version, and the order to deploy in.

If you haven’t already, read the Release Control overview first for the workspace and the API versions.

​

Work in the workspace

Features start in the workspace. Add fields to a storage, wire up a sync, build blocks, listings and pages: every change shows in the develop version at once, so you can build the frontend against it in parallel. Regenerate the Client SDK whenever the API surface changes so your code stays in sync:

frontic generate develop

The develop version can break at any moment, because it follows every edit. Nothing you do here reaches the public version. When the workspace is ready for testing, preview a version.

​

Preview a version

A preview version is a snapshot of the workspace as it is when you create it. Open your project’s dashboard in the admin app and click Create Preview in the Release Control section, or run frontic release preview from your editor.

A project has one preview version at a time, and previewing again replaces it. The old preview’s version key stops working the moment the new build starts, and a frontend deployed against it silently reads the public version instead (the workspace, before the first publish), which may lack fields it expects. To test two changes in parallel, publish one before you preview the next, or use a draft.

Frontic snapshots the workspace end to end - schemas, syncs, blocks, listings, pages, project settings - into a new preview version with its own version key, and processes your data with that configuration. Its schema, sync mappings and records stay consistent with each other, whatever happens in the workspace afterward. While it builds, a progress bar takes the place of the version key in Release Control.

You don’t have to wait for a build to finish. If you spot something to fix mid-build, fix it in the workspace and preview again right away; the button now reads Create new Preview. The new preview version replaces the one still building, and the old version key stops working at once.

​

Test against the preview version

1. Generate the Client SDK against the preview

   From your editor, generate the Client SDK against the preview version. The generated SDK carries the preview’s version key.

   frontic generate preview
   

   The key is baked into the generated client files, not stored in an env var you have to remember to flip.

2. Deploy your frontend against it

   Build, merge and deploy the frontend release with that SDK. The deployed app reads the preview version instead of the public version.

3. Test the deployed app

   This is what you test: not a moving target, but the exact version you will publish, running where your customers will use it.

4. Iterate

   If you find issues, fix them in the workspace, preview a new version, regenerate the SDK, deploy and test again.

​

Publish the version

Publishing is irreversible. There is no rollback: the previous public version cannot be restored, and the admin app warns you before you publish. To undo a change, make the opposite change in the workspace, preview a version and publish it: the same path as any other change.

When the preview version has finished building and the app deployed against it passes your tests, open your project’s dashboard and click Promote to Public in Release Control, or run frontic release publish.

Publishing is instant. The preview version becomes the public version: it already holds processed data, so nothing is rebuilt. Every frontend reading the public version gets the new one in the same moment, with no downtime and no version skew between callers.

The version you tested is now the public version, so the app you deployed against it is already live. No redeploy, no downtime: a blue-green switch.

Afterward the project has no preview version until you trigger the build of the next one.

​

Version keys

A version key ties a request to one API version. The Fetch API reads it from the fs-version header:

fs-version: <version key>

You rarely set this header yourself. The Client SDK carries the key of the version it was generated against, so every call your frontend makes reads that version.

Develop version

A key fixed when the project is created. Reads the workspace as it is now. For development, never for customer traffic.

Preview version

A new key each time you preview a version. It stops working when the preview is published or replaced. Release Control shows it as the Version Key.

Public version

An empty key. A request without an fs-version header reads the public version.

​

How the Fetch API picks a version

By default, the Fetch API serves the public version. Only a request with a valid version key reads another version:

The request carries	The Fetch API serves
No valid version key	The public version
The develop version’s key	The workspace as it is now
A preview version’s key	That preview version

When you publish, a frontend deployed against the preview is live on the public version at once, with no code change. When a preview is replaced instead, its key is no longer valid the moment the new build starts, so a frontend built against it reads the public version, which may lack what it expects: see the warning under Preview a version.

Without Release Control, or before the first publish, the public version is served straight from your workspace, so every workspace change takes effect at once. Remove a field from a storage schema and the affected records are reprocessed; until that finishes, some records still have the old shape and some the new one.

​

Deploy order

Preview, deploy, test, then publish. The app goes live before the version does:

1. Preview a version and generate the Client SDK against it.
2. Build, merge and deploy the frontend release with that SDK. From the moment it is live, the app reads the preview version: the version you are about to publish.
3. Test the deployed app.
4. Publish the version. The version you tested is now the public version, so the app is live at once, with no second deploy.

Don’t preview again between deploying the app and publishing: the new preview replaces the version the app reads the moment its build starts, and the app falls back to the old public version (the workspace, before the first publish).

Changes on one side only don’t need the other. A workspace change the frontend doesn’t depend on needs no app deploy: preview, test and publish. A frontend-only change needs no new preview.

​

Related

Release Control

The workspace, the API versions and how a change moves through them.

What's in an API Version

Exactly what an API version contains, and what all versions share.