Swell Apps: SDK Reference | Swell Developer Center

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. API access 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: 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. Theme rendering 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. SwellTheme The SwellTheme class is the entry-point for all theme rendering functionality. Here's a basic example: Storefront resources 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: SwellAccount SwellBlog SwellBlogCategory SwellCart SwellCategory SwellOrder SwellPage SwellProduct SwellVariant Primitive resources are used to create your own resource objects, in the same way that standard resources are implemented in the SDK: SwellStorefrontCollection: A collection result. Arguments: swell: Swell, collection: string, query: object = {}, getter?: StorefrontCollectionGetter<T> SwellStorefrontRecord: A single record result from a collection. Arguments: swell: Swell, collection: string, id: string, query: object = {}, getter?: StorefrontCollectionGetter<T> SwellStorefrontSingleton: A unique record-type, for example SwellAccount and SwellCart. Arguments: swell: Swell, collection: string, getter?: StorefrontCollectionGetter<T> 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: Caching 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: 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. Future enhancements 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.