Now that you've familiarized yourself with the app setup and structure, we can dive into the development workflow for Swell Apps.

Before diving into development, we highly recommend reading the Apps Overview and Getting started guides.

The following table outlines the properties defined in an swell.json file. Note that all properties are optional except for id.

[TODO: move this reference into a model called swell.json]

swell.json propertyDescription
idSwell app ID.
versionApp version, starting at 1.0.0 by default.
nameThe name of your app.
descriptionA brief description of your app.
typeType of App. Either admin, integration, storefront.
permissionsArray of permission scopes for the app. Scopes are a string combination of an access level (read, write) and a collection name.

It is not necessary to specify permissions for app-defined models. Additionally, an empty array [] will grant the app full access to store data.

An app can be designated as a given type to help users understand its purpose. In the marketplace, it will be used as a top-level category. There will be secondary categories to improve discoverability in the future.

  • 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 Proxima.
  • channel: Implements an external sales channel. E.g. Amazon marketplace.

While configuration is a major aspect of developing a Swell app, the work can be simplified by leveraging a couple of key techniques.

Changes to your local configurations can be automatically synchronized to your Test environment when a change is made by enabling watch-mode via the CLI. Here’s how it works:

Watching for changes
swell app watch

This command will watch for new and updated configurations, including functions, and automatically synchronize them for testing in the Swell dashboard.

The CLI offers various commands for managing configuration files and local development. The following table outlines the commands you’re likely to use in managing configuration files. See the full CLI reference for more.

CommandDescription
swell create modelInitializes a data model in the models/ directory.
swell create contentInitializes a content model in the content/ directory.
swell create webhookInitializes a webhook in the webhooks/ directory.
swell create functionInitializes a function in the functions/ directory.
swell create notificationInitializes a notification in the notifications/ directory.
swell create settingInitializes a setting model in the settings/ directory.
swell app versionIncrements the version of your Swell App by release type or Semver rules..
swell app devStart a local development server to preview frontend changes.

App configurations are validated by Swell whenever you push changes, either manually or by using watch-mode. This can help reveal conflicts that require the platform to resolve. If a deployment is successful, you can be assured that your app configurations are valid.

During development, you’ll test your app’s functionality in your store’s Test environment. As described under our best practices, you can either enable watch-mode to push changes to the platform as you develop continuously, or you can manually invoke the swell app push command.

For testing application logic (functions), we strongly recommend that you build unit tests with a framework such as Jest. A future app review process for the App Store is likely to require substantial unit test coverage.

For testing configurations (content fields, etc), you’ll be able to see the effect of your app present in your Test environment dashboard. In addition to manual testing, we recommend implementing automated UI tests with a framework such as Playwright.

For debugging purposes, consider reviewing app logs regularly, as is covered in the next section.

App logs are designed to give you an overview of activities that your application is engaged in, as well as details of installs and version updates. Also, functions can create log entries to help with debugging.

To view app logs in the Swell dashboard, navigate to Developer > Console > Logs.

You can also view logs via the CLI logs command:

App logs
swell logs --app [id] -n 100 # show the last 100 log lines

swell logs --app [id] --tail

Swell uses semantic versioning to support the automation of updates and to notify merchants of minor and major changes throughout the lifecycle of an App.

Before updating an app in a Live environment, it’s necessary to increment the app version and provide at least a brief summary of the upgrade. Swell presents these details to merchants in the dashboard, helping them to make informed decisions about changes that might affect their experience.

Here’s an example of how to increment your App version:

Increment App version
swell version minor

In this example, the local swell.json will have its Minor version incremented by 1, indicating the new version adds new functionality but does not introduce any backward-incompatible changes. This approach should be familiar if you have experience with NPM versioning.

It’s important to consider the implications of breaking changes on a merchant’s data. If a change requires updating APIs, you must express those details in your release notes. You may want to consider implementing a migration script using a function, but you should be extremely careful about changing data that a merchant might depend on from an earlier version.

Release notes can be written to a file in your app and references when using the CLI app release command.

App release
swell app release --release-notes releases/2.0.md

Before a new version is published to the App Store (coming soon), Swell will work with you to ensure these considerations are honored, to provide the best possible experience to merchants.

App installation involves deploying configurations into a production store. You must have user-level access to the store in order to install an app. In the future, Swell will offer an App Store with easy discovery and one-click setup, however at the current time, developers can install apps in any store they have access to using the following process.

Using the CLI:

App install
swell app install

A development app is automatically installed in your store's test environment when using swell app push and related dev commands. The install command is only used to install an existing app into a different store, after creating at least one version using swell app version.

If you are updating an installed app in a live store, the CLI will require that you update the app’s version to as part of your workflow.

Using the dashboard coming soon

  • In your Test environment, navigate to Apps > Details
  • Click Install App
  • Select Install in another store and copy the link

Share this link with another user. When followed, they will be asked which Swell store they want to install the app into. You’ll be able to see installation analytics from the app details page.

For additional considerations during app development, be sure to review our best practices guidelines.