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.

Note: During development, app files 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.

npm install -g @swell/cli

Login to your Swell account. If you are not already logged in, this command will open your browser to the Swell Admin login page, otherwise, it will show you the stores that are accessible by your account.

swell login

The following command will walk you through prompts to build an app for the first time:

swell create app

If you're looking for more of a boilerplate setup, use the swell app init command:

swell app init

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.

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

→ See the swell.json reference

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

A frontend is a Node.js app, built with one a number of supported frameworks include Next.js, Astro, and others, and can serve different use cases including storefront apps, admin apps, and integrations. Coming soon: the ability to embed frontend interfaces in various areas of the Swell dashboard. Prior to this, the primary use case for frontends is storefront apps.

→ Learn more about app frontends

These are a special kind of app intended to simplify storefront customization for merchants by isolating the look and feel of a store from its backend functionality. Initially Proxima app was released to support Shopify 2.0 themes, however a storefront app may implement any number of structures and features using themes. The Swell storefront editor supports the familiar pattern of using sections and blocks to allow merchants to visually edit their online store.

→ Learn more about theme apps

Data 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 data models

Content models are configurations that represent fully functional, native fields and pages in the Swell dashboard. There are two primary types of content 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 content models

App functions are deployed as cloud workers and configured to respond to system and app-specific events. Developers have great flexibility in how these events are processed, with the ability to enhance API queries, seamlessly modify data results, and even run scheduled jobs. Detailed logging makes them observable from the Swell dashboard and CLI.

→ Learn more about app functions

Configure specialized model events 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 events are typically used to trigger webhooks and app functions, reducing overhead by having Swell's backend perform real-time event notifications to your endpoints instead of polling for changes in code.

→ 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

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.

-> Learn more about app assets