Getting started

Once you’re familiar with the structure of a Swell App, your first step is to decide what kind of app to develop. Keep in mind that an app can fulfill many capabilities at once, which allows you to package a cohesive set of functionality into a single package for merchants to use.

Before diving in, we'll need to install the CLI. You’ll use the Swell CLI to develop and install apps, so you should be comfortable using command-line interfaces, Node.js tooling, and JSON structures. Make sure you have a Swell account that has been granted access to create Apps by the Swell partner team.

Note: During development, app configurations and functions are always synced to your Test environment. When you’re ready to push an app to a Live environment, you’ll routinely use the CLI to perform installation.

To begin, run the following command in a new folder:

swell create app

@dave need an example here

Changes to your local configurations can be automatically synchronized to your development store’s 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.

An app is essentially a package of configurations and code for serverless functions. It might do something as simple as add a field to an existing model, or as complex as a multi-faceted storefront experience with many backend endpoints and dashboard views.

The following sections represent the building blocks of an app and their representation in the package.

Similarly to a package.json file, swell.json contains the main configuration details for an app, such as ID, version, and permission scopes. This file is created automatically when you run swell create app.

Contains information about the connected test store and canonical app instance. This file is created automatically by the CLI and should not need to be edited manually.

Models are used to define and manage data structures in your application. They enable you to map your data to the underlying database and create relationships between different entities. When a model is defined and installed by a Swell App, it becomes an integral part of a store’s database schema.

→ Learn more about app models

Model events allow you to track and respond to changes in your data. When a record is created, updated, or deleted, Swell checks whether certain conditions are met and generates an event record with metadata about the event. These records can be analyzed using the backend API, and are typically used to constitute activity feeds and to trigger webhooks.

→ Learn more about app events

Notifications are transactional messages designed to keep customers and admins informed about events occurring within the system. There are built-in notifications for common use cases, and the platform offers flexibility in configuring notifications, including templates, event conditions, and default contact and delivery settings.

→ Learn more about app notifications

Webhooks enable real-time communication between the Swell platform and external services, by subscribing to any number of model events. The payload structure is based on the related Event record, containing fields such as event type, event payload, and more. Webhooks are processed asynchronously and feature a highly reliable retry system.

→ Learn more about app events

App settings are a means of providing a standardized model and UI for a merchant to configure an application’s behavior. When installed, a merchant can access your app-specific settings page within the Swell dashboard. Setting values managed by the merchant are then made available to the application in configurations and via API.

→ Learn more about app settings

Views are configurations that represent fully functional, native pages in the Swell dashboard. There are two primary types of views: List (list) and Record (edit, and new). List views display collections of items, while Record views focus on displaying the details of a single item. Apps can address various use cases to help merchants manage data within the dashboard by adding Tabs and Fields to both standard and app-specific collections.

→ Learn more about app views

Coming soon

Your app can contain static assets for various purposes including images and documents. When an app is installed, it can reference metadata to retrieve a CDN URL to a named asset. One use-case, for example, is to provide a logo for your app to be displayed in the Swell dashboard and elsewhere.