Apps SDK

The Swell Apps SDK is a Typescript-based library built to simplify the implementation of an app frontend by taking care of API access and more. In the case of storefront apps, it encapsulates many aspects of theme rendering and caching.

The primary feature of Apps SDK is to simplify authentication between your app and the store which has installed it.

Here's an example of instantiating the Swell class using headers passed to an app frontend instance, followed by a simple API call:

import { Swell } from '@swell/apps-sdk';

const swell = new Swell({
  serverHeaders: context.request.headers, // Object received from worker environment
  ...options,
});

// Make a backend API call
await swell.backend.get('/products');

// Make a frontend API call
await swell.storefront.get('/products');

The access token provided via headers gives your app scoped access based on its requested permissions when installed. If it is granted full-permissions, then you can consider the backend API to function just as any secret key would provide.

The most common approach is to initialize a Swell class instance in the beginning of the request cycle, then pass the instance through the request context for page rendering or other components that require API access.

The ability to support themes is a key feature of Apps SDK. The library understands the Shopify theme structure, while your app frontend can implement any kind of logic and structure unique to your use case. This section outlines the different theme rendering features offered by Apps SDK.

The SwellTheme class is the entry-point for all theme rendering functionality. Here's a basic example:

import {
  Swell,
  SwellTheme,
  SwellProduct,
} from '@swell/apps-sdk';

const swell = new Swell({
  serverHeaders: context.request.headers, // Object received from worker environment
  ...options,
});

const theme = new SwellTheme(swell, [options]);

// Fetch settings and set global context objects
await theme.initGlobals('index');

const data = {
  product: new SwellProduct(swell, context.params.id),
};

// Render a theme page with optional data
return await theme.renderPage([data]);

There are several built-in classes representing storefront resources such as products, categories, etc, as well as primitive classes for customizing resource logic. A resource uses deferring fetching so that when a theme template is rendered, the data is not fetched unless it is used. This is preferable in themes because a theme developer can choose from many different resources to render a page, but may not need to use all of them.

Standard resources:

Primitive resources are used to create your own resource objects, in the same way that standard resources are implemented in the SDK:

Here's an example of how to create a custom resource class for a storefront collection defined by an app, by extending a core class:

import {
  Swell,
  SwellStorefrontCollection,
  StorefrontResourceGetter,
} from '@swell/apps-sdk';

import type {
  StorefrontResourceGetter,
  SwellData,
  SwellCollection,
} from 'types/swell';

export class MyAppCollection<
  T extends SwellData = SwellCollection,
> extends SwellStorefrontCollection {
  constructor(
    swell: Swell,
    id: string,
    query: SwellData = {},
    getter?: StorefrontResourceGetter<T>,
  ) {
    // Wrap the collection name
    super(swell, 'my-app-collection', id, query, getter);

    // Return the proxy object with defers calls to async data
    return this._getProxy();
  }
}

Some resources are automatically cached by the Swell class, in context of the worker instance. For a more efficient and scalable approach, you can create a Cloudflare KV binding called THEME and pass its context to the Swell class when instantiated. For example:

import { Swell } from '@swell/apps-sdk';

const swell = new Swell({
  ...
  workerEnv: context.locals.runtime.env,
  workerCtx: context.locals.runtime.ctx,
});

In this example from an Astro frontend, env is an object containing the THEME KV binding, while ctx is a reference to the Worker context object.

More details about caching behavior and options coming soon.

We expect to continue growing Apps SDK to simplify more use cases over time. If you have any requests or ideas to improve the library, we welcome and appreciate discussions and pull-requests on Github.