lodash-es is imported as individual sub-paths (lodash-es/set, lodash-es/get, etc.). Bundlers (Vite, Webpack 5, Rollup) handle this natively. For Jest / ts-node add a module name mapper or use the lodash CJS build plus path aliases.

No native build steps, no pod install, no Android linking required.

Project setup

1. Copy the source/ directory into your project, e.g. src/swell/.
2. In tsconfig.json add a path alias so deep imports resolve cleanly:

   {
     "compilerOptions": {
       "paths": {
         "swell-sdk": ["./src/swell/index.js"],
         "swell-sdk/*": ["./src/swell/*"]
       }
     }
   }
   

3. If you are using Babel, add babel-plugin-module-resolver with the same alias.
4. Set environment variables (for the API client initialisation call):

   SWELL_STORE_ID=your-store-id
   SWELL_PUBLIC_KEY=your-public-key
   

5. Because the source uses ES module syntax throughout, ensure your bundler or tsconfig targets ESM, or configure your bundler to transpile source/ from ESM to CJS.
6. Import and initialise:

   import swell from './src/swell/index.js';
   swell.init(process.env.SWELL_STORE_ID, process.env.SWELL_PUBLIC_KEY);
   export default swell;
   

Public API

default (API client)

import swell from './src/swell/index.js';

swell.init(storeId: string, publicKey: string, options?: object): void;

The root export from index.js re-exported from api.js. Call init once at application startup with your store ID and public key. All sub-controllers (swell.cart, swell.products, swell.account, swell.payment, etc.) are available as properties after initialisation.

AppController

import AppController from './src/swell/app/index.js';

class AppController {
  constructor(api: object, options: object);
  load(appId: string): Promise<App>;
}

Loads a Swell app/extension by ID, fetching its component definitions from /apps/:id and caching the result. Use this when building a storefront that renders merchant-installed app components (e.g. custom checkout widgets). Throws if the app has no extensions configured in swell.json.

PaymentController

import PaymentController from './src/swell/payment/index.js';

class PaymentController {
  constructor(api: object, options: object);
  get(id: string): Promise<object>;
  methods(): Promise<object>;
  createElements(params: object): Promise<void>;
}

Orchestrates all payment gateway integrations. Call methods() to retrieve enabled payment methods for the store, then createElements(params) to mount the appropriate gateway UI (Stripe Elements, PayPal button, Apple Pay sheet, etc.). get(id) retrieves a specific payment record.

AppPaymentComponent

import { AppPaymentComponent } from './src/swell/app/component/index.js';

Exported from app/component/index.js. Represents the payment component surface for a loaded app extension. Use it when an installed app provides a custom payment UI that must be embedded in your checkout page.

Working examples

Scenario - Fetch products and render a listing

Retrieve a paginated list of products with a category filter and display their names and prices.

import swell from './src/swell/index.js';

swell.init('my-store', 'pk_live_xxxx');

async function getProducts() {
  const result = await swell.products.list({
    category: 'shirts',
    limit: 20,
    page: 1,
  });

  for (const product of result.results) {
    console.log(product.name, product.price);
  }
}

getProducts();

Scenario - Add an item to the cart and apply a coupon

Create or update the session cart, add a product variant, then apply a promotional coupon code.

import swell from './src/swell/index.js';

swell.init('my-store', 'pk_live_xxxx');

async function buildCart(productId: string, variantId: string) {
  await swell.cart.addItem({
    product_id: productId,
    variant_id: variantId,
    quantity: 1,
  });

  const cart = await swell.cart.applyCoupon('SUMMER20');
  console.log('Discount applied:', cart.discount_total);
  return cart;
}

Scenario - Load a Stripe card payment element at checkout

Use PaymentController (via the top-level swell.payment proxy) to mount Stripe card elements and tokenize the card on submit.

import swell from './src/swell/index.js';

swell.init('my-store', 'pk_live_xxxx');

async function mountCardPayment() {
  const methods = await swell.payment.methods();
  console.log('Available methods:', Object.keys(methods));

  await swell.payment.createElements({
    card: {
      elementId: '#card-element',
      onChange(event) {
        if (event.error) console.error(event.error.message);
      },
    },
  });
}

async function submitOrder() {
  const result = await swell.payment.tokenize({ card: {} });
  console.log('Order result:', result);
}

Scenario - Load an app extension

Dynamically load a merchant-installed app and access its registered components.

import AppController from './src/swell/app/index.js';
import api from './src/swell/api.js';

const controller = new AppController(api, {});

async function loadReviewsApp() {
  const app = await controller.load('product-reviews');
  console.log('Loaded app:', app);
}

loadReviewsApp();

File walkthrough

• index.js - Single re-export of the default API client; this is the package entry point.
• api.js - Instantiates and wires all sub-controllers; handles request(), init(), and session bootstrapping.
• account.js - All customer account operations: login, logout, address book, stored cards, order history.
• attributes.js - Fetches store-defined product and category attribute schemas.
• cache.js - Lightweight key/value cache to avoid redundant API round-trips.
• card.js - Card number/expiry/CVC validation and client-side tokenisation utilities.
• cart.js - Full cart lifecycle: create, retrieve, add items, update items, remove items, coupons, shipping.
• categories.js - List all categories or fetch a single category by slug/ID.
• content.js - Access CMS content models stored in Swell Content.
• cookie.js - Portable cookie helpers (works in browser and Node.js SSR).
• currency.js - Format and convert monetary values according to store currency settings.
• functions.js - Internal utility functions shared across modules.
• invoices.js - Retrieve customer invoices for account dashboards.
• locale.js - Detect active locale and switch locale context for multi-language stores.
• products.js - Product listing with filters/sort/pagination, single product, search, and variant resolution.
• session.js - Session token acquisition, renewal, and attachment to API requests.
• settings.js - Store-level settings, navigation menus, and payment method configuration.
• subscriptions.js - Create, read, update, and cancel customer subscriptions.
• app/ - AppController fetches and caches app definitions; App and component classes live here.
• payment/ - Gateway-specific implementations (Stripe, Braintree, PayPal, Apple Pay, Google Pay, Klarna, Amazon, Sezzle, Paysafecard, QuickPay, ConvesioPay) unified under PaymentController.
• utils/ - Shared helpers: custom error classes (PaymentMethodDisabledError, UnsupportedPaymentMethodError), dynamic script loader, case converters, Stripe and Klarna utility wrappers.

Common pitfalls and fixes

• ESM-only source in a CJS project: the source uses export/import throughout; configure Webpack/Vite to transpile src/swell/ or set "type": "module" in your package.json.
• lodash-es not resolving in Jest: Jest does not process node_modules by default; add transformIgnorePatterns: [] or map lodash-es to lodash via moduleNameMapper.
• Buffer not defined in browser: utils/index.js references /* global Buffer */; if targeting browsers without a polyfill, add buffer to your bundler's resolve.fallback.
• swell.init() not called before first request: all controllers assume init has been called; call it in your app entry before any async operations, or requests will fail with an auth error.
• Payment elements mounted before DOM ready: createElements injects scripts and queries DOM nodes; always call it inside a DOMContentLoaded handler or after your framework's mount lifecycle hook.
• Case conversion mismatch: the SDK uses toCamel/toSnake internally; if you pass manually constructed objects, use the exported helpers from utils/index.js to ensure field names match the API's expectations.

Vibe-coding prompt template

I have vendored the swell-js SDK source into my project at `src/swell/`.
The integration guide is in `USAGE.md` next to this source directory.
The upstream package is `user@example.com`.

Please help me integrate this SDK into my existing [framework] project step by step:

1. Read `USAGE.md` for correct import paths and initialisation.
2. Wire up the API client using my environment variables SWELL_STORE_ID and SWELL_PUBLIC_KEY.
3. Create a products listing page that calls `swell.products.list()`.
4. Create a cart context/provider that uses `swell.cart` methods.
5. Add a checkout page that calls `swell.payment.methods()` and `swell.payment.createElements()`.
6. Make sure all imports reference `src/swell/index.js` (or sub-paths as shown in USAGE.md).
7. Do not install the `swell-js` npm package; use the vendored source only.
8. Point out any tsconfig or bundler changes needed for ESM compatibility.

License and credit

The upstream source is published by Swell under the MIT license. See source/LICENSE if present, or check the swell-js npm page and the official repository for the full license text. Upstream package: user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Vendure Headless GraphQL Commerce Platform

eCommerce, Marketplace & POS Systems

Free