In Frontstack, your API evolves over time as your project grows. You will change blocks, adjust parameters, or remove parts — each of these changes updates your API and may affect your frontend.

Releases let you manage these changes, publish new versions of your API, and ensure your frontend always connects to a compatible version.

​
Changes

All changes made in the Admin app are instantly reflected in your workspace and available in the develop version of your API. For example, when you add a field to a block’s response, Frontstack processes all related updates and revalidates the data automatically — making the updated API immediately available for developers to build and test new features.

​
Publishing Flow

Before becoming publicly available, changes go through a preview stage. This gives you a consistent snapshot of your API endpoints and data, which you can test and validate. Once you’re ready, you can publish this version with a single click — replacing your current public version.

Your changes flow through these stages:

1

Make changes in your workspace

Changes here are processed immediately and trigger instant data revalidation, making them available in your API’s develop version.

2

Preview Version

The preview version captures a full snapshot of your project’s workspace at a specific point in time. You can promote this version to public or replace it with a new preview.

3

Publish Version

The public version is updated when you promote a preview. It serves as the default for all requests from your frontend applications.

​
Creating a Preview

Use the Release Control button in the top right of your Admin app to open the release drawer, then click Create Preview.

This creates a new preview from the current state of your project’s workspace. Any existing preview will be overwritten.

Because the preview is a full snapshot, it takes a moment to generate. You can track progress in the release drawer.

​
Promoting a Preview

Once your preview is ready, you can promote it to public. To promote, open the release drawer, and click Promote to Public.

Unlike creating a preview, promotion is instant — the promoted preview directly replaces your current public version.
After promotion, the preview section in the release drawer is hidden until you create a new one.

​
Working with Releases

Now that the concept of releases is established, let’s dive into how you can work with them in your project.
Make sure you’ve read the Client SDK guide to understand how releases integrate into your frontend code.

​
Understanding Version Tokens

A key concept in Frontstack’s release management is the version token — a unique identifier for a specific snapshot of your API.

Whenever you create a new preview, Frontstack generates a version token tied to that snapshot. This token remains valid as long as the preview exists. Once the preview is promoted to public or replaced by a new preview, the version token is automatically invalidated.

Version tokens are passed to the API using the FS-Version HTTP header. This header allows Frontstack to identify incoming requests and route them to the correct version of your API.

If you’re using our CLI, you don’t need to manage this manually — the token is automatically embedded in the generated client SDK. This creates a stable and predictable contract between your frontend and your API.

When a version token becomes invalid (for example, after promotion), or if no token is provided, the API gracefully falls back to the latest public version. This makes the transition from preview to public seamless — you don’t need to remove or update the token in your codebase. Your frontend will continue to function correctly, automatically using the production API when needed.

Accessing the develop version requires a version token that includes a secret. This ensures that only authorized environments can use unstable or work-in-progress API versions.

​
Practical Workflow

Here’s a typical workflow using releases:

1

Make changes in your workspace

Developers work on new features and make changes to blocks, parameters, or other API components in the Admin app.

2

Generate an updated client SDK

Once the API changes are complete, generate an updated client SDK using the Frontstack CLI:

frontstack generate

This SDK contains a version token that points to the current state of your develop stage.

3

Use the updated client in your frontend

Implement your frontend changes using the newly generated client SDK. Push these changes to a feature branch.

4

Deploy new preview

When ready to lock in the API configuration and test the complete solution, create a new preview version as described earlier. The preview becomes available with the exact API configuration that your client SDK expects.

5

Review, test and deploy

Generate an updated client SDK for the preview version. Review the changes and test your frontend code. When you’re satisfied with testing, create a pull request and ship your frontend code to production.

6

Promote to public

Promote your version from preview to public. Your frontend will continue to work seamlessly — it first uses the preview version, and once that version is promoted, it gracefully falls back to the corresponding public release.

​
Ensuring Frontend Stability

This approach provides several benefits:

  • Versioned API contracts: Your frontend always communicates with the exact API version it was built to work with.
  • Independent deployments: You can deploy frontend and backend changes independently without breaking compatibility.

The version token decouples your frontend code from the release lifecycle. Your frontend’s stability depends only on the specific API contract it was designed for — not on which stage (develop, preview, or public) the API version currently resides in.

​
Roll back to a previous release

(coming soon)