Frontend

Swell App frontends can serve different purposes, depending on the goal of the app. A frontend is essentially its own application within a Swell App, intended to render pages for public display. For example, a storefront app implements the page structure and functionality of a storefront using a frontend. Frontends run as Cloudflare Workers, either hosted by Swell or deployed to your own Cloudflare account.

You can create a new frontend with the following CLI command. It prompts for a frontend template, and sets frontend.hosting in swell.json to the template's hosting mode. You can also add a compatible framework to the app's frontend/ folder yourself.

swell create frontend

To skip the prompt, pass a template, for example swell create frontend --frontend swell-react -y. See Frameworks for the templates.

Proxima app serves as an example for developers to learn best practices for developing storefront frontends, but the sky is the limit. With a wide range of framework choices, any number of storefront use cases can be achieved on the Swell platform. The React SPA Storefront template, swell-spa, starts a new storefront app on managed hosting.

A frontend can be embedded in Swell's dashboard, to provide a more flexible interface for merchants to manage data and settings for your app. Links with the frontend:// scheme in content views, navigation and actions open the app's frontend inside the dashboard. A store user who opens it this way is identified by the admin claim of Swell-Context. See Swell API access.

A frontend is either managed, hosted by Swell, or self-hosted in your own Cloudflare account. Set the mode with frontend.hosting in swell.json. When it isn't set, the frontend is self-hosted.

Next.js apps must be self-hosted. To move a managed frontend to self-hosted, set frontend.hosting to self-hosted. Removing the key isn't enough.

swell create app and swell create frontend accept the following templates with --frontend. The managed templates require Node.js 22.22.2 or later.

We will expand this list as demand for additional support grows. If your framework of choice is not yet supported, reach out to us or make a pull-request on Github.

To simplify your frontend's interactions with the Swell platform, we've developed the Apps SDK, a Typescript-based library that comes built-in with frontend and backend API clients, and theme rendering logic for storefront apps.

→ See the Apps SDK reference for more details.

During local development, you'll be able to run the app on your machine and quickly preview changes using the following CLI command:

swell app dev

This will perform several functions:

You should only run app dev on one app at a time, otherwise your account session will only remember the last app that was started.

When the command is successfully executed, it prints a URL to preview the app through the proxy. It also watches for changes and automatically pushes configurations and files to Swell as you develop the app. The preview always uses your local dev server, for both managed and self-hosted frontends.

When you're ready to test your frontend in the cloud, or to make a final deployment before release, deploy it with the CLI. How the CLI deploys depends on frontend.hosting:

For a self-hosted frontend, first log in to Cloudflare using wrangler:

wrangler login

In a non-interactive shell, also export CLOUDFLARE_ACCOUNT_ID. Then deploy the frontend, in either hosting mode, with the following command:

swell app frontend deploy

Admin and integration app frontends are served at https://<store-id>--<installation-id>--app.swell.store, and storefront app frontends on the store's storefront domains. swell app push and swell app frontend deploy update the app in the store's test environment. A released app version keeps the frontend it was released with.

Swell handles some paths on an app's domain before they reach the frontend, including /api, /graphql, /functions and /.well-known. On storefronts, /checkout goes to Swell's hosted checkout unless the store uses a custom checkout. Serve your app's own endpoints under /app-api, which Swell passes to the frontend with the path, query and body unchanged.

Managed deployments return errors with the following codes. A failed deployment leaves the previous frontend serving.

When your app is invoked, either as a storefront or as an admin app, Swell will proxy the request along with headers that can be used by the app to identify the merchant and authenticate with the store's frontend and backend APIs.

The following table outlines the headers passed to a frontend app when requested:

Storefront-specific headers:

Theme-specific headers:

These headers are unique for each store and its app installation. Once invoked, your frontend will likely connect to the Swell Frontend API, Backend API, or both, using the access token (backend) and public key (frontend) provided via headers. Keep the access token on the server, and send only the public key to the browser.

Example

Using the Apps SDK:

import { Swell } from '@swell/apps-sdk';

const swell = new Swell({
  serverHeaders: context.request.headers, // Object received from worker environment
  ...options,
});

// Make a backend API call
await swell.backend.get('/products');

// Make a frontend API call
await swell.storefront.get('/products');

Using Swell libraries:

import Swell from 'swell-node';
import SwellJS from 'swell-js';

const storeId = context.request.headers['Swell-Store-Id'];
const accessToken = context.request.headers['Swell-Access-Token'];
const publicKey = context.request.headers['Swell-Public-Key'];

// Initialize backend API client
const backend = Swell.init(storeId, accessToken, [...options]);

// Initialize frontend API client
const storefront = SwellJS.create(storeId, publicKey, [...options]);

You may otherwise prefer to build your own request handlers using the Fetch API, following our backend and frontend API guides for details.

Swell-Context is a JSON Web Token signed by Swell with ES256, and expires 60 seconds after it's issued. Only trust the store, app or store user it identifies after verifying it. The other Swell-* headers aren't signed.

Verify the signature with the key from https://swell.store/.well-known/jwks.json that matches the token's kid. Then check that iss is https://swell.store, aud is your app's ID, and the token hasn't expired. The token contains:

Use the admin claim to identify the store user, rather than the _swell_admin_session cookie, which is temporary.

Because frontends are hosted by Cloudflare Workers, your app has access to standard worker context properties and runtimes. Managed frontends have the limits listed under Managed frontends.

Here are some useful docs to better understand the worker environment:

Things to consider: