Building a storefront

There are three ways to build a storefront on Swell: as a storefront app, as a theme for a storefront app that supports them, or as a headless storefront you host yourself. For most new projects, a storefront app is the recommended starting point.

A storefront app is built with the Swell Apps framework and implements the pages, data interactions, and features of a storefront. Its frontend runs on Cloudflare Workers and is deployed with the Swell CLI, and it receives your store's public key and access token directly — so it can call the Frontend API, the Backend API, or both. A storefront app can also support themes, which lets merchants change how a store looks without touching your code.

Proxima is Swell's first official storefront app, built with Astro. It supports themes and emulates the structure of Shopify Online Store 2.0 themes, and its Sunrise theme is installed by default with a new Swell account. It's open source, so it also serves as a working reference for building your own.

# Frameworks: nextjs, astro, nuxt, react, hono, angular
swell create app my_storefront -t storefront --frontend astro

# Preview it locally
swell app frontend dev

# Deploy it
swell app frontend deploy

A theme is its own kind of app, and always belongs to a storefront app that supports themes. If you want to change how a store looks rather than how it works, build a theme for an existing storefront app instead of a storefront app of your own. The theme guide covers the folder structure, the editor configuration, and the Liquid templates a theme is made of.

# The storefront app you're theming must be installed
# in your test environment first
swell create app my_theme -t theme --storefront-app proxima

A headless storefront is a frontend you host yourself that talks to Swell over the Frontend API — the methods documented in this section — or the Backend API. Choose it when you want full control of the stack and are prepared to own hosting and deployment yourself.

Origin and Horizon are earlier headless examples built on Swell.js, released in 2020 and 2022. Origin is a Nuxt project; Horizon is built with Next.js and includes native subscription support. Both are complete working implementations you can read through as reference for your own.