An application is only as useful as the system it operates on. Swell provides deep configurability in a cloud-based environment, which allows apps to solve the most important and complex challenges faced by merchants, without the headaches of maintaining their own software and infrastructure.

With Swell, apps have a unique ability to package low-level functionality, for example, by enhancing or adding to a store’s native API. In a sense, we’re giving back control to merchants by enabling apps that can unify their data, APIs, admin workflows, and storefront experiences, all in one place.

The Swell app architecture is uniquely positioned to provide the ultimate control over various areas of configuration within your Swell store. You can find an illustration of the app architecture below:

 can alter a store’s database schema, either by adding fields to existing models (like products and orders) or creating completely new ones. They can also define API endpoints for CRUD requests, and display UI in the dashboard for admins to view and edit content.

Files, including images and other types, can be stored natively in a store’s database using file fields within an app-specific or standard model. When retrieved using the automatically assigned URL, the file will get cached and served by the Swell CDN. Images can be transformed on the fly using a set of query parameters.

 can be configured to fire when certain conditions are met. These can be used to trigger functions and webhooks, send notifications, or simply observe when something in the system happens that you want to keep track of.

 for sending emails to admins or users when certain conditions are met.

 can be configured to call a URL when a particular event occurs, enabling outgoing calls to external services.

 to run custom code. They can be triggered by events, a cron schedule, or via URL to enable incoming calls from external services. Functions are deployed to edge data centers in 200+ locations and have no cold start time.

 provide a way for merchants to install and configure apps in the dashboard.

 define a full-page structure for displaying collections and records in the dashboard.

 are a way to trigger custom logic in dashboard views by calling directly to an app function and configuring how the response is handled.

 define conditions and formatting for displaying event information in dashboard activity feeds, either in aggregate or for a single record.

 are small components for viewing and editing content/data in the dashboard. They can either target a single field or a group of fields.

Introduction

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 

 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 

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

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:

Start the development server

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.

 contains the main configuration details for an app, such as ID, version, and permission scopes. This file is created automatically when you run 

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.

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.

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.

Webhooks enable real-time communication between the Swell platform and external services, by subscribing to any number of 

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

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.

Views are configurations that represent fully functional, native pages in the Swell dashboard. There are two primary types of views: List (

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

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.

Getting started

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:

Create a Swell 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 

 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 

 file. Note that all properties are optional except for 

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.

: Enhances functionality of the Swell Admin dashboard or API.

: Integrates with an external service. E.g., an email provider or payment gateway.

: Implements a storefront experience. E.g., a store website, page builder, or checkout.

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:

Watching for changes

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 

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 

 in order to make them automatically recognized by editors in the future.

 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.

models/things.json

The following JSON schemas will be available 

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 

, you can either enable watch-mode to push changes to the platform as you develop continuously, or you can manually invoke the 

For testing application logic (functions), we strongly recommend that you build unit tests with a framework such as 

. 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 

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.

Swell app logs

To view logs in the Swell dashboard, navigate to 

 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 Swell App version

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 

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 (

), 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.

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.

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 

App development

In the early stages, Swell will support manual app installation using a secure installation link (

). This link can be obtained from the CLI or the admin dashboard, allowing you to share it with merchant users for a seamless installation process.

During the Alpha and Beta phases, developers will have the ability to manage apps for any given store. They will be able to access details about where apps are installed and the versions currently in use.

Swell is planning to develop a comprehensive marketplace for app discoverability in 2024. The marketplace will provide an enhanced platform for Swell app developers to showcase their ideas and reach a larger audience of merchants.

In the meantime, it is essential for developers to focus on creating high-quality apps, following best practices, and providing excellent support to their merchant users. This will ensure a smooth transition to the upcoming Swell marketplace and create a strong foundation for success in the Swell ecosystem.

Coming soon, you’ll be able to generate a secure installation link for an app using the Swell CLI or from the admin dashboard. Until then, use the CLI.

: Use the appropriate command in the Swell CLI to install the app in another store environment.

App installation

Install the App using the installation link 

Click on the secure installation link provided by the developer. This will open the Swell admin dashboard in your browser.

Log in to your Swell account if you haven't already. After logging in, you will be redirected to the app installation page.

Review the app details and permissions. Make sure to read and understand the app's functionality and the data it accesses before proceeding.

 button to begin the installation process. The app will be installed and configured for your store.

Once the installation is complete, you can start using the app and explore its features from the Swell admin dashboard.

We're thrilled to see what you'll create using the Swell platform, and we're committed to continuously evolving and improving our ecosystem to support you. With our upcoming app marketplace, we're looking forward to fostering an environment where developers and merchants can connect and collaborate seamlessly.

Thank you for being a part of the Swell community, and we can't wait to see the amazing things you'll build. Let's make the world of e-commerce more powerful, flexible, and customizable together.

App distribution

In the course of developing a Swell app, you should be aware of a few best practices to ensure your apps are efficient in a large scale production environment. For example, when offering an open-source app, the merchant is responsible for the cost of resources consumed, and in turn could be frustrated by an inefficient implementation.

Performance and security optimization will be a constant focus for Swell as the ecosystem expands. During an app review process, you might encounter questions or feedback related to the patterns you’ve implemented.

For the good of merchants everywhere, we recommend you follow this guide to stay ahead of the curve.

Models, functions calls, API calls, and data storage are the key aspects impacting overall application performance. The simplest way to optimize, is to minimize the impact of each of these aspects as it relates specifically to your app.

Before diving into development, spend time analyzing and understanding the data structure your app will require.

Use consistent naming contentions. Your models and fields will become an important part of a consumer’s implementation. Prefer lowercase letters and underscores for app fields (e.g., 

Consider adding model events specific for your app, instead of subscribing to simple 

 events that have to be filtered at the function-level.

Be careful about function runtime. Depending on the merchant’s Swell, long running functions could result in errors that render an application useless.

For smaller merchants in particular, make sure to implement graceful timeouts and notification mechanisms to account for potentially long-running functions.

Debounce techniques can help you limit the frequency of API calls, reducing the load on your server and preventing unnecessary requests.

Use pagination and filtering techniques to retrieve only the data your app needs at a given time.

Consider using batch requests to combine API calls into a single request.

Only store the data that is absolutely necessary for your app to function.

Organize your data in a structured and logical manner using appropriate collections, fields, and relationships.

Depending on your use-case, consider establishing data retention policies.

Ensure that sensitive data, such as personally identifiable information (PII) or payment details, is stored securely and protected from unauthorized access. Implement proper access controls, encryption, and other security measures to safeguard the data your App stores in a merchant's account.

It is imperative to ensure the security of merchant data and functionality. To help you maintain a high level of security, consider the following best practices:

: Assign the minimum required permissions to access resources within your app. This helps prevent unauthorized access and reduces the potential impact in case of a security breach.

: Always validate and sanitize user input to prevent security vulnerabilities such as query injection and cross-site scripting (XSS).

: Encrypt sensitive data and use secure methods for transmitting them externally.

: Keep your app's dependencies up-to-date to prevent security vulnerabilities from outdated libraries or packages.

: Implement proper error handling in your app to prevent information leaks that could expose sensitive data or provide hints for potential attackers.

: Continuously monitor and audit your app to detect any security issues or breaches, and have a plan in place to respond to such incidents.

Implementing a comprehensive testing strategy ensures that your app works as expected, reduces the risk of errors, and provides a smooth user experience. Consider the following best practices when testing your Swell app:

: Outline your test scenarios and test cases. This plan will serve as a guide throughout the testing process and help ensure complete test coverage.

: Employ various testing techniques, such as unit testing, integration testing, and end-to-end testing, to identify potential issues at different levels of your app.

: Test your app on a range of devices and browsers to ensure compatibility and a consistent user experience across different platforms.

: Use realistic data sets during testing to accurately simulate user interactions and evaluate your App's performance under real-world conditions.

: Assess your app's performance under varying loads and stress conditions to identify potential bottlenecks and ensure it can handle increased traffic.

: Integrate testing into your development process to catch issues early and ensure that new changes do not introduce unexpected errors.

Best practices

Welcome! This reference outlines the available commands of the Swell CLI. To get started, install the Alpha version:

Install Swell CLI alpha

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 you still have available for logging in to.

 show all available stores and switch if already logged in

Log out of all stores available in your current session.

If you have access to multiple stores, this command will define the store that all other commands will apply to by default.

Scaffold apps, models, functions, and notifications.

 initialize an app with config file and folder structure

 initialize a data model config file with properties in the models folder

 initialize a content UI model config file with properties in the content folder

 initialize a functions script in JavaScript or TypeScript

 initialize notification files and configuration with properties in the notifications folder

If npm or yarn are available, initiate a package with 

. By default, apps have full access to store data. Edit 

 to narrow down permissions before publishing an app.

 package manager used to install default dependencies, one of 

 skip prompts and accept defaults, overwriting existing files, should only be used with 

Initialize a data model config file with properties in the models folder.

CLI will prompt for values when flags are not present.

: collection to create or apply to, i.e. products

 list of data model events delimited by commas, defaults to 

 list of data model fields delimited by commas, in the format of 

 overwrite existing data model configuration, if existing

 path to the app directory, defaults to the current directory

Initialize a content UI model config file with properties in the content folder.

 list of content fields delimited by commas, in the format of 

 list of content views delimited by commas, i.e. 

 overwrite existing model configuration, if existing

Initialize a functions script in JavaScript or TypeScript.

 function name, used in an http route if applicable

Initialize notification files and configuration with properties in the notifications folder.

CLI reference

Frontend

Themes

Once a model is defined, Swell dynamically generates backend API endpoints, eliminating the need to manually create custom endpoints for backend services, and streamlining the process of exposing your data to the frontend or other services.

A model schema supports various field types, such as scalar values, arrays, nested objects, and links to other models, allowing you to create diverse data structures. Links help establish relationships between models, making it easier to navigate and work with related data. Scalar field types include basic data types such as strings, integers, and booleans. Arrays allow for collections of values, while nested objects enable you to create complex, hierarchical data structures.

Models include built-in validation and type coercion mechanisms. The key principle is to ensure that your data is consistent without being overly rigid and hard to work with. Validation constraints include required fields, unique constraints, and custom validation rules. Automatic type coercion ensures that API input data is converted to the appropriate data type when querying and creating records.

 can be configured to emit when a specific action occurs, such as creating, updating, or deleting a record with specific properties. 

 can be subscribed to these events. Triggers are model-defined actions that respond to record conditions and can be used to propagate changes to other records automatically. By using events and triggers, you can create a dynamic and responsive application that automatically reacts to changes in your data.

When working with models, you often need to fetch and consistently display data. Default query parameters allow you to define standard settings for data retrieval, such as pagination, sorting order, and the number of items to display per page.

A primary field is the main identifier for a record, used for lookup and reference purposes. The primary field should be unique and is set to 

 by default. A secondary field allows for a more human-readable alternative identifier, for example, a product 

Swell employs techniques to optimize database queries automatically, while App-specific indexes can be created on one or more fields and can include additional options, such as expiration time. By using indexes, you can significantly improve the performance of your application, especially when dealing with large amounts of data.

Model namespaces are a way to group and organize related models. They help prevent naming conflicts between different models in an app and provide a clear structure for organizing your data. Note that all App-defined models and fields are scoped to API keys and dynamically layered to prevent naming collisions across applications. Therefore, it’s not necessary to use namespaces for any purpose other than convenience and organization.

You can extend existing models to create new models with additional properties and behaviors through model inheritance. This enables you to create a hierarchy of models sharing common properties and behaviors, promoting organization and maintainability in your application. To extend a model, specify the parent model using the 

 property in the model definition. Additionally, indicate the version of the parent model to inherit from with the 

Swell offers two specialized types of models: singular and abstract. A singular model represents a single record in your application, such as a site configuration or a global setting. An abstract model serves as a base for other models to extend, but cannot be instantiated directly. Abstract models are useful for creating reusable data structures and enforcing consistent behavior across your schema.

Swell automatically tracks changes to models over time using semantic versioning. When a model is updated, the version number is incremented as a patch, although you can also specify a new major or minor version in your configuration. This helps maintain compatibility between different versions of your application without breaking existing functionality.

There are two types of model configurations representing both low-level database fields and high-level content management interfaces. To learn more about these concepts, read the 

With an understanding of how models work, you can construct app configurations that automatically introduce new models as well as new fields to standard models when installed.

A data model configuration has the ability to modify a merchant store’s own data schema in a secure, observable, and isolated manner.

Since Swell data models are dynamically instantiated as REST endpoints, any models you define will essentially enhance a merchant’s own API in what feels like a first-class, native interface. See 

You can create a new data model via the Backend API, or by using the following CLI command:

A model configuration can either instantiate a new collection, such as above, or append to an existing collection such as 

Here’s an example of appending fields to an existing collection:

In the above example, the resulting model will append the field definition 

Notice how there is no explicit namespace on the field object. This is intentional, as Swell handles namespace conflicts in a unique way that supports overlapping fields among apps, without causing conflicts internally or externally. It works because each API key is identified by a specific app, and data is isolated by an internal structure. App models and fields can still be accessed without an app-scoped API key, however, the model API endpoint necessarily has a namespace prefix in that case. See our 

Consider content models as a layer above data models, with the primary purpose of defining the content management experience presented in a store’s dashboard.

This two-tiered approach makes it easier to separate concerns between the database schema, API functionality, and administrative workflows. See our guide on 

You can create a new content model manually, or by using the following CLI command:

Here's an example of a new content model:

Notice the difference between content and data model configurations. Content models prefer UI-oriented field types, which for example can specify short vs long text, and field ordering to display in the admin dashboard, while data models are purely schema-oriented to structure the database and related APIs.

 collection is not standard, therefore a new data model and collection will be established by the app. If it did exist, then the platform would automatically enhance the underlying data model associated with that collection.

All model collections are private by default, but to support accessing data from the 

you can declare individual fields or entire models as public, along with specific query parameters that can limit the range of fields returned using a public key.

Here’s an example model with a public field:

With at least 1 public field declared, all records can be accessed by the frontend API, with only the public fields being returned in a response. In addition, you can limit the range of results to only include active records using public_permissions, and specify how expand parameters should be treated for the collection in a public scope.

Models

Views are an aspect of content models used to provide merchants with different ways of visualizing and editing data, as well as defining app-specific actions for standard and custom models.

Apps

What can you build with apps?

Ready to start building?