Skip to main content

Add the SDK to your app

This walkthrough adds the Storefront SDK to an app you already have, and ends with a product grid filled from your Propeller catalog. It covers the four parts every app needs: the packages, a GraphQL route on your server, the providers and a first component. Pick your framework in the tabs: React shows a Next.js app with the App Router, Vue a Vite app.

To start from a complete storefront instead, use the Accelerator quickstart.

Prerequisites​

  • Node.js 22 and an existing Next.js or Vite app with React 18 or newer, or Vue 3.4 or newer
  • Your GraphQL API URL and an API key limited to storefront use (see Keys and security)
  • The id of a category in your catalog, for the product grid

Step 1: Install the packages​

npm install @propeller-commerce/propeller-sdk-v2 @propeller-commerce/propeller-v2-react-ui

Step 2: Add the GraphQL route​

The SDK in the browser posts every request to a route on your own server, which adds the API key and forwards the request to Propeller. The key never reaches the browser. Put the endpoint and the key in server-only settings:

# .env.local (Next.js) or .env (Vite)
PROPELLER_GRAPHQL_ENDPOINT=https://api.helice.cloud/v2/graphql
PROPELLER_API_KEY=your-storefront-api-key

Create app/api/graphql/route.ts:

// Forwards the browser's GraphQL requests to Propeller with the storefront key.
export async function POST(request: Request) {
  const headers: Record<string, string> = {
    'Content-Type': 'application/json',
    apiKey: process.env.PROPELLER_API_KEY!,
  };
  // Forward the signed-in user's token, if there is one.
  const authorization = request.headers.get('authorization');
  if (authorization) headers.Authorization = authorization;

  const upstream = await fetch(process.env.PROPELLER_GRAPHQL_ENDPOINT!, {
    method: 'POST',
    headers,
    body: await request.text(),
  });

  return new Response(await upstream.text(), {
    status: upstream.status,
    headers: { 'Content-Type': 'application/json' },
  });
}

Keep this route to the storefront key. Order actions that need the order-editor key, such as the status update after a payment, belong in your own server code. See Keys and security.

Step 3: Mount the providers​

Create the SDK client and the services once, and pass them to the UI library at your app root, together with the session (the user, the language and the price display).

Create app/propeller-providers.tsx:

'use client';

import type { ReactNode } from 'react';
import { createClient } from '@propeller-commerce/propeller-sdk-v2';
import {
  PropellerDepsProvider,
  PropellerProvider,
  createServices,
} from '@propeller-commerce/propeller-v2-react-ui';

const graphqlClient = createClient({ endpoint: '/api/graphql' });
const services = createServices(graphqlClient);

export function PropellerProviders({ children }: { children: ReactNode }) {
  return (
    <PropellerDepsProvider value={{ graphqlClient, services, currency: '€', configuration: {} }}>
      <PropellerProvider
        value={{ user: null, companyId: undefined, language: 'NL', includeTax: false, portalMode: 'open' }}
      >
        {children}
      </PropellerProvider>
    </PropellerDepsProvider>
  );
}

Then wrap your root layout in it and load the stylesheet, in app/layout.tsx:

import type { ReactNode } from 'react';
import '@propeller-commerce/propeller-v2-react-ui/styles.css';
import { PropellerProviders } from './propeller-providers';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <PropellerProviders>{children}</PropellerProviders>
      </body>
    </html>
  );
}

A signed-in user, a Company switch or another language changes the session value, not the client. UI components explains every field.

Step 4: Render a product grid​

Replace 1324 with the id of a category in your catalog.

Create app/shop/page.tsx:

import { ProductGrid } from '@propeller-commerce/propeller-v2-react-ui';

export default function ShopPage() {
  return <ProductGrid categoryId={1324} />;
}

Run npm run dev and open http://localhost:3000/shop.

You should see the products of that category with their names and prices, for example "Tervo accuboorschroefmachine 18 V zonder accu, € 135,04 excl. VAT". In the browser's network tab, every request goes to /api/graphql and none carries an API key.

Next steps​

Last updated on