Repository: vuestorefront/vue-storefront
Pull request #7415: docs(tf-372): add middleware config switcher
Author: login: dawid-ziobro
Created: 2025-03-24T17:26:38Z | Merged: 2025-03-26T09:07:17Z

https://alokai.atlassian.net/browse/TF-387


Diff:
diff --git a/docs/content/guides/6.multistore/2.tooling-and-concepts/3.development/4.local-environment.md b/docs/content/guides/6.multistore/2.tooling-and-concepts/3.development/4.local-environment.md
index 43673b6811..af84683687 100644
--- a/docs/content/guides/6.multistore/2.tooling-and-concepts/3.development/4.local-environment.md
+++ b/docs/content/guides/6.multistore/2.tooling-and-concepts/3.development/4.local-environment.md
@@ -195,7 +195,7 @@ This will skip the build and only compose the store into the `.out` directory.
 ::card{title="Next: Development - Writing an integration tests with Playwright" icon="tabler:number-3-small" }
 
 #description
-TODO
+Learn how to create and run integration tests using Playwright in your Alokai multistore project.
 
 #cta
 :::docs-arrow-link{to="/guides/multistore/tooling-and-concepts/integration-tests"}
diff --git a/docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md b/docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
index ee0e896ef3..3c7b6c65c1 100644
--- a/docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
+++ b/docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
@@ -6,3 +6,330 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+## Understanding Sub-Path Routing Architecture
+
+Sub-path routing in Alokai consists of two essential components: the storefront (frontend) and the middleware (backend). This architectural pattern allows you to serve different content or product catalogs through distinct URL paths within the same application. **This guide focuses exclusively on implementing the middleware aspect of sub-path routing** using the `ConfigSwitcher` extension, which dynamically changes integration configurations based on URL paths. For comprehensive information about implementing sub-path routing in storefront applications ([Next.js](./1.subpath-next.md) and [Nuxt](./2.subpath-nuxt.md)), please refer to the dedicated documentation for those frameworks.
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+### Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations
+::
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+Take a look at the diagram to see the difference:
+
+<img src="../../img/file-based-vs-switcher-diagram.png" alt="Comparison of File-based Inheritance vs Config Switcher" class="mx-auto">
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the `api` object. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
+
+### Step 4: Create `ConfigSwitcher` extension
+
+Now let's create a `ConfigSwitcher` extension file.
+Create a new file and name it `configSwitcher.ts`. Place it where the other extensions for the given integration are located. Continuing example with SAPCC, place it in the directory `/apps/storefront-middleware/integrations/sapcc/extensions`. 
+
+Fill the newly created file with the content from the snippet below:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/extensions/configSwitcher.ts
+
+import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
+  configuration: {},
+});
+```
+
+Now you need to supply the configuration for the `ConfigSwitcher` extension with the configuration file you created in the previous step. Import it from the file and use it inside the extension:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/extensions/configSwitcher.ts
+
+import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+import { config } from '../switcher.config'; // [!code ++]
+
+export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
+  configuration: {}, // [!code --]
+  configuration: config, // [!code ++]
+});
+```
+
+### Step 5: Register the new extension
+
+The final step is to add the `ConfigSwitcher` extension to the main configuration of the given integration.
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+import { configSwitcherExtension } from './extensions/configSwitcher'; // [!code ++]
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions,
+    configSwitcherExtension, // [!code ++]
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+## Multiple Integrations
+
+Each integration requires its own `ConfigSwitcher` setup. If your project uses multiple integrations (e.g., SAPCC for eCommerce and Contentful for CMS), you'll need to configure the `ConfigSwitcher` separately for each one.
+
+Every `ConfigSwitcher` extensions must use the same configuration IDs, which means that you cannot use different configuration IDs in different extensions.
+
+## Typescript
+
+To enable proper typing, create a new type that will define the configuration of the `ConfigSwitcher` extension. For this purpose, use the `Config` type from the base configuration of the integration whose configuration you're changing.
+
+
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/switcher.config.ts 
+
+import type { Config } from './config';
+```
+
+Since each configuration option can be overridden, and the type may have some keys marked as required that you won't be overriding, you must override the type so that none of the keys are required. Use the `Partial` type for this. If you want to override only selected values for the `api` key in the configuration, you can do it in the way shown below:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.switcher.ts
+
+// [!code ++:10]
+import type { Config } from './config';
+
+type ConfigSwitcherItem = {
+  api?: Partial<Config['api']>;
+};
+
+export type ConfigSwitcher = {
+  [key: string]: Partial<ConfigSwitcherItem>;
+};
+
+export const config = { // [!code --]
+export const config: ConfigSwitcher = { // [!code ++]
+  default: {},
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+This way, you can override only selected parts of the configuration, and TypeScript won't require you to provide all keys that are marked as required.
+
+
+## Advanced Topics
+
+This guide covered sub-path routing with the usage of headers strategy while used in the multibrand setup. For more advanced topics, see:
+- [Dynamic Configuration](/connect/middleware/2.guides/6.config-switcher.md#dynamic-configuration)
+- [Other Switch Strategies](/connect/middleware/2.guides/6.config-switcher.md#switch-strategies)
+- [Error Handling](/connect/middleware/2.guides/6.config-switcher.md#error-handling)
+
+---
+
+With sub-path routing properly configured, your Alokai application can now dynamically adapt to different contexts while maintaining a single codebase and deployment. This approach simplifies management while providing the flexibility needed for complex multi-catalog or multi-region scenarios.
+
+
diff --git a/docs/content/guides/6.multistore/img/file-based-vs-switcher-diagram.png b/docs/content/guides/6.multistore/img/file-based-vs-switcher-diagram.png
new file mode 100644
index 0000000000..99cbae0f33
Binary files /dev/null and b/docs/content/guides/6.multistore/img/file-based-vs-switcher-diagram.png differ


Reviews:
user: login: mateuszo
body: I'm a bit lost with this guide. The title is "How to make sub-path routing on Middleware" but the first paragraph doesn't mention sub-path routing at all.  I suggest removing the notion of sub-path routing here and create a separate guide about it that refers to this one.
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T08:07:07Z
user: login: dawid-ziobro
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T09:04:45Z
user: login: dawid-ziobro
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T09:11:12Z
user: login: dawid-ziobro
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T09:11:51Z
user: login: dawid-ziobro
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T09:12:51Z
user: login: mateuszo
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T10:10:18Z
user: login: dawid-ziobro
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-25T13:18:36Z
user: login: mateuszo
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-26T07:40:40Z

Review comments:
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the api key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: mateuszo
body: "api key" might be misunderstood badly by AI or some humans :D 
I'm not sure if this would help:
 ```suggestion
Note that the overrides are made here within the "api" key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
```
created_at: 2025-03-25T07:45:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the api key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
+
+### Step 4: Create `ConfigSwitcher` extension
+
+Now let's create a `ConfigSwitcher` extension file.
+Create a new file and name it `configSwitcher.ts`. Place it where the other extensions for the given integration are located. Continuing example with SAPCC, place it in the directory `/apps/storefront-middleware/integrations/sapcc/extensions`. 
+
+Fill the newly created file with the content from the snippet below:
+
+```ts
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: mateuszo
body: ```suggestion
```ts[/apps/storefront-middleware/integrations/sapcc/extensions]
```
created_at: 2025-03-25T07:48:42Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the api key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
+
+### Step 4: Create `ConfigSwitcher` extension
+
+Now let's create a `ConfigSwitcher` extension file.
+Create a new file and name it `configSwitcher.ts`. Place it where the other extensions for the given integration are located. Continuing example with SAPCC, place it in the directory `/apps/storefront-middleware/integrations/sapcc/extensions`. 
+
+Fill the newly created file with the content from the snippet below:
+
+```ts
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: mateuszo
body: Add paths to the files in all the snippets if applicable.
created_at: 2025-03-25T07:49:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: mateuszo
body: I miss an end-to-end example in this guide. With the examples provided here I'm not able to test whether it works. I suggest adding some example of how to set `x-alokai-middleware-config-id` in the storefront.
created_at: 2025-03-25T07:57:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: mateuszo
body: It would be nice to show the same example as in this guide but implemented with file-based inheritance. This would make it easier to compare.
Also, a visual diagram would be nice. Something like this, maybe?
![image](https://github.com/user-attachments/assets/f2cd7161-7fda-4a84-a1f4-5700416e1a77)

created_at: 2025-03-25T07:59:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the api key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
+
+### Step 4: Create `ConfigSwitcher` extension
+
+Now let's create a `ConfigSwitcher` extension file.
+Create a new file and name it `configSwitcher.ts`. Place it where the other extensions for the given integration are located. Continuing example with SAPCC, place it in the directory `/apps/storefront-middleware/integrations/sapcc/extensions`. 
+
+Fill the newly created file with the content from the snippet below:
+
+```ts
+import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
+  configuration: {},
+});
+```
+
+Now you need to supply the configuration for the `ConfigSwitcher` extension with the configuration file you created in the previous step. Import it from the file and use it inside the extension:
+
+
+```ts
+import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+import { config } from '../switcher.config'; // [!code ++]
+
+export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
+  configuration: {}, // [!code --]
+  configuration: config, // [!code ++]
+});
+```
+
+### Step 5: Register the new extension
+
+The final step is to add the `ConfigSwitcher` extension to the main configuration of the given integration.
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+import { configSwitcherExtension } from './extensions/configSwitcher'; // [!code ++]
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions,
+    configSwitcherExtension, // [!code ++]
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+## Multiple Integrations
+
+Each integration requires its own `ConfigSwitcher` setup. If your project uses multiple integrations (e.g., SAPCC for eCommerce and Contentful for CMS), you'll need to configure the `ConfigSwitcher` separately for each one.
+
+Every `ConfigSwitcher` extensions must use the same configuration IDs, which means that you cannot use different configuration IDs in different extensions.
+
+## Typescript
+
+To enable proper typing, create a new type that will define the configuration switcher config. For this purpose, use the `Config` type from the base configuration of the integration whose configuration you're changing.
+
+
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/switcher.config.ts 
+
+import type { Config } from './config';
+```
+
+Since each configuration option can be overridden, and the type may have some keys marked as required that you won't be overriding, you must override the type so that none of the keys are required. Use the `Partial` type for this. If you want to override only selected values for the `api` key in the configuration, you can do it in the way shown below:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.switcher.ts
+
+// [!code ++:10]
+import type { Config } from './config';
+
+type ConfigSwitcherItem = {
+  api?: Partial<Config['api']>;
+};
+
+export type ConfigSwitcher = {
+  [key: string]: Partial<ConfigSwitcherItem>;
+};
+
+export const config = { // [!code --]
+export const config: ConfigSwitcher = { // [!code ++]
+  default: {},
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+This way, you can override only selected parts of the `api` key, and TypeScript won't require you to provide all keys that are marked as required.
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: mateuszo
body: ```suggestion
This way, you can override only selected parts of the configuration, and TypeScript won't require you to provide all keys that are marked as required.
```
created_at: 2025-03-25T08:01:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: dawid-ziobro
body: We have another task and another docs to be written for handling storefront. This docs is focused on middleware itself.
created_at: 2025-03-25T09:04:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the api key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
+
+### Step 4: Create `ConfigSwitcher` extension
+
+Now let's create a `ConfigSwitcher` extension file.
+Create a new file and name it `configSwitcher.ts`. Place it where the other extensions for the given integration are located. Continuing example with SAPCC, place it in the directory `/apps/storefront-middleware/integrations/sapcc/extensions`. 
+
+Fill the newly created file with the content from the snippet below:
+
+```ts
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: dawid-ziobro
body: Oh i missed one or two. Fixed
created_at: 2025-03-25T09:11:12Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the api key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: dawid-ziobro
body: Fair point :) i've updated it with 
```
`api` object.
```
created_at: 2025-03-25T09:11:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
+
+`ConfigSwitcher` operates differently from file-based inheritance:
+
+| **File-Based Inheritance**              | **ConfigSwitcher**                            |
+|-----------------------------------------|-----------------------------------------------|
+| Works **between different stores**      | Works **within a single store**               |
+| Creates separate deployable instances   | Uses a single deployable instance             |
+| Full codebase customization             | Only middleware configuration changes         |
+| Requires separate builds for each store | Single build supports multiple configurations |
+
+## Configurable Elements
+
+The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
+
+A typical configuration file looks like this:
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
+
+export const config = {
+   configuration: {
+      // configuration options
+   },
+   location: '@vsf-enterprise/<your-integration>/server',
+   extensions: (extensions: ApiClientExtension[]) => [
+      // extensions for the integration
+   ],
+} satisfies Integration<MiddlewareConfig>;
+```
+
+Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
+
+::warning
+If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at: 
+
+`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
+::
+
+A SAPCC specific configuration file looks like this:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
+Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool. 
+
+## Implementation Guide
+
+### Step 1: Create a configuration file
+
+The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
+
+To keep things organized, you should create this file in the same directory as your integration's configuration file. The recommended name for this file is `switcher.config.ts`.
+
+For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
+
+::tip
+If you've overridden the configuration file for some store, perform this step in its directory. If, for example, the store is `store-c`, the correct file path becomes:
+
+`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
+::
+
+### Step 2: Create a configuration object
+
+Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
+
+Example config object:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {}
+}
+```
+
+Note that two keys have been placed here: `default` and `electronics`. Config object **must contain all** configuration keys that are used by a given store, even those you won't be changing. If you don't want to override some configuration, leave an empty object. Only make the changes you need, everything else will be inherited from the main configuration.
+
+### Step 3: Apply overrides
+
+Let's assume you want to change the product catalog for the configuration with ID `electronics`. To do it extend the given example with this change:
+
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
+
+export const config = {
+  default: {},
+  electronics: {},  // [!code --]
+  // [!code ++:7]
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+Note that the overrides are made here within the api key. This is important because configurations are merged with the main configuration, so their structure must be the same. In the base configuration, these keys are also nested inside of the `api` object.
+
+### Step 4: Create `ConfigSwitcher` extension
+
+Now let's create a `ConfigSwitcher` extension file.
+Create a new file and name it `configSwitcher.ts`. Place it where the other extensions for the given integration are located. Continuing example with SAPCC, place it in the directory `/apps/storefront-middleware/integrations/sapcc/extensions`. 
+
+Fill the newly created file with the content from the snippet below:
+
+```ts
+import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
+  configuration: {},
+});
+```
+
+Now you need to supply the configuration for the `ConfigSwitcher` extension with the configuration file you created in the previous step. Import it from the file and use it inside the extension:
+
+
+```ts
+import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+import { config } from '../switcher.config'; // [!code ++]
+
+export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
+  configuration: {}, // [!code --]
+  configuration: config, // [!code ++]
+});
+```
+
+### Step 5: Register the new extension
+
+The final step is to add the `ConfigSwitcher` extension to the main configuration of the given integration.
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
+import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
+
+import { configSwitcherExtension } from './extensions/configSwitcher'; // [!code ++]
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'default',
+      catalogId: 'defaultProductCatalog',
+      catalogVersion: 'Online',
+      defaultCurrency: 'USD',
+      defaultLanguage: 'en',
+      uri: 'https://<your-sap-api>',
+    },
+    OAuth: {
+      clientId: '<your-client-id>',
+      clientSecret: '<your-client-secret>',
+      tokenEndpoint: '/oauth/token',
+      tokenRevokeEndpoint: '/oauth/revoke',
+      uri: 'https://<your-sap-api>/authorizationserver/',
+    }
+  },
+
+  extensions: (extensions: ApiClientExtension[]) => [
+    ...extensions,
+    configSwitcherExtension, // [!code ++]
+  ],
+
+  location: '@vsf-enterprise/sapcc-api/server',
+} satisfies Integration<Config>;
+
+export type Config = MiddlewareConfig;
+```
+
+## Multiple Integrations
+
+Each integration requires its own `ConfigSwitcher` setup. If your project uses multiple integrations (e.g., SAPCC for eCommerce and Contentful for CMS), you'll need to configure the `ConfigSwitcher` separately for each one.
+
+Every `ConfigSwitcher` extensions must use the same configuration IDs, which means that you cannot use different configuration IDs in different extensions.
+
+## Typescript
+
+To enable proper typing, create a new type that will define the configuration switcher config. For this purpose, use the `Config` type from the base configuration of the integration whose configuration you're changing.
+
+
+```ts
+// /apps/storefront-middleware/integrations/<your-integration>/switcher.config.ts 
+
+import type { Config } from './config';
+```
+
+Since each configuration option can be overridden, and the type may have some keys marked as required that you won't be overriding, you must override the type so that none of the keys are required. Use the `Partial` type for this. If you want to override only selected values for the `api` key in the configuration, you can do it in the way shown below:
+
+```ts
+// /apps/storefront-middleware/integrations/sapcc/config.switcher.ts
+
+// [!code ++:10]
+import type { Config } from './config';
+
+type ConfigSwitcherItem = {
+  api?: Partial<Config['api']>;
+};
+
+export type ConfigSwitcher = {
+  [key: string]: Partial<ConfigSwitcherItem>;
+};
+
+export const config = { // [!code --]
+export const config: ConfigSwitcher = { // [!code ++]
+  default: {},
+  electronics: {
+    api: {
+      baseSiteId: 'electronics',
+      catalogId: 'electronicsProductCatalog',
+    },
+  },
+};
+```
+
+This way, you can override only selected parts of the `api` key, and TypeScript won't require you to provide all keys that are marked as required.
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: dawid-ziobro
body: Changed.
created_at: 2025-03-25T09:12:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -6,3 +6,310 @@ navigation:
 ---
 
 # How to make sub-path routing on Middleware
+
+The `ConfigSwitcher` extension in middleware enables dynamic configuration changes per request, allowing you to adapt your integrations like eCommerce or CMS settings based on specific URL paths. This powerful feature lets you serve different product catalogs or content collections through the same store instance but on different URL paths.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding how `ConfigSwitcher` extension works within the middleware
+- Setting up multiple configurations within a single store
+- Implementing integration-specific configurations 
+::
+
+## Why Use Sub-Path Routing?
+
+Sub-path routing allows you to create a more dynamic and flexible application that can adapt to different contexts based on the URL path. This approach can simplify your architecture by consolidating multiple configurations within a single store instance.
+
+## Common Use Cases
+
+1. **Multi-catalog stores**: Show different product catalogs based on URL paths
+2. **Regional content variations**: Serve different content based on region-specific paths
+3. **Brand-specific experiences**: Configure different brand experiences within the same store
+
+## Core Concepts
+
+### How ConfigSwitcher Works
+
+The `ConfigSwitcher` dynamically changes your middleware integration configuration based on the current request configuration ID sent with the `x-alokai-middleware-config-id` header. This means:
+
+1. **Path-Based Configuration**
+    - Different configuration ID set by different paths allow to fetch data from different sources
+    - Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
+
+2. **Configuration ID vs Store ID**
+    - Each configuration has its own distinct ID
+    - This is different from the store ID (`storeId`)
+    - Multiple configurations can exist within a single store
+
+3. **Same-Store Operation**
+    - `ConfigSwitcher` works within a single store instance
+    - It extracts the configuration ID from the request
+    - It executes queries using the appropriate configuration
+
+::tip
+The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
+::
+
+### Key Distinctions To File-Based Inheritance
path: docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md
user: login: dawid-ziobro
body: That is a good idea. I've added a new one as yours is unreadable in dark mode ;)
created_at: 2025-03-25T13:18:36Z
author_association: CONTRIBUTOR

PR comments:
user: login: changeset-bot[bot]
created_at: 2025-03-24T17:26:41Z
body: ###  ⚠️  No Changeset found

Latest commit: 9f1befd86f1d9884285102eff5e346a8491916c5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. **If these changes should result in a version bump, you need to add a changeset.**

<details><summary>This PR includes no changesets</summary>

  When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

</details>

[Click here to learn what changesets are, and how to add one](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).

[Click here if you're a maintainer who wants to add a changeset to this PR](https://github.com/vuestorefront/vue-storefront/new/docs/tf-372-config-switcher-middleware?filename=.changeset/spotty-bugs-serve.md&value=---%0A%0A---%0A%0Adocs(tf-372)%3A%20add%20middleware%20config%20switcher%0A)


author_association: NONE
user: login: dawid-ziobro
created_at: 2025-03-25T12:01:53Z
body: > I'm a bit lost with this guide. The title is "How to make sub-path routing on Middleware" but the first paragraph doesn't mention sub-path routing at all. I suggest removing the notion of sub-path routing here and create a separate guide about it that refers to this one.

Agree. I've updated the intro so it covers now a general idea on what path-based routing is. As this docs is middleware dedicated and we'll have storefronts dedicated ones. Then we'll create a master guide that will wrapping the whole idea and serve as a hub for those docs.
author_association: CONTRIBUTOR
user: login: sonarqubecloud[bot]
created_at: 2025-03-25T14:20:23Z
body: ## [![Quality Gate Passed](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/checks/QualityGateBadge/qg-passed-20px.png 'Quality Gate Passed')](https://sonarcloud.io/dashboard?id=vuestorefront_vue-storefront&pullRequest=7415) **Quality Gate passed**  
Issues  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 New issues](https://sonarcloud.io/project/issues?id=vuestorefront_vue-storefront&pullRequest=7415&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/accepted-16px.png '') [0 Accepted issues](https://sonarcloud.io/project/issues?id=vuestorefront_vue-storefront&pullRequest=7415&issueStatuses=ACCEPTED)

Measures  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0 Security Hotspots](https://sonarcloud.io/project/security_hotspots?id=vuestorefront_vue-storefront&pullRequest=7415&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Coverage on New Code](https://sonarcloud.io/component_measures?id=vuestorefront_vue-storefront&pullRequest=7415&metric=new_coverage&view=list)  
![](https://sonarsource.github.io/sonarcloud-github-static-resources/v2/common/passed-16px.png '') [0.0% Duplication on New Code](https://sonarcloud.io/component_measures?id=vuestorefront_vue-storefront&pullRequest=7415&metric=new_duplicated_lines_density&view=list)  
  
[See analysis details on SonarQube Cloud](https://sonarcloud.io/dashboard?id=vuestorefront_vue-storefront&pullRequest=7415)


author_association: NONE