Apps
Fields
ID of the app, used to identify itself in code. For example, my_app.
Name of the app.
Type of the app. Some configurations apply differently based on the type of app. Defaults to admin.
admin: Enhances functionality of the Swell Admin dashboard or API.
integration: Integrates with an external service. E.g., an email provider or payment gateway.
storefront: Implements a storefront experience. E.g., a store website, page builder, or checkout.
theme: A theme created for a specific storefront app, for example Wave or Proxima.
channel: Implements an external sales channel. E.g. Amazon marketplace.
For storefront apps, what the storefront is. Only a shop storefront can create storefronts, and it needs a desktop preview image to release.
shop: A store website. The default for storefront apps.
checkout: A checkout.
account: A customer account portal.
Swell sets extension itself for an app that has extensions but no storefront or theme.
Indicates whether the app is a companion app, which comes with a theme and has no listing of its own in the Swell App Store. A companion app is always free. Defaults to false. See Companion apps.
Semver-formatted version number. swell app version increments it. swell create app writes 1.0.0; an app record created without a version starts at 0.1.0.
A brief description of the app, shown as the tagline in the App Store catalog. Maximum 70 characters. Required to release.
An array of permission scopes limiting which store data the app can access. When a merchant installs the app, Swell issues it an access token restricted to the scopes declared here.
Defaults to [], which grants unrestricted access to store data. Apps published to the Swell App Store must declare the specific scopes they need.
Each scope combines an access level with a collection name:
- read_{collection}: grants read access. For example, read_orders.
- write_{collection}: grants read and write access. write_orders also covers read_orders, so there is no need to declare both.
Use the base collection name. read_accounts also covers its child collections, such as accounts:cards.
It is not necessary to declare scopes for resources your app defines. An app always has full access to its own models, settings, and app record.
Permissions are recorded with each version of your app. The scopes granted on install are those declared by the version the merchant installs, so changing them takes effect with your next released version.
Declares that the app uses AI through Swell. AI is on by default when a store installs the app, and merchants can turn it off for each installation; installs created by swell app push start with it off, and removing ai turns it off for them. Each version keeps its own ai. See AI.
What the app uses AI for. Maximum 200 characters. ai takes no other keys.
Configures the app's storefront features. Any app can declare embeds, data and actions, which add embed blocks, data sources and form actions to Wave storefronts. See Storefront extensions. menus, theme, external, editor, context and theme_updates are for storefront apps only.
Default navigation menus instantiated when the app is installed.
ID of the menu, may be used to reference specific menus from a storefront app or theme.
Name of the menu for display purposes in the Swell dashboard.
The menu items.
Type of menu item rendered by the storefront app or theme.
- home: Link to the home page.
- search: Link to a search page with an optional pre-defined query.
- product: Link to a product detail page.
- product_list: Link to a page listing all products.
- category: Link to a category of products.
- page: Link to a content page.
- blog: Link to a blog post.
- blog_category: Link to a page listing all blogs in a category.
- content: Link to a content entry.
- content_list: Link to a page listing all content entries.
- url: Link to a specified URL.
- heading: Display a heading above a set of menu items.
Name of the item to be displayed in the storefront app or theme.
For product, category, page, blog, blog_category, content, content_list, and url types only, defines the value used to construct a link in the storefront app or theme. For example, a page item would have a value referencing page.slug.
A sub-menu of items. The sub-items of an item are of the same schema as the top-level items property.
For storefront apps that support themes only, defines attributes of theme support and functionality.
Determines whether the theme is provided by an app or self-contained. Defaults to self.
app: Supports loading separate theme apps.
self: Provides its own theme, supporting Swell's Theme Editor without a separate theme app.
Note: Support for self contained themes is still a work in progress.
Defines attributes of compatibility between the storefront app and its supported themes, if provider: app.
- version: Indicates that this app only supports themes which are themselves compatible with this storefront app version.
- For example, compatibility.version: 2.* indicates themes which are themselves compatible with storefront app version: 1.* will not be supported.
- conflicts: Indicate paths or files that should be checked for change conflicts before being automatically updated (overwritten) during a theme version upgrade.
- For example, specifying compatibility.conflicts.exclude_files: ['theme/config/**'] indicates that changes to any theme config files will not be overwritten during a theme upgrade and will not count as a conflict.
Semver-formatted version range indicating the version that themes must be compatible with in order to be supported by this storefront app. For example, version: * indicates that all themes are supported, while version: 1.* indicates that only themes made for storefront app version 1.* are supported. Defaults to the storefront app's own version.
-> See the semver package on npm for a detailed explanation of ranges.
Configures which files or file paths are considered when performing conflict checks during theme version upgrades.
List of files or file paths starting from theme/ that are excluded during theme upgrade conflict checks.
List of files or file paths starting from theme/ that are included during theme upgrade conflict checks.
Map of resources to their respective class names, which are typically instantiated to customize resource logic by the storefront app. If applicable, the app must define a /resources/[slug].json endpoint which allows the Swell Theme Editor to load data from the app when necessary.
-> See the Proxima app documentation for details.
Resources are split into two categories:
- singletons: One-off records such as Account and Cart.
- records: All other resources that may be instantiated multiple times throughout a storefront app.
Map of singleton resources to their respective classes in the storefront app. For example, cart: CartResource.
Resource class name provided by the storefront app, for example CartResource.
Map of record resources to their respective classes in the storefront app. For example, products: ProductResource.
Resource class name provided by the storefront app, for example ProductResource.
List of page templates supported by the storefront app, to be displayed in the Swell Theme Editor.
ID of the page, typically corresponding to its file path within a theme app. For example, index to identify the home page.
Label of the page template displayed in the Swell Theme Editor. For example, Home to indicate the home page.
URL of the page route defined by the storefront app. May contain named segments starting with a colon : that are parsed into page parameters at runtime. For example, /products/:slug would indicate a product page route with a slug parameter.
Optional string indicating the icon to display for the page template in the Swell Theme Editor.
The model collection associated with this page, if applicable. Typically a home page would not have a collection, while a product detail page would specify collection: products for example.
A string used to group pages in the page template menu. For example, you might group all account pages with group: customer.
Indicates the page template has a JSON endpoint for fetching page data by the Swell Theme Editor. A JSON endpoint may be provided by the storefront app to supply objects required to render a page initially. The JSON route defined by the storefront app should match the end-user route, adding .json as a suffix.
For example, a product detail page might have a user-facing route such as /products/[slug], and then the corresponding JSON endpoint must be /products/slug.json and must return valid JSON representing the entire data set used to render the page.
For provider: app storefronts only, an array of forms accepted by themes using the form liquid tag (Shopify reference). The storefront app must implement each form configured by this property, according to its own purpose.
ID of the form, used by the form liquid tag.
URL endpoint defined by the storefront app to accept a POST request when the form is submitted.
For provider: app storefronts only, an optional map of collections that are rendered by record-based page templates. For example, products: product would indicate the product detail page supports alternate templates defined within the products collection, assuming page.id: product.
Defines the relationship between a collection and a page that supports record-based templates. For example, [collection]: [page.id].
For provider: app storefronts only, an optional endpoint defined by the storefront used to cache theme pages. The endpoint will be invoked when ever a theme template or file is updated, allowing the theme to leverage its own cache mechanisms.
For storefront apps that are hosted externally, configures the external URLs used to access the storefront.
URL of an external storefront that would display a merchant's online store when accessed. May include dynamic setting values, for example http://example.com/store/{{ merchant_id }}.
URL of an external checkout interface that would display a merchant's checkout when accessed. May include dynamic setting values, for example http://example.com/checkout/{{ merchant_id }}/{{ checkout_id }}.
Note: At the time of this writing, this feature is not fully supported.
An editor provided by the storefront app itself, shown in the dashboard in place of the standard theme editor.
Label of the editor action in the dashboard. Defaults to Open editor.
URL of the editor. Required when editor is set: push fails with storefront.editor.link is required without it. A frontend:// link opens the app's own storefront frontend, embedded in the dashboard. An http:// or https:// URL opens in a new tab. May include storefront values, for example ?storefront={id}.
Headers passed to an embedded frontend:// editor. Push refuses them for any other link, and a header name can't start with Swell-.
Header value. May include storefront values, for example {id}.
For storefront apps only. Set to summary to receive a shorter shopper context in the Swell-Storefront-Context header of each storefront request: the cart's id and item_quantity, and the signed-in account's id, email, first_name, last_name, name and group.
Without it, the header carries the whole cart and account, which Swell reads with their products and promotions on every request from a shopper with a cart. With summary, fetch the cart from the Storefront API when a page needs its items.
For storefront apps only. Set to app when the storefront app applies theme updates in its own editor: the dashboard then sends merchants there instead of offering its own update. No other value has an effect.
Embed blocks that merchants place on Wave storefront pages, and the script that renders them. Any app can declare them. See Storefront extensions.
Version of the app block standard. Must be 1.
The block script, as frontend://<path>, up to 500 characters. Required when a block renders with script.
auto, or a sha256-, sha384- or sha512- hash in base64. With auto, push computes the sha384 of frontend/public/<path> and adds ?v= to the script's URL.
Up to 10 origins the script can connect to.
Up to 10 origins blocks can load images from.
The app's blocks, 1 to 20.
ID of the block: lowercase letters, digits and underscores, up to 40 characters.
Name of the block in the storefront editor. Maximum 80 characters.
What the block does. Maximum 300 characters.
Icon name: lowercase letters, digits and hyphens, up to 40 characters.
How the block renders: with the app's script, or as a UI component.
Possible enum values:
For component blocks, the name of a top-level file in the app's components/ folder.
Page types the block can be placed on.
Up to 20 settings for the block.
ID of the prop.
Type of the prop.
Possible enum values:
Label shown in the storefront editor.
Help text shown with the prop.
Default value. A text default can be up to 500 characters.
For select props only, 1 to 50 choices, each {value, label}.
For number props only, the lowest value.
For number props only, the highest value.
Up to 20 data sources that Wave themes read and render on the server. Any app can declare them. See Storefront extensions.
ID of the data source.
Name of the data source in the storefront editor.
What the data source provides.
What the data is about. An account source must filter on $account.id.
Possible enum values:
Where the data comes from: {function}, or {collection, where, fields, sort, limit}.
Name of one of the app's functions that returns the data.
Collection to read, such as one of the app's models.
Up to 10 field filters. Values can use $account.id, $product.id, $category.id and $storefront.id.
Value the field must match.
1 to 30 fields to return.
<field>, or <field> asc or <field> desc.
Number of records, 1 to 100.
Seconds to cache the result, 0 to 3600.
Sample data, which storefront editors render. JSON of at most 8 KB.
Up to 20 form actions that Wave themes post to one of the app's functions. Any app can declare them. See Storefront extensions.
ID of the action.
Name of the action.
What the action does.
Name of the app function the form posts to.
account when the shopper must be signed in. Defaults to none.
Possible enum values:
The form's fields, 1 to 30.
ID of the field.
Type of the field.
Possible enum values:
Indicates whether the field must have a value.
Maximum length, for text (up to 5,000), textarea (up to 50,000) or hidden (up to 500).
For select fields only, 1 to 100 choices, each a string.
What the storefront may do with the function's result.
For theme apps only, configures theme properties including storefront app compatibility, the apps the theme names, its Theme Store listing and style presets.
Defines which storefront app and versions are compatible with this theme.
ID of the storefront app the theme is for, such as wave or proxima. Defaults to proxima, so a Wave theme sets wave. The theme works only with the storefront app whose id matches.
Defines attributes of compatibility between a theme and the storefront app which supports it.
Semver-formatted version range indicating the version of a storefront app that this theme is compatible with. For example, version: * indicates that all storefront app versions are compatible, while version: 1.* indicates that only storefront app version 1.* is compatible.
Defaults to all versions *.
-> See the semver package on npm for a detailed explanation of ranges.
Apps the theme names: its companion apps, and any other apps it requires or works with. At most 10, each named once. See Companion apps.
When a merchant installs the theme or creates a storefront from it, Swell installs every companion app it names that the store doesn't have. Apps that aren't companions are listed on the theme's page in the dashboard, and the merchant installs them separately.
Each id must name an existing app when the theme is pushed, so push an app before the theme that names it.
ID of the app: the id of one of your own apps, or the public ID of a published app. Lowercase letters, digits, underscores and hyphens, up to 40 characters.
Indicates whether the theme requires the app. The dashboard and the Wave editor warn when a required app isn't installed. Defaults to false.
Lowest version of the app the theme works with, as an exact version such as 1.2.0, not a range. When the theme is installed or updated, Swell updates a companion app installed below this version.
What the app does for the theme, shown to merchants with the app on the theme's page and in its install dialog. Maximum 200 characters.
How the theme is listed in the Theme Store on swell.is: its filters, a short line on who it's for, and its demo. The Theme Store reads it from the theme's published version. See Selling themes for the filter values.
Industries the theme is listed under, such as fashion or food_drink.
Looks the theme is listed under, such as minimal or editorial. These are filter values, not the style presets in theme.styles.
Features the theme is listed under, such as subscriptions or mega_menu.
Catalog sizes the theme suits, from one for a single product to lots for a large catalog.
A short line on the stores the theme suits, for its Theme Store listing.
URL of the theme's demo frame on its demo storefront's preview host: https://<store>--<storefront>--preview.swell.store/__demo. Use the preview host, since a test storefront's own address is visible only to the store's admins. The Theme Store's View demo button opens it.
The storefront must run the theme in a store of yours: one of your development stores, or the store that owns the theme app. A demo_url that names a storefront in any other store does nothing. See Selling themes.
Optional array of styles to configure theme presets and their preview images and colors, and demo URL, to be displayed in the Storefront Theme catalog. These styles should correlate with presets defined by theme settings.
ID of the theme preset, for example dark or light. Required, and unique among the styles.
Label to display as the name of the theme preset.
Primary hexadecimal color value to display as a thumbnail, representing the majority of the color palette in the style preset.
Secondary hexadecimal color value to display as a thumbnail, along with the primary color.
Relative path of an image asset representing the desktop preview of the theme. For example, assets/preview-dark.jpg.
Relative path of an image asset representing the mobile preview of the theme. For example, assets/preview-dark-mobile.jpg.
URL of a demo store showcasing the theme style preset.
For theme apps, a map of storefront app IDs to semver ranges: the versions of each storefront app the theme works with. The CLI uses its keys to find theme apps for a storefront app with storefront.theme.provider: app, and the dashboard checks the range. Each version keeps its own.
Semver range of the storefront app's versions, for example 1.*.
Configures how the app's frontend is hosted. See Frontend.
Where the frontend runs. When omitted, the frontend is self-hosted.
- managed: Swell hosts the frontend on its own Cloudflare account. Supports Vinext, and client-side React with Vite.
- self-hosted: the CLI deploys the frontend with Wrangler to your own Cloudflare account.
swell create app --frontend and swell create frontend set this value from the chosen template. To move a managed frontend to self-hosted, set self-hosted explicitly.
For self-hosted frontends, the URL of the deployed frontend. After deploying with Wrangler, the CLI sets it on the app record, not in swell.json. A url in swell.json is sent only when hosting isn't managed.
Path of the app's icon image, under assets/. Defaults to assets/icon.*. Every app type except theme needs an icon to release.
For storefront and theme apps only, path of the desktop preview image shown in the App Store catalog, under assets/. Defaults to assets/preview.*. Required to release a storefront app of kind shop whose storefront.theme.provider isn't app. Release fails if another app type has a preview image.
For storefront and theme apps only, path of the mobile preview image shown in the App Store catalog, under assets/. Defaults to assets/preview-mobile.*.
Gallery images shown in the App Store catalog. Each item describes one image and points to a file with image_src. Images are shown in array order and the first four are displayed. At least one image is required to release, except for theme apps.
id: Required. Unique identifier for the image.
title: Optional. Maximum 40 characters. Shown in the gallery.
description: Optional. Maximum 140 characters.
image_src: Required. Path to the image file, for example assets/screenshots/dashboard.png. Image paths, here and in highlights, preview_src, preview_mobile_src, logo_src and theme.styles, must be under assets/; the CLI warns about others.
ID of the image. For example, products.
Title to display as the name of the image.
Relative path of the image asset. For example, assets/screenshots/products.jpg.
Feature highlights, for any app type, each with a title, a description and an optional image. The dashboard's new-storefront page shows a storefront or theme app's highlights as its features, and the partner dashboard shows them for every app. The App Store listing doesn't show them.
ID of the highlight. Required.
Title of the feature highlight. Maximum 40 characters.
Text description of the feature. Required. Maximum 140 characters.
Path of an image for the highlight, under assets/. For example, assets/feature-sleek-design.jpg.
For storefront and theme apps only, list of enumerated features to associate with in the App Store catalog.
- multi_currency: Multi-currency apps support selling in multiple currencies.
- multi_language: Multi-language apps support selling in multiple languages.
- bulk_pricing: Bulk pricing apps support selling in bulk.
- account_pricing: Account pricing apps support selling to different customer groups.
More feature enumerations are coming soon.
Release fails if an app that isn't a storefront or theme sets it.
For storefront and theme apps only, list of enumerated use-cases to associate with in the App Store catalog.
- direct_to_consumer: Direct to consumer apps are designed for selling directly to consumers.
- wholesale: Wholesale apps are designed for selling to other businesses.
- marketplace: Marketplace apps are designed for selling products from multiple vendors.
- digital_goods: Digital goods apps are designed for selling digital products.
More use-case enumerations are coming soon.
Release fails if an app that isn't a storefront or theme sets it.
For storefront and theme apps only, list of enumerated purchase-options to associate with in the App Store catalog. Release fails if another app type sets it.
standard: Sell one-time purchases.
subscription: Sell recurring purchases on a schedule.
A longer text description of the app's features and capabilities, displayed in the App Store catalog. Optional.
Set from DESCRIPTION.md in the app root, truncated at 20,000 characters. It cannot be set in swell.json.
URL of a website where users can see a demonstration of the app's features and capabilities.
For theme apps, the Theme Store's demo is theme.listing.demo_url.
YouTube embed URL of a video demonstrating the app, shown first in the App Store gallery.
If the app developer offers support to merchants, URL of the website where a user can get help with the app.
Email address merchants can contact for help with the app. When empty, the support email of your partner account is shown instead.
If the app provides written documentation to merchants, URL of the website where a user can get read the docs.
If the app is open-source, URL of the website where a user can find a Git repository of the app's code base.
List of extensions the app implements to integrate with core platform features such as payments, shipping, and tax calculation. Extension events are handled by app functions. See the Extensions guide for details.
Unique ID of the extension, referenced by the functions that implement its events.
Human-friendly name of the extension.
Text description of the extension.
Type of platform feature the extension implements.
- payment: Implements a payment gateway.
- shipping: Implements shipment rating and price calculation.
- tax: Implements tax calculation.
ID of the app setting associated with the extension.
For payment extensions, ID of the payment method. Defaults to the extension id.
For payment extensions, indicates whether the payment method supports subscriptions. Swell's checkout offers the method for a cart with a subscription item only when this is true. Defaults to false.
For payment extensions, relative path of an icon image asset for the payment method.
For payment extensions, relative path of a logo image asset for the payment gateway.
For payment extensions, relative path of an icon image asset for the payment gateway.
For shipping extensions, relative path of an icon image asset for the carrier.
An array of identifiers for the areas the app operates in, used to detect conflicts with other apps and with Swell integrations. Values can be the ids of Swell integrations or your own custom ids, such as ["klaviyo", "algolia", "myownid"].
A conflict is reported when an integration is already running under one of the listed ids, or when a running app lists one of this app's ids in its own integrations. Each conflict can be ignored, or the conflicting integrations and apps can be disabled.
Swell checks for conflicts when an app is installed from the marketplace, when a disabled app is enabled again, and when an integration is enabled. The Swell CLI runs the same check when an app is pushed for the first time, when a pushed app's integrations list has changed, and when an app is installed.
No checks are performed when integrations is omitted.
The swell.json model
{
"id": "honest_reviews",
"name": "Honest Reviews",
"description": "Honest reviews from honest people",
"version": "1.0.6",
"type": "admin",
"permissions": [
"read_orders",
"write_products",
"write_accounts"
]
}