Build smarter workflows with App Functions

A recent introduction to Swell is our Apps framework, which brings many new opportunities to customize the platform for unique use cases. Among the capabilities that an app can provide is hosted functions.

How functions unlock new opportunities

Functions are written in JavaScript or TypeScript and deployed to Swell’s cloud environment, powered by Cloudflare Workers. They can be triggered by data events (similar to webhooks), by a schedule, or invoked directly by HTTP. When called, a function is wrapped in the context of a Swell store and its API in order to provide a seamless development experience without unnecessary boilerplate.

Here’s an example of a function that sends a text message confirmation when an order is shipped.

// functions/shipment-text-notification.ts
export const config: SwellConfig = {
  description: 'Send SMS confirmation on order shipment',
  model: {
    events: ['shipment.created'],
    conditions: {
      tracking_url: { $exists: true }
    }
  }
};

export default async function (req: SwellRequest) {
  const { swell, data, store } = req;
  
  const order = data; // The updated order record

  const settings = await swell.settings(); // App settings
  
  const { twilio_account_id, twilio_auth_token, twilio_from_number } = settings;

  // Use an external SMS service like Twilio via fetch
  await fetch(`https://api.twilio.com/2010-04-01/Accounts/${twilio_account_id}/Messages.json`, {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + btoa(`${twilio_account_id}:${twilio_auth_token}`),
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      To: order.billing.phone,
      From: twilio_from_number,
      Body: `Your order ${order.number} has shipped! Track it at ${order.tracking_url}`
    })
  });
}

In this example, we see how a function can be used asynchronously, but there are many use cases that require a function to intercept an event and affect the outcome synchronously.

Here’s an example of a function that is invoked in the middle of a request, and modifies the data of an order before it is submitted.

// functions/high-value-order.ts
export const config: SwellConfig = {
  description: 'Apply custom discount to high-value orders',
  model: {
    events: ['before:order.submitted']
  }
};

export default function (req: SwellRequest) {
  const { data } = req;
  
  const order = data; // Incoming order data

  // Add custom validation or modification
  if (order.sub_total > 1000) {
    order.discounts = orders.discounts || [];
    order.discounts.push({
      id: 'high-value-discount',
      amount: 50
    });
  }

  // Return modified data to continue the creation process
  return order;
}

Test and deploy

Development and deployment are made easy with the Swell CLI. A single command will compile and run local versions of your functions using Cloudflare Wrangler behind the scenes.

$ swell app dev

✔ App function server running on port 3001

Functions:
  shipment-text-notification
    Trigger: Model
    Events: shipment.created
    Description: Send SMS confirmation on order shipment
  high-value-order
    Trigger: Model
    Events: before:order.submitted
    Description: Apply custom discount to high-value orders

→ Call functions at: http://localhost:3001/<function-name>

The swell app dev command will cause Swell to proxy all backend events to your local machine so that you can test and visualize behavior before pushing to the cloud. You can also invoke the functions directly using an API tool such as Postman with a call to the URL listed by the command.

As you make changes, functions are automatically recompiled and reloaded on the fly, as well as deployment to Swell as a part of your development app version.

You'll see the output of any console logs emitted when running swell app dev, and while functions are executed in the cloud, you can see their input and output in the Swell dashboard under Developer -> Console -> Logs.

Context is key

Functions are isolated by the Cloudflare Worker platform, and their logic contains only what is necessary to get the job done. To simplify and reduce boilerplate as much as possible, Swell compiles and wraps function code in a context that provides easy access to the store’s API and app settings, along with detailed information about the event or trigger. This context is what makes the development experience feel magical.

Diving deeper, the context object—passed as req to your function—includes everything you need at your fingertips. There's swell, our SDK for API interactions like querying products or updating records. The data object holds the event-specific payload, such as the record being created or updated, and the store object gives access to store-wide details and settings. No more wrestling with authentication or setup—it's all prepped and ready, letting you focus on the logic that drives value.

Function logs

Event, schedule, and request triggers

Functions can be triggered by three main action types.

Event Functions react to platform changes, like record creations or updates in models such as products or orders. Events can be either asynchronous, like webhooks, or synchronous using before or after hooks. Use conditions to filter invocations and sequence numbers to prioritize execution in chains—ensuring your function runs exactly when and where it should.

Scheduled Functions automate tasks over time. Tie them to a model's date field for dynamic timing, like capturing payments on a set schedule, or use cron expressions for recurring jobs, such as daily inventory syncs. This opens doors to proactive ecommerce automation without constant oversight.

Request Functions turn your app into a custom API engine. Exposed as HTTP endpoints, they handle regular HTTP methods, with options for caching, public access, or secure key-based auth. Ideal for building custom logic into headless storefronts or integrating third-party services on-demand.

Each trigger type leverages the same edge-powered runtime for zero cold starts and optimal performance, making Swell Apps a scalable extension of your store.

Getting started

Start by installing the Swell CLI and running swell create function to scaffold your first one. Develop locally with swell app dev for real-time testing via a secure tunnel. Deploy effortlessly—changes push automatically to our Cloudflare-backed edge.

A few best practices: Keep code lean, using ES modules and avoiding unsupported Node APIs. Leverage conditions to minimize invocations. For request functions, enable caching on GETs to boost performance. Remember, while powerful, functions have limits on memory and execution time, so design for efficiency.

For full details, dive into our App Functions Developer Docs. We're excited to see what you build—share your creations, provide feedback, or partner with us to shape the future.