Routing Commerce API Requests Through Vue Storefront 2 Middleware

When a Vue Storefront 2 (Nuxt 2) storefront calls a commerce GraphQL or REST endpoint directly from the browser, Server-Side Rendering (SSR) often fails to forward session cookies, and the client inherits CORS requirements, backend URLs, and token management. The practical takeaway is to route cart, checkout, customer, and product requests through the VSF server middleware using the configured api-client proxy, so the browser only calls relative /api paths.

Decision and Constraints

Decision: proxy checkout, product, cart, and customer traffic through the VSF Node server middleware using the official commerce api-client integration. Browser code calls relative endpoints such as /api/cart, and the middleware forwards them to the commerce backend.

Constraints: this guidance targets Vue Storefront 2 with Nuxt 2 and an official api-client module. Later Vue Storefront releases use different module names and composable signatures, so do not copy this configuration into a newer version without checking the release notes.

Supported Options

Strategy	Request path	SSR cookie forwarding	Client exposure	Operational cost
Direct browser-to-commerce	External commerce URL	Poor; cookies rarely survive hydration	Backend URL, CORS setup, tokens visible to client	Low
VSF api-client server middleware proxy	Relative /api path	Good; Node server forwards headers and cookies	Only the storefront origin	Medium
Separate backend-for-frontend (BFF)	BFF service, then commerce	Good; full control over forwarding	Only the BFF origin	High

Trade-offs

The VSF proxy centralizes commerce headers, cookies, rate limiting, and endpoint configuration in one Node process. That improves SSR compatibility and keeps sensitive URLs out of the browser. The cost is an additional server hop for every proxied request, which can increase cold-start latency and ties frontend availability to middleware uptime.

Direct browser calls remove the Node hop and reduce server load, but they leak commerce endpoint details and require client-side token storage, which complicates SSR hydration. A separate BFF offers the most control and reuse across mobile or other clients, but it duplicates VSF integration logic and carries the highest build and maintenance cost.

Implementation

Register the commerce api-client module in nuxt.config.js and set the API URL and cookie names through environment variables. Exact module and configuration keys vary by commerce platform and VSF 2 patch release, so treat the block below as a representative structure and verify it against your installed package.

// nuxt.config.js
module.exports = {
  modules: [
    '@vue-storefront/module',
    // Replace with the official api-client package for your commerce platform
    '@vue-storefront/commerce-api-client'
  ],
  storefront: {
    api: {
      url: process.env.COMMERCE_API_URL,
      cookieNames: {
        token: 'auth_token'
      }
    }
  }
};

After configuration, page components use VSF composables. The composable resolves the call to a relative route handled by the Node middleware rather than the external commerce host.

// pages/cart/index.vue
import { useCart } from '@vue-storefront/core';

export default {
  setup() {
    const { cart, load } = useCart();

    // This resolves to /api/cart through the VSF middleware proxy.
    load();

    return { cart };
  }
};

Do not store commerce bearer tokens in localStorage when using SSR. Prefer HttpOnly cookies managed by the middleware where the commerce platform supports them.

Validation

Run the following commands from the VSF project root. No special filesystem permissions are required beyond normal npm access.

1. Build and start the production server:

   npm run build
   npm run start

2. Open the browser developer tools Network tab, filter by Fetch/XHR, and load a product or cart page.

3. Trigger a commerce action, such as adding an item to the cart.

4. Confirm the request URL is relative, for example http://yourstorefront.com/api/cart, and not the external commerce host such as https://commerce.example.com/graphql.

5. Inspect VSF server logs or middleware tracing to verify the same request reaches the commerce backend with forwarded headers and cookies.

6. Compare npm run start against npm run dev to confirm cart and user data hydrate without client-only fetch errors.

Limitations and Practical Checks

Proxying all traffic through Node can become a bottleneck for high-traffic catalog pages. Consider output caching or static generation for product listing data that does not require a user session. Changing the commerce API URL or cookie domain after launch can break SSR hydration and persisted carts, so pin those values in environment configuration and test after any change.

This is not security advice. Validate cookie SameSite, CSRF, and PCI scope for checkout against your commerce platform before handling payment data.

A practical verification is to open the Network tab after a full production build and confirm every commerce call begins with /api on the storefront origin. If any call targets the external commerce host directly, the proxy configuration or composable import needs correction.