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 first thing to do is initialize your app using the Swell CLI. This step establishes an entity in Swell and allows you to interact with all of the necessary configurations. The app will also be represented in your Test environment in the Swell dashboard.

Here’s an example of how to initialize an app:

swell create app

A series of prompts will allow you to specify details such as app ID and description. Once complete, a new directory matching the app ID will be created with a swell.json file, and an npm package initialized with relevant details. From here on out, CLI commands will recognize your app by its ID declared in this configuration file.

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

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 creating and managing configuration files. The following table outlines the commands you’re likely to use in managing configuration files. See the full CLI reference for more.

Swell offers JSON schemas representing each app configuration, which are recognized by most code editors and used to autocomplete and validate properties on the fly.

These schemas have been submitted to the open-source JSON Schema Store in order to make them automatically recognized by editors in the future.

In the meantime, a $schema property can be added to configuration files to enable validation in your editor. Also note this property is set by default when creating configurations using the CLI.

The following JSON schemas will be available coming soon:

Server-side validation

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.

You can work with logs via the logs CLI command:

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

swell logs --tail

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

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 changelog. 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.

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.

A merchant can roll back to an older version of your app. In that case, all configurations and functions will be replaced with the selected version. Be sure to consider this scenario when designing any approach to data migration.

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.