# App development

Source: https://developers.swell.is/apps/app-development

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

> **Tip:** Before diving into development, we highly recommend reading the Apps [Overview](https://developers.swell.is/apps/overview) and [Getting started](https://developers.swell.is/apps/getting-started) guides.

#### App configuration

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](https://developers.swell.is/apps/swell-json)

#### App types

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.

- `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](https://developers.swell.is/storefronts/proxima-app).
- `channel`: Implements an external sales channel. E.g. Amazon marketplace.

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.

### Running your app locally

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

**Run an app in dev mode**

```txt
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](https://developers.swell.is/apps/cli#app-dev) in the CLI reference.

### Configuration

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

#### Watching for changes

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:

**Watching for changes**

```txt
swell app watch
```

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

#### Other CLI commands

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](https://developers.swell.is/apps/cli) for more.

| Command | Description |
| --- | --- |
| swell create model | Initializes a data model in the models/ directory. |
| swell create content | Initializes a content model in the content/ directory. |
| swell create webhook | Initializes a webhook in the webhooks/ directory. |
| swell create function | Initializes a function in the functions/ directory. |
| swell create notification | Initializes a notification in the notifications/ directory. |
| swell create setting | Initializes a setting model in the settings/ directory. |
| swell create frontend | Initializes a frontend framework and folder structure. |
| swell create tests | Scaffolds a Vitest + Workers test setup that reuses CLI authentication. |
| swell app dev | Runs the app locally, serving its functions and frontend on your machine. |
| swell app push | Pushes configurations to your test environment. |
| swell app pull | Pulls an app’s files from a store to your machine. |
| swell app version | Increments the version of your Swell app by release type or Semver rules. |
| swell app info | Shows the app’s name, description, version, public ID and test store. |

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

### Testing

During development, you’ll test your app’s functionality in your store’s Test environment. As described under our [best practices](https://developers.swell.is/apps/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](https://playwright.dev/).

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

### Logging

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

```txt
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`.

### Versioning

Swell uses [semantic versioning](https://semver.org/) 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**

```txt
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](https://docs.npmjs.com/cli/v8/commands/npm-version).

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

#### Breaking changes

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.

**App release**

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

### Releasing

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.

**Release a version**

```txt
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](https://developers.swell.is/apps/app-store-submission) for the full list of requirements.

- no storefront-only listing fields on an app of another type

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](https://developers.swell.is/apps/app-store-submission) for submitting the release for review and publishing it to the App Store.

### Installing

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

Using the CLI:

**App install**

```txt
swell app install
```

> **Note:** 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 as part of your workflow.

-> Installing published apps, and the merchant side of installation, is covered in [App distribution](https://developers.swell.is/apps/distribution).

### Next steps

For additional considerations during app development, be sure to review [best practices](https://developers.swell.is/apps/best-practices). When your app is ready for merchants, see [App Store submission](https://developers.swell.is/apps/app-store-submission).