The Swell Apps SDK is a TypeScript-based library designed to simplify the development of isomorphic Swell apps by providing streamlined API access, theme rendering capabilities, and comprehensive caching solutions.
- Unified API access - Seamless integration with both Swell Backend API and Storefront API
- Authentication handling - Automatic scoped access token management based on app permissions
- Theme rendering - Complete Shopify-compatible theme system with Liquid templating
- Resource management - Deferred loading of storefront resources (products, categories, etc.)
- Caching system - Multi-tier caching with Cloudflare KV integration
- Shopify compatibility - Full compatibility layer for migrating Shopify themes and apps
- Liquid templating - Enhanced Liquid engine with Swell-specific objects and filters
- Section rendering - Dynamic section management with schema support
- Settings resolution - Automatic theme and section settings processing
- Layout system - Flexible layout rendering with section groups
- Asset management - Optimized asset loading and URL generation
- Localization - Multi-language support with translation rendering
- TypeScript support - Full type safety with comprehensive type definitions
- Isomorphic design - Works seamlessly in both browser and server environments
- Error handling - Robust error management with detailed debugging information
- Performance optimized - Built-in caching and resource optimization
- Extensible architecture - Plugin system for custom resource types
npm install @swell/apps-sdkimport { Swell } from '@swell/apps-sdk';
// Initialize Swell instance in your app frontend
const swell = new Swell({
serverHeaders: context.request.headers, // Headers from worker environment
});
// Make backend API calls
const products = await swell.backend.get('/products');
// Make storefront API calls
const cart = await swell.storefront.get('/cart');When your Swell app is deployed, it runs behind Swell's proxy infrastructure. The proxy automatically injects essential headers that contain authentication tokens, store configuration, and storefront context. These headers are critical for the SDK to function properly:
// Headers passed from Swell's proxy contain:
// - swell-store-id: The store identifier
// - swell-public-key: Frontend API access key
// - swell-access-token: Backend API access token (scoped to app permissions)
// - swell-storefront-id: Current storefront instance
// - swell-environment-id: Environment (development, staging, production)
// - swell-theme-id: Active theme identifier
// - swell-storefront-context: Preloaded cart/account data
const swell = new Swell({
serverHeaders: context.request.headers, // Contains all proxy-injected headers
getCookie: (name) => getCookieValue(name),
setCookie: (name, value, options) => setCookieValue(name, value, options),
});Without these headers, the SDK cannot:
- Authenticate with Swell APIs
- Determine which store and storefront to operate on
- Access cached resources or maintain session state
- Render themes with proper configuration
The serverHeaders parameter should always be passed the complete headers object from your app's request context to ensure full functionality.
import { Swell, SwellTheme, SwellProduct } from '@swell/apps-sdk';
const swell = new Swell({
serverHeaders: context.request.headers,
...options,
});
// Initialize theme with optional configuration
const theme = new SwellTheme(swell, {
forms: formConfigs,
resources: customResources,
globals: additionalGlobals,
});
// Fetch settings and set global context
await theme.initGlobals('product'); // page ID
// Create page data with deferred resource loading
const data = {
product: new SwellProduct(swell, context.params.id),
};
// Render theme page
const renderedPage = await theme.renderPage(data);The main entry point for SDK functionality:
class Swell {
// API access
backend: SwellBackendAPI;
storefront: typeof SwellJS;
// Configuration
config: SwellAppConfig;
url: URL;
headers: Record<string, string>;
queryParams: ParsedQs;
// State
isEditor: boolean;
isPreview: boolean;
storefrontContext: SwellData;
// Methods
get<T>(url: string, query?: SwellData): Promise<T>;
post<T>(url: string, data: SwellData): Promise<T>;
put<T>(url: string, data: SwellData): Promise<T>;
delete<T>(url: string, data?: SwellData): Promise<T>;
getCachedResource<T>(key: string, args: unknown[], handler: () => T, isCacheble = true): Promise<T>;
}Handles theme rendering and management:
class SwellTheme {
// Core properties
swell: Swell;
globals: ThemeGlobals;
liquidSwell: LiquidSwell;
// Methods
initGlobals(pageId: string, altTemplate?: string): Promise<void>;
renderPage(pageData?: SwellData, altTemplate?: string): Promise<string>;
renderSection(sectionId: string, pageData?: SwellData): Promise<string>;
renderLayout(layoutName?: string, data?: SwellData): Promise<string>;
getSectionSchema(sectionName: string): Promise<ThemeSectionSchema>;
setGlobals(globals: Partial<ThemeGlobals>): void;
}Built-in storefront resource classes for deferred loading:
SwellAccount- Customer account managementSwellBlog- Blog post contentSwellBlogCategory- Blog categorizationSwellCart- Shopping cart stateSwellCategory- Product categoriesSwellOrder- Order informationSwellPage- Static pagesSwellProduct- Product detailsSwellVariant- Product variants
SwellStorefrontCollection- Collection results with paginationSwellStorefrontRecord- Individual recordsSwellStorefrontSingleton- Unique resources (cart, account)
// Create custom resource class
class MyAppCollection extends SwellStorefrontCollection {
constructor(swell: Swell, query: SwellData = {}) {
super(swell, 'my-app-collection', query);
return this._getProxy();
}
}
// Usage in theme data
const data = {
myCollection: new MyAppCollection(swell, { limit: 20 }),
};Resources are automatically cached in memory per worker instance:
// Cached resource with custom handler
const cachedData = await swell.getCachedResource(
'expensive-operation',
[param1, param2],
async () => {
return await performExpensiveOperation(param1, param2);
}
);For production scalability, enable KV caching:
const swell = new Swell({
serverHeaders: context.request.headers,
workerEnv: context.locals.runtime.env, // Contains THEME KV binding
workerCtx: context.locals.runtime.ctx, // Worker context
});Caches are automatically invalidated based on:
- Session cookies (for cart/account data)
- Theme configuration versions
- Storefront environment changes
The SDK includes comprehensive Shopify compatibility for theme migration.
- Template mapping - Direct file path compatibility
- Liquid objects - Full object structure compatibility
- Form handling - Compatible form endpoints and validation
- Section schemas - Shopify section configuration format
- Settings data -
settings_data.jsonandsettings_schema.json
Enhanced Liquid templating with Swell-specific features. See Swell Liquid documentation for details.
Resources are loaded only when accessed in templates:
<!-- Product data is fetched only when this line executes -->
{{ product.name }}
<!-- Collection is fetched only when iteration begins -->
{% for item in collection.products %}
{{ item.name }}
{% endfor %}# Install dependencies
npm install
# Build for production
npm run build
# Watch for changes
npm run watch
# Run tests
npm testsrc/
├── api.ts # Core Swell class and API handling
├── theme.ts # SwellTheme class and rendering
├── resources.ts # Storefront resource classes
├── liquid/ # Liquid templating engine
├── compatibility/ # Shopify compatibility layer
├── cache/ # Caching implementations
├── utils/ # Utility functions
└── index.ts # Main exports
- Swell Documentation
- Apps Development Guide
- Proxima Example App
- Swell Liquid Reference
- GitHub Repository
See the LICENSE file for details.