Vue Storefront 2: Official Commerce Adapter vs. Custom GraphQL Integration

The problem and the useful takeaway

You are setting up a Vue Storefront 2 storefront and must connect it to a commerce backend. The choice is not just Shopify versus Magento: it is whether to use an official middleware adapter or build a custom GraphQL adapter. Picking a custom adapter when an official one fits your backend version creates unnecessary maintenance. Picking an official adapter when your backend is unsupported or uses proprietary pricing logic can force you to rewrite frontend queries and checkout flows later.

Takeaway: use an official adapter when your backend and version appear on the supported adapter matrix. Build a custom adapter only for unsupported platforms or backend behavior that the unified schema cannot express. Validate either choice with GraphQL introspection, a production SSR build, and a test checkout before you commit to frontend development.

Decision and constraints

Decision: which catalog and checkout integration pattern to adopt in the Vue Storefront middleware layer.

• Backend platform and version: official adapters exist for Shopify, Magento 2, BigCommerce, and commercetools, but feature parity varies by platform version.
• Unified schema: the frontend expects a common GraphQL shape for products, cart, and checkout. The adapter must satisfy that shape.
• Credential safety: commerce backend credentials belong in middleware server environment variables, never in Nuxt runtime config exposed to the browser.
• Server-side rendering: Vue Storefront 2 uses Nuxt 3 with SSR enabled by default, so catalog queries run on the server for the initial page load.
• Team capacity: a custom adapter means you own resolver implementation, schema coverage, and upgrade testing.

Supported options compared

Option	Best for	Adapter responsibilities	Main risk
Official adapter	Backend on a supported version	Backend authentication, cart synchronization, checkout redirect, webhook handling	Feature parity varies by backend version; adapter releases can introduce breaking schema changes
Official adapter with custom resolvers	Mostly official behavior plus backend-specific logic	Official base behavior, extended with custom resolvers for backend-specific fields	Still tied to the official adapter release cycle; custom resolvers must match the unified schema
Custom GraphQL adapter	Unsupported backend or proprietary pricing, tax, or inventory logic	Full implementation of the GraphQL schema expected by the Vue Storefront frontend	Missing cart or checkout mutations can silently break functionality; you own all maintenance

Trade-offs

An official adapter reduces custom code because authentication, cart sync, and checkout redirect are already encapsulated. The trade-off is that you must confirm the adapter supports your backend version, and you may still need frontend query updates if you switch adapters later because backend fields do not always map one-to-one.

A custom adapter gives you full control over proprietary logic, but it must implement the full GraphQL schema expected by the frontend. A missing mutation may not produce an obvious error during catalog browsing; it can surface only when a customer tries to add an item to cart or complete checkout.

SSR performance is another constraint. Slow adapter resolvers increase server-side rendering time and time-to-first-byte for catalog pages under load, regardless of whether the adapter is official or custom.

Concrete implementation: configure and validate an official adapter

The following example uses a Shopify adapter as a placeholder. Package names, config file paths, and environment keys vary by adapter version; treat them as untrusted until you confirm them against your installed package.

1. Set middleware environment variables

Where to run: a terminal in the middleware directory, for example cd middleware. Required permissions: a user account that can edit files in the middleware project and restart the middleware process.

Create or edit .env in the middleware directory:

SHOPIFY_STORE_DOMAIN=YOUR_STORE.myshopify.com
SHOPIFY_STOREFRONT_ACCESS_TOKEN=YOUR_PUBLIC_STOREFRONT_TOKEN
SHOPIFY_API_VERSION=2024-01

Risk: do not copy these values into the Nuxt frontend runtimeConfig. Keep sensitive keys in the middleware server environment only.

2. Select the adapter in middleware configuration

Where to run: middleware project directory. Example configuration block; exact keys depend on the adapter version:

integrations: {
  shopify: {
    location: '@vue-storefront/shopify-api/src',
    configuration: {
      storeDomain: process.env.SHOPIFY_STORE_DOMAIN,
      storefrontAccessToken: process.env.SHOPIFY_STOREFRONT_ACCESS_TOKEN,
      apiVersion: process.env.SHOPIFY_API_VERSION
    }
  }
}

Restart the middleware after saving. Example command, depending on your process manager:

systemctl restart vue-storefront-middleware

or, under Docker:

docker compose restart middleware

3. Validate the GraphQL endpoint

Where to run: any client that can reach the middleware host, such as your local terminal. Required permissions: network access to the middleware GraphQL port.

curl -s -X POST http://localhost:8080/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { types { name } } }"}'

Expected check: the response should include a types array containing Product, Cart, and checkout-related types. If the endpoint returns an error or an empty schema, the adapter configuration or credentials are likely incorrect. Some adapter versions require authentication headers for introspection.

4. Validate server-side rendering

Where to run: the Vue Storefront storefront directory. Required permissions: ability to run a production build.

npm run build

Expected check: inspect the rendered server output or initial HTML for a catalog page. Product data should appear in the initial HTML, not only in client-side JavaScript. If product fields are missing, the SSR request to the adapter may be failing silently.

5. Validate checkout end to end

Where to run: a test customer session in the storefront, followed by a check in the commerce backend admin.

Expected check: complete a test checkout and confirm that the order, payment, and cart events appear in the commerce backend admin or logs. Risk: depending on the backend, a test checkout may create a real draft order or invoice.

Reverting the change

Because this procedure changes middleware configuration and restarts a running service, rollback means restoring the previous .env and configuration file, restarting the middleware, and re-running the GraphQL introspection check. If you also modified frontend queries for a specific adapter, revert those query changes in the storefront repository and redeploy.

Limitations and practical checks

• Adapter feature parity: confirm the supported adapter matrix for your backend version before selection. Practical check: review the adapter release notes for your installed package version.
• Custom schema gaps: missing mutations can silently break cart or checkout. Practical check: introspect the schema and execute cart and checkout mutations in staging.
• Breaking upgrades: pin middleware and adapter versions and test upgrades in staging. Practical check: inspect package.json for exact versions.
• SSR performance: slow resolvers increase time-to-first-byte. Practical check: measure catalog page TTFB under load.

Editorial note: this draft describes general Vue Storefront 2 behavior and has not been executed against a live adapter. Verify paths, package names, credentials handling, and feature parity for your specific version before production use.