sfnext-scapi-management

SCAPI Client Management Skill

This skill covers managing which typed SCAPI clients are available in a Storefront Next project and how to discover their shapes before writing data-fetching code.

Overview

Storefront Next projects use typed SCAPI clients generated from OpenAPI schemas. Two complementary command sets work together:

Command Set	Purpose	When to Use
b2c sfnext scapi	Manage which clients exist in your project	Adding/removing APIs, checking what's configured
b2c scapi schemas	Browse API shapes (endpoints, fields, types)	Before writing a loader — discover what's available

Managing Project Clients

List Available APIs

See what SCAPI APIs can be added to your project:

# show all APIs available to add
b2c sfnext scapi available

# filter by API family
b2c sfnext scapi available --api-family product

# JSON output for scripting
b2c sfnext scapi available --json

Add a Client

Add a typed SCAPI client to your project. This generates type-safe client code accessible via createApiClients(context):

# add the shopper-products API
b2c sfnext scapi add product shopper-products v1

# add a custom API
b2c sfnext scapi add custom my-loyalty-api v1

# force re-add (overwrite existing)
b2c sfnext scapi add product shopper-products v1 --force

After adding, the client becomes available in your loaders:

import { createApiClients } from '@/lib/api-clients';

export function loader({ context }: LoaderFunctionArgs) {
    const clients = createApiClients(context);
    return {
        product: clients.shopperProducts.getProduct({
            params: { path: { id: params.productId } }
        }).then(({ data }) => data),
    };
}

List Current Project Clients

See which SCAPI clients are currently configured in your project:

# list all configured clients
b2c sfnext scapi list

# JSON output
b2c sfnext scapi list --json

Remove a Client

Remove an unused client to reduce bundle size:

# remove a client
b2c sfnext scapi remove product shopper-products

Discovering API Shapes

Before writing a loader or action, use b2c scapi schemas to explore what endpoints and fields an API offers.

The Schema-First Workflow

1. b2c scapi schemas list              → Find the API family/name/version
2. b2c scapi schemas get ... --list-paths   → See available endpoints
3. b2c scapi schemas get ... --expand-paths → See request params + response shape
4. Write your loader using the discovered types

Step 1: Find the API

# list all available schemas
b2c scapi schemas list

# filter to product APIs
b2c scapi schemas list --api-family product

Step 2: See Available Endpoints

# list all paths in shopper-products
b2c scapi schemas get product shopper-products v1 --list-paths

Output shows endpoints like /products/{productId}, /products, etc.

Step 3: Expand Endpoint Details

# see the full shape of a specific endpoint
b2c scapi schemas get product shopper-products v1 --expand-paths /products/{productId}

# see the response schema type
b2c scapi schemas get product shopper-products v1 --expand-schemas Product

# combine: endpoint + its response type
b2c scapi schemas get product shopper-products v1 \
  --expand-paths /products/{productId} \
  --expand-schemas Product,ProductResult

Step 4: Write Your Loader

Now that you know the endpoint path and parameter structure, write your loader:

export function loader({ params, context }: LoaderFunctionArgs) {
    const clients = createApiClients(context);
    return {
        product: clients.shopperProducts.getProduct({
            params: { path: { id: params.productId } }
        }).then(({ data }) => data),
    };
}

Example: Adding and Using a New API

Complete walkthrough — adding shopper-search and writing a search loader:

# 1. Check what's available
b2c sfnext scapi available --api-family search

# 2. Add the client
b2c sfnext scapi add search shopper-search v1

# 3. Discover endpoints
b2c scapi schemas get search shopper-search v1 --list-paths

# 4. Inspect the productSearch endpoint
b2c scapi schemas get search shopper-search v1 \
  --expand-paths /product-search \
  --expand-schemas ProductSearchResult

Then write the loader:

export function loader({ request, context }: LoaderFunctionArgs) {
    const url = new URL(request.url);
    const q = url.searchParams.get('q') ?? '';
    const clients = createApiClients(context);

    return {
        results: clients.shopperSearch.productSearch({
            params: { query: { q, limit: 25 } }
        }).then(({ data }) => data),
    };
}

Common Pitfalls

Pitfall	Problem	Solution
Writing a loader without checking the schema	Wrong parameter names or missing required fields	Run --expand-paths first to see exact param structure
Adding an API but client not appearing	Missing pnpm install after add	Run pnpm install to regenerate types
Trying to browse custom API schemas before registration	Schema returns empty/404	Deploy and register the custom API first (see sfnext-custom-apis)
Using wrong API version	Types don't match runtime behavior	Use scapi available to verify the current version

Related Skills

• storefront-next:sfnext-data-fetching - Using the clients in loaders, actions, and useScapiFetcher
• storefront-next:sfnext-custom-apis - End-to-end custom API implementation and consumption
• b2c-cli:b2c-scapi-schemas - Full reference for schema browsing commands and flags
• storefront-next:sfnext-project-setup - Project creation and initial structure

Reference Documentation

• CLI Commands Reference - Detailed command reference for b2c sfnext scapi