Server API Routes

Server API Routes, also known as Resource Routes, are the standard way to fetch and mutate data in Storefront Next. They implement the Backend-For-Frontend (BFF) pattern—your client-side components communicate with these server endpoints, which securely handle B2C Commerce API calls, authentication, and sensitive business logic.

All data fetching routes through server endpoints. Server routes handle:

• API authentication: SLAS flows, client secrets, and token management.
• B2C Commerce API proxying: All SCAPI calls route through server endpoints.
• Callbacks and redirects: Auth redirects, webhooks, JWKS proxying.
• Cookie and header management: Session handling, locale preferences.
• JSON responses: Data for useFetcher() or client-side fetch() calls.

This approach keeps credentials secure, reduces client bundle size, and centralizes data access patterns.

Server routes implement the Backend-for-Frontend (BFF) pattern. Your storefront app acts as an intermediary between the client and backend services.

This architecture provides:

• API aggregation: Combine multiple Commerce API calls into single endpoints.
• Security: Keep API credentials and sensitive logic on the server.
• Performance: Reduce client-side JavaScript and network requests.
• Flexibility: Transform API responses to match your UI needs.

Storefront Next uses React Router 7 in framework mode. Routes are defined by files in src/routes/ by using the flat routes convention.

A route module becomes a resource route (API endpoint) when it exports only data functions such as loader and action, without a default React component.

Storefront Next uses these naming conventions.

• resource.* files map to /resource/... endpoints.
• action.* files map to /action/... endpoints.
• loader.* files map to /loader/... endpoints.
• _empty.* files bypass parent layouts. Use this prefix when a route needs to render without the standard page wrapper, for example, the logout action that redirects immediately.

All data fetching in Storefront Next happens on the server. Resource routes use loader and action functions that run server-side for both initial page loads and client-side navigation.

This server-side approach provides:

• Security: Sensitive API keys and business logic stay on the server.
• Performance: Reduced client bundle size.
• Consistency: Single source of truth for data-fetching logic.
• SEO: All data is available during server-side rendering.

Server routes support three main patterns: loaders for GET requests, actions for mutations, and dynamic parameters for flexible endpoints.

Use a loader to respond to GET requests. This example shows a store search endpoint.

Use an action to handle mutations and form submissions. This example shows a locale-setting endpoint.

Use dynamic segments when a family of endpoints shares a common shape.

This dynamic segment maps to /resource/auth/:operation. For example, /resource/auth/login-guest.

For standard B2C Commerce operations, use the useScapiFetcher hook. This hook pairs with a generic server route so that you can call any SCAPI method from your components while keeping the actual API communication on the server.

You don’t interact with the underlying server route directly—the hook handles everything for you.

For mutations, use the submit method.

Server routes use standard Web APIs, such as Request, Response, and FormData, for handling requests and responses. For detailed patterns, see the React Router Actions.

Handle errors gracefully and return appropriate status codes. Don’t expose sensitive information in error messages.

Status Code Guidelines

Use React Router’s useFetcher() hook to call server routes without triggering a full page navigation. For complete documentation, see React Router’s Data Loading.

Server routes handle sensitive operations. Follow these practices.

Always validate and sanitize input from requests.

Never embed client secrets in browser code. Server routes exist specifically to keep credentials secure.

Use the generic Commerce SDK proxy (resource.api.client.$resource.ts) carefully. If you implement similar patterns, enforce an allowlist of methods and validate parameters. Don’t expose a “call-anything” proxy without guardrails.

Public endpoints must set appropriate Cache-Control headers.

• Salesforce B2C Commerce API (SCAPI) Client