Enable Multi‑Store (Store‑View) Mode in Vue Storefront 2.x

Desired outcome

You want a single Vue Storefront (VSF) 2.x instance to serve several storefronts, each with its own locale, currency and catalog. The storefront is distinguished by a store‑view code that is passed either in a request header or as a URL query parameter.

Prerequisites

• A VSF 2.x project already installed (created with vue-storefront/nuxt-theme or similar).
• Access to a compatible backend (Magento 2/Adobe Commerce or Shopify) that has been configured with multiple store views and exposes store‑view‑scoped API endpoints (e.g., /api/products?storeView=code).
• Write permission to the project’s root directory so you can edit .env files and source code.
• Node.js ≥14 and Yarn (or npm) available in your development environment.

Procedure

1. Create a dedicated environment file for the store view

   Duplicate the root .env file and name the copy after the store view you intend to use, for example .env.fr for a French store view.

   cp .env .env.fr
   

   Edit the new file and set the STORE_VIEW_CODE variable to the exact code that matches the backend store view.

   # .env.fr
   STORE_VIEW_CODE=fr
   

2. Make the middleware aware of the store‑view code

   Open middleware/src/middleware.ts (or the equivalent middleware entry point in your project). Add a read of process.env.STORE_VIEW_CODE and inject it into every outbound API request as a custom header or query parameter.

   import { Context } from '@vue-storefront/core'
   
   export default function (context: Context) {
     const storeView = process.env.STORE_VIEW_CODE
     return {
       // existing middleware logic …
       async after (params) {
         // attach store‑view header if defined
         if (storeView) {
           params.headers['X-Store-View'] = storeView
         }
         return params
       }
     }
   }
   

3. Add locale files and register them with Nuxt i18n

   Create a JSON translation file for the store view under locales/. For the French example:

   # locales/fr.json
   {
     "welcome": "Bienvenue",
     "cart": "Panier"
   }
   

   Then edit nuxt.config.js (or nuxt.config.ts) to register the new locale:

   export default {
     modules: ['@nuxtjs/i18n'],
     i18n: {
       locales: [
         { code: 'en', iso: 'en-US', file: 'en.json' },
         { code: 'fr', iso: 'fr-FR', file: 'fr.json' } // ← added
       ],
       defaultLocale: 'en',
       // other i18n options …
     }
   }
   

4. Rebuild and start the application

   Because the store‑view code is read at build time, you must rebuild the project after changing the environment file.

   # Use the dedicated env file for the build
   cp .env.fr .env   # temporarily point .env to the store‑view config
   yarn build
   # Start the server (dev or prod as needed)
   yarn start
   

   When you are done testing this store view, repeat the copy step with the appropriate .env.storeview file.

Expected checks

• API responses include the header X-Store-View: fr (or whatever code you set).
• The UI language switcher automatically shows the French locale and prices are displayed in EUR.
• Static assets (images, CSS) load without 404 errors for the store view.
• Switching the URL query parameter ?storeView=en (or changing the header) results in the English locale and USD prices, confirming runtime switching works when the env file is swapped and the server is restarted.

Recovery options (rollback)

1. Restore the original environment file: cp .env.backup .env (or simply delete the custom .env.fr and rename the backup).
2. Revert the middleware changes: either delete the added if (storeView) { … } block or comment it out.
3. Clear Nuxt and module caches to avoid picking up stale compiled code:

rm -rf .nuxt
rm -rf node_modules/.cache

1. Reinstall dependencies if you removed the cache:

yarn install

1. Restart the development server:

yarn dev

After these steps the application should behave as a single‑store VSF instance again.

Limitations and practical notes

• This guide applies only to VSF 2.x; VSF 1.x uses a different extension mechanism and does not support runtime store‑view switching via environment variables.
• The backend must expose store‑view‑scoped endpoints; supplying an incorrect or missing STORE_VIEW_CODE will result in empty catalog responses or errors.
• Server‑side caching layers (Redis, Varnish, etc.) may serve stale data if cache keys do not incorporate the store‑view identifier. Ensure cache keys include the STORE_VIEW_CODE value or disable caching while testing.
• Because the middleware reads process.env.STORE_VIEW_CODE at build time, changing the store view requires a rebuild and server restart; there is no hot‑reload mechanism for this value in the default VSF template.