Frontend

Swell Apps may implement a frontend to 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. Different technologies can be used to build a frontend, such as Next.js, Astro, and other frameworks supported by Cloudflare Pages.

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, and the power of Cloudflare Pages, any number of storefront use cases can be achieved on the Swell platform.

A frontend can be configured as an embedded UI within Swell's dashboard, to provide a more flexible interface for merchants to manage data and settings for your app.

You can create a frontend by initializing an app using the JavaScript framework of your choice in the app's frontend/ folder, or by using the following CLI command:

swell create frontend

At this time, the following frontend app frameworks are supported:

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 frontend dev

This will perform several functions:

You should only run app frontend 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 will provide a URL to preview the app through the ngrok proxy. It will also watch for changes and automatically push configurations and app files to Swell as you develop the app.

When you're ready to test your frontend in the cloud, or ready to make a final deployment before release, you will deploy it using the CLI. At the time of this writing, the frontend app will be deployed to your own Cloudflare account, which you can obtain for free. In a future release, Swell may be able to handle worker deployments for you.

To configure Cloudflare, first make sure your are logged in using wrangler:

wrangler login

Once logged in, Swell CLI will orchestrate deployment using wrangler, with the following command:

swell app frontend deploy

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 the Swell Frontend API, Backend API, or both, using the access token (backend) and public key (frontend) provided via headers.

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.

Because frontends are hosted by Cloudflare Workers, your app has access to standard worker context properties and runtimes.

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

Things to consider: