App development

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

The swell.json file contains the main configuration properties for an app, such as its type, ID, version, permissions, compatibilities, App Store listing details, and more.

-> See the swell.json reference

An app is designated as a given type, which tells merchants what it’s for and acts as its top-level category in the Swell App Store. Categories refine that further — an app can list several, and they drive filtering in the App Store.

The type also decides which listing details apply. preview_image, use_cases, purchase_options and features belong to storefronts and themes — an app of any other type is rejected at release for setting them. Every other listing field, including logo_icon, images and highlights, is open to all types.

swell app dev runs your app on your own machine. Functions are bundled and served in the same Workers runtime they run in on Swell, so what you exercise locally behaves the way it will in a store.

swell app dev

On start, the command pushes your current configurations, then prints every function it’s serving along with the trigger that fires it — a route with its methods, a model event, or a cron schedule. Edit a function and it reloads. Workflow functions are the exception: they deploy through swell app push rather than running locally.

For a storefront app, the dev server also starts your frontend and serves it against a storefront you choose, so you can see the app rendering real store data while you work. Pass --function to run a single function on its own when you want a tighter loop.

-> For every flag, see app dev in the CLI reference.

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

Where swell app dev runs the app locally, watch-mode keeps your Test environment in step instead — useful when you want to work against the dashboard rather than localhost. Changes to your local configurations are synchronized as you save them. Here’s how it works:

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.

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 run the app locally with swell app dev, enable watch-mode to push changes to the platform as you develop continuously, or 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 Vitest. The swell create tests command scaffolds a ready-to-use test setup configured for the Cloudflare Workers runtime.

Every release is reviewed by the Swell team before it can be published, and test coverage is part of what reviewers look for. Building it as you go is far easier than retrofitting it at review time.

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:

swell logs --app . -n 100   # show the last 100 log lines

swell logs --app . -f       # follow new entries as they arrive

--app takes an app id or slug, or . to use the app in the current swell.json.

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:

swell app 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.

swell app version on its own prints the current version. The command commits the change and tags it in Git — pass -m to set the message, or --no-git-tag to skip the tag.

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 referenced when you release.

swell app release 2.0.0 --release-notes releases/v2.0.0.md

A version is all you need to install an app — any store you have access to can run it. Releasing is a separate step with one purpose: it puts a version forward to be published in the App Store, and Swell reviews it before it goes live.

swell app release

Releasing your app requires it to be connected to a partner account with permission to publish. If the version doesn’t exist yet, the CLI offers to create it.

Swell validates your listing details before accepting a release, and the release fails if anything a listing needs is missing. See App Store submission for the full list of requirements.

Other flags worth knowing: --amend updates the description or release notes of an existing release, and --not-supported marks a version you don’t officially support.

-> From here, see App Store submission for submitting the release for review and publishing it to the App Store.

Installing deploys an app’s configurations into a store, and you need user-level access to that store to do it.

Using the CLI:

swell app install

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

-> Installing published apps, and the merchant side of installation, is covered in App distribution.

For additional considerations during app development, be sure to review best practices. When your app is ready for merchants, see App Store submission.