Skip to main content

Understanding the Storefront SDK

The Storefront SDK is the set of packages and starter apps you use to build a customer-facing storefront on Propeller. Every layer talks to the Propeller GraphQL API. You adopt as much or as little as you need: a single typed client, a full component library or a complete storefront you scaffold in one command.

Checked against propeller-sdk-v2 0.18.0, propeller-v2-react-ui 0.32.0, propeller-v2-vue-ui 0.31.1 and create-propeller-shop 0.11.2 on 28 October 2026.

Prerequisites​

Use Node.js 22 for the packages and the boilerplates. To run a storefront with data, you also need from your Propeller environment:

  • A Propeller tenant and Backoffice access. Contact your Propeller account manager if you do not have one yet.
  • Two API keys for that tenant, created in the Backoffice: one for the storefront and an order-editor key for order actions. See Keys and security for what each may do, and Environments and access for creating them.
  • The id of the Channel the storefront sells on. The storefront reads its catalog root and its guest account from the Channel.

The layers​

Each layer builds on the one below it. Higher layers are optional, and the bars on the right show which layers each approach uses.

Storefront SDK layers: the Accelerator, CMS renderers and UI libraries are optional and build on the core layer and the SDK, which reach the Propeller GraphQL API. The Accelerator uses every layer, your own app uses a UI library and the SDK, and a headless build uses the SDK only.

  • SDK is the data layer. It gives you a typed GraphQL client and a service for every supported query and mutation. It works in any JavaScript or TypeScript project.
  • Core holds the shared types, the formatters and helpers the UI builds on and createServices(), which bundles the SDK services for a client.
  • UI libraries add ready-made commerce components (product cards, grids, cart, checkout, account) plus headless hooks, for React or Vue.
  • CMS renderers turn a CMS page into rendered blocks. They ship no blocks of their own, and they do not fetch content: a separate provider does that. See CMS integration.
  • Accelerator is the top layer: complete Next.js, Vue and Nuxt storefronts with the layers below wired in, which you scaffold with the create-propeller-shop CLI.

Each layer works on its own. You do not need the Accelerator to use the UI libraries, and you do not need the UI libraries to use the SDK.

The packages​

The packages are MIT licensed and public on npm under the @propeller-commerce scope, so no credentials are needed to install them. Always install the scoped names below.

PackageWhat it isCode and release notesAPI docs
@propeller-commerce/propeller-sdk-v2Typed GraphQL client and a service per operationGitHub, changelogSDK docs
@propeller-commerce/propeller-v2-core-uiShared types, formatters, helpers and createServices()GitHub, changelogCore docs
@propeller-commerce/propeller-v2-react-uiReact components and hooksGitHub, changelogReact docs
@propeller-commerce/propeller-v2-vue-uiVue 3 components and composablesGitHub, changelogVue docs
@propeller-commerce/propeller-v2-cms-reactCMS page and block renderer for ReactGitHub, changelogCMS React docs
@propeller-commerce/propeller-v2-cms-vueCMS page and block renderer for VueGitHub, changelogCMS Vue docs
@propeller-commerce/propeller-v2-mollieMollie payments, server-sideGitHub, changelogThe README
@propeller-commerce/propeller-v2-mspMultiSafepay payments, server-sideGitHub, changelogThe README
@propeller-commerce/propeller-v2-punchoutOCI and cXML PunchOut, server-sideGitHub, changelogThe README
@propeller-commerce/propeller-v2-splSpareParts Live drawings for ReactGitHub, changelogThe README
@propeller-commerce/create-propeller-shopThe CLI that scaffolds a storefront (run with npx)GitHub, changelogAccelerator docs

The boilerplates are public GitHub repositories, each with its own changelog and settings example: Next.js, Vue and Nuxt.

The payment, PunchOut and SpareParts Live packages are server-side add-ons rather than layers of the frontend stack. The boilerplates already use them. See Payment providers and PunchOut.

How the pieces connect​

The UI libraries do not ship a GraphQL client or a fixed endpoint, because transport differs per app (a Next.js app proxies through a route handler, a Vite app through its server, and so on). You own the client. The contract has three steps:

  1. Create a client with createClient() from the SDK, pointing at your endpoint.
  2. Call createServices(client) from the core layer to build the typed Services bundle.
  3. Pass both into the UI library once, at your app root: PropellerDepsProvider in React, the propellerVue plugin in Vue. The session (user, Company, language) goes into PropellerProvider. Every component below reads the services and the session from context.
import { createClient } from '@propeller-commerce/propeller-sdk-v2';
import { createServices } from '@propeller-commerce/propeller-v2-core-ui';

// Steps 1 and 2: build once, share everywhere.
export const graphqlClient = createClient({ endpoint: '/api/graphql' });
export const services = createServices(graphqlClient);

Add the SDK to your app walks through all three steps in a running app. SDK services and UI components cover each layer in full.

The domain guides teach the products, pricing, cart and account models with raw GraphQL. Those concepts apply whether you use the SDK or not: the SDK wraps the same queries in typed services and components.

Versions and release notes​

Release notes for the SDK packages and the boilerplates are in each repository's changelog on GitHub, linked in the table above. The changelog on this site covers the Propeller platform and its APIs, not the SDK packages.

The guides in this section explain how to choose, set up and run the SDK on Propeller. For the exact API of the version you installed (every prop, hook option and method signature) use the API docs above or the TypeScript types in your editor.

See also​

Last updated on