Storefronts V2
Themes are developed for specific storefront apps that support them. Proxima is Swell's first official storefront app supporting themes, however we encourage developers to create their own apps and themes to make customizing stores easier for all kinds of merchants.
Depending on the storefront app, a theme may have different features and capabilities. For example, on Sunrise, supported by Proxima, is designed with a feature set very similar to Shopify themes, with native subscriptions out of the box.
Using the Swell Apps SDK, Proxima is able to fully emulate the environment that runs Shopify themes, while maintaining all of the functionality and flexibility of the Swell platform.
You might envision a different kind of storefront app with its own themes, even a fork of Proxima, with completely different features and structure that works seamlessly with the Swell Theme Editor.
Proxima emulates the Shopify theme architecture by enabling a compatibility layer which converts Swell objects into Shopify's format dynamically. This allows you to choose between using existing Shopify themes, or build to leverage Swell's native theme objects.
If you decide to follow Shopify's standard, we recommend referring to their documentation here.
Proxima automatically detects which standard to apply based on the theme's structure. For example, if a theme has a config/settings_schema.json file then it's assumed to be a Shopify theme, whereas if it has the equivalent config/editor.json, then it's assumed to be a Swell theme and will not enable the compatibility layer.
The following sections outline Swell-specific theme standards.
The structure of a Swell theme starts with the theme/ folder, and has several standard file-types as described below.
- swell.json: Swell app configuration, indicating which storefront app the theme is supported by, among other descriptive properties. See the swell.json reference for details.
- theme/
- assets/: Static assets that can be referenced within theme files.
- components/: Individual components that can be statically rendered by sections, blocks, or other components. Equivalent to Shopify snippets/.
- config/
- editor.json: Theme editor configuration. Equivalent to Shopify settings_schema.json.
- settings.json: Global theme settings which are applied during runtime and edited by the Swell Theme Editor. Equivalent to Shopify settings_data.json.
- language.json: A simpler alternative to locales for themes with fewer supported languages. See Localization below for details.
- layouts/: Theme layout files (Liquid). A page template may specify different layouts using the layout property, for example "layout": "full-page", while the default layout is theme.liquid.
- locales/: Individual locale files (JSON), following the format [iso-code].json, for example en.json. Adding a default tag to a locale file will cause it to be used by default, for example en.default.json.
- templates/: Templates for each page supported by the storefront app. See the Proxima guide for a list of templates supported by it.
- sections/: Sections that can be configured within page templates. These are the primary building block used by the Swell Theme Editor to customize pages.
A storefront app can support any given template structure. While Proxima is intended to follow a familiar set of templates such as product, category, blog, etc, there is no restriction and hierarchy or functionality of templates supported by a storefront app.
Refer to the documentation for your target app for more details.
Themes are configured in the same way for all storefront apps, allowing the Swell Theme Editor to operate on a unified standard.
See Structure above for details.
Language and currency localization is supported by Swell's core functionality, which means that products and other records are localized on an individual level, whereas theme-specific content is localized using either config/language.json or individual JSON files in the locales/ folder.
Theme editor support
The Swell Theme Editor has a language editor that allows users to change content and implement new languages in their own way. If a theme comes pre-configured with multiple languages, then the user will automatically see content for any language they have configured in General settings.
When to use language.json
For simpler themes where a smaller number of languages are configured out of the box, language.json can be used to combine one or more languages in a single file. simplifying the effort of creating language content.
Here's an example of how to configure two languages this way.
{
"general": {
"cart": {
"$locale": {
"en": {
"add_to_cart": "Add to cart"
},
"es": {
"add_to_cart": "Añadir al carrito"
}
}
},
...
},
...
}The Swell Apps SDK implements a version of Liquid, which extends the open-source library LiquidJS. It supports the majority of Shopify tags and filters.
If you're developing a Shopify theme, we recommend referring to Shopify's Liquid documentation here.
If you're developing a Swell theme, see our Liquid reference.
Rather than building a theme from scratch, your best bet to get started is by downloading an existing theme from your Swell account and getting accustomed to the structure and development workflow.
The Sunrise theme is installed by default when you create a new Swell account, however you may also create a new storefront in the dashboard under Online Store > Browse catalog.
To download a theme, use the swell theme pull command and follow the prompts.
swell theme pull
? Which environment?
❯ Live
Test
? Choose a storefront
❯ Sunrise (VdqSvJXD) [primary]
[theme] Sunrise v1.2.3 [store] example-store [env] live
Theme (176/176)
✔ [2:50:40 PM] theme/assets/account-icon.svg
✔ [2:50:40 PM] theme/assets/arrow-down-swell.svg
✔ [2:50:40 PM] theme/assets/accordion.js
...This allows you to select a storefront and download all current theme files to folder named after the theme's ID (i.e. sunrise/).
Once a theme is downloaded, you should run swell theme pull from inside that folder and will not need to complete the initial prompts multiple times, as the CLI remembers its context automatically.
Now that your theme files are downloaded, you'll use the swell theme dev command during local development, which will automatically watch for changes, rebuild JavaScript/CSS assets if configured, and re-upload to your Swell storefront.
swell theme dev
✔ Theme sync server started on port 3000
Watching for changes. View your theme at http://localhost:3000This command starts a local server on the first available port, which connects to the storefront previously selected when using swell theme pull and automatically reloads the browser when files are changed.
Note: Any changes made in your Swell account by the Swell Theme Editor may be overwritten during development.
The following CLI flags may prove useful with swell theme dev.
- --bundle: Run a bundle command when any files change, if configured in a package.json file. This is the equivalent to npm run bundle.
- --local: Connect to a local running storefront app instance. This is used when developing a storefront app (such as Proxima) and a theme together at the same time.
- --storefront-select: Select a different storefront from your Swell account to sync with. The app must be compatible with this theme.
It's helpful to know the difference between making changes to an existing installed theme, versus create a new theme and installing it on an account for the first time.
- Theme apps are installed on an account first, and then used to create individual instances along with a storefront.
- Theme instances are established when a storefront is created or cloned in the Swell dashboard under Online Store.
If your goal is to simply make changes to the look & feel of a storefront theme, then you're working with a theme instance on a specific storefront where it's already been installed. However, if your goal is to create a new theme that can be distributed to other accounts or via the App Store, then you're creating a theme app.
- Read the guide Swell's Sunrise theme.
- Read the Liquid reference for Swell themes.