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 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]

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.

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:

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 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:

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:

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.

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:

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 to as part of your workflow.

Using the dashboard coming soon

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.