Skip to main content

Understanding the Storefront SDK

Public and evolving

The Storefront SDK packages are published on npm under the @propeller-commerce scope and are MIT licensed. No credentials are needed to install them. They are still on 0.x versions, so APIs can change between minor releases. Each guide notes the versions it was written against. The package pages on npm and the TypeScript types shipped with every package are always the current source of truth.

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 working storefront you scaffold in one command.

Prerequisites​

Installing the packages needs only Node.js 20 or newer. To actually run a storefront with data, you also need three things from your Propeller environment:

  • A Propeller tenant and Backoffice access. Contact your Propeller account manager if you do not have one yet.
  • A GraphQL API key for that tenant, created in Backoffice Admin (see Environments and access).
  • A base category id, the category you want as the storefront's root for navigation, taken from your catalog.

The boilerplate's environment example documents every variable, but these three are the values you supply yourself before the shop shows any products.

The layers​

Each layer builds on the one below it. Higher layers are optional.

Storefront SDK layers: the Accelerator, CMS renderers and UI libraries are optional and build on the core layer and the SDK, which connects to the Propeller GraphQL API.

  • 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 normalizers 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 are an optional layer that turns a CMS page payload into rendered blocks. They ship no opinionated blocks of their own. The provider that fetches the content is separate from the renderers: in the Accelerator it ships inside the Next.js boilerplate (lib/cms, activated by CMS_PROVIDER), or you implement the contract yourself.
  • Accelerator is the top layer: complete Next.js, Vue and Nuxt storefronts, pre-wired with the layers below, that you scaffold with the create-propeller-shop CLI.

Each layer is independently usable. 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​

LayerPackageWhat it isDistribution
SDK@propeller-commerce/propeller-sdk-v2TypeScript GraphQL client and a typed service per operationnpm
Core@propeller-commerce/propeller-v2-core-uiShared types, formatters, normalizers and createServices()npm
UI@propeller-commerce/propeller-v2-react-uiReact components and hooksnpm
UI@propeller-commerce/propeller-v2-vue-uiVue 3 components and composablesnpm
CMS@propeller-commerce/propeller-v2-cms-reactCMS page and block renderers for Reactnpm
CMS@propeller-commerce/propeller-v2-cms-vueCMS page and block renderers for Vuenpm
Accelerator@propeller-commerce/create-propeller-shopScaffolder CLI that generates a storefront from a boilerplatenpm (run with npx)
AcceleratorNext.js · Vue · Nuxt boilerplatesComplete storefront appspublic GitHub

Always install the scoped package names shown above. The unscoped names that appear in some package READMEs are internal aliases and do not resolve on npm.

How the pieces connect​

The UI libraries do not ship a GraphQL client or a hardcoded endpoint. Transport is application-specific (a Next.js app proxies through a route handler, a Vite app calls a proxy, and so on). You own the client. The contract is three steps, sometimes called the SDK seam:

  1. Construct 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's PropellerProvider once, at your app root. Every component and hook below it reads the services from context.
import { createClient } from '@propeller-commerce/propeller-sdk-v2';
import { createServices } from '@propeller-commerce/propeller-v2-core-ui';

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

The SDK and UI libraries guides cover each step in full.

Where to find what​

You wantLook here
The big picture and which packages existThis section
Which approach fits your projectChoosing your approach
How the GraphQL data layer worksSDK services
How to use the components and hooksUI libraries
A full, runnable storefrontAccelerator
The list of available componentsComponent reference
The full prop list for one componentThe component's TypeScript types, or the package's documentation site
How a commerce domain works at the GraphQL levelThe domain guides

The domain guides teach the products, pricing, cart and account models using raw GraphQL. Those concepts apply whether you use the SDK or build from scratch. The SDK wraps the same queries into typed services and components.

For the exact API of the version you installed, read the package's documentation site, the package on npm, or the types in your editor.

Package documentation​

Each package has its own documentation site, the canonical reference for its API:

See also​