Skip to content

Commit 9e06cb8

Browse files
dawid-ziobrodawid-ziobro
authored
docs(tf-372): add middleware config switcher (#7415)
1 parent 2b68c96 commit 9e06cb8

File tree

3 files changed

+328
-1
lines changed

3 files changed

+328
-1
lines changed

‎docs/content/guides/6.multistore/2.tooling-and-concepts/3.development/4.local-environment.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ This will skip the build and only compose the store into the `.out` directory.
195195
::card{title="Next: Development - Writing an integration tests with Playwright" icon="tabler:number-3-small" }
196196

197197
#description
198-
TODO
198+
Learn how to create and run integration tests using Playwright in your Alokai multistore project.
199199

200200
#cta
201201
:::docs-arrow-link{to="/guides/multistore/tooling-and-concepts/integration-tests"}

‎docs/content/guides/6.multistore/3.patterns/5.subpath/3.subpath-middleware.md

Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,330 @@ navigation:
66
---
77

88
# How to make sub-path routing on Middleware
9+
10+
## Understanding Sub-Path Routing Architecture
11+
12+
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.
13+
14+
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.
15+
16+
## Why Use Sub-Path Routing?
17+
18+
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.
19+
20+
### Common Use Cases
21+
22+
1. **Multi-catalog stores**: Show different product catalogs based on URL paths
23+
2. **Regional content variations**: Serve different content based on region-specific paths
24+
3. **Brand-specific experiences**: Configure different brand experiences within the same store
25+
26+
**What You'll Learn**
27+
28+
::list{type="success"}
29+
- Understanding how `ConfigSwitcher` extension works within the middleware
30+
- Setting up multiple configurations within a single store
31+
- Implementing integration-specific configurations
32+
::
33+
34+
## Core Concepts
35+
36+
### How ConfigSwitcher Works
37+
38+
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:
39+
40+
1. **Path-Based Configuration**
41+
- Different configuration ID set by different paths allow to fetch data from different sources
42+
- Example: `/clothes` path shows apparel products, while `/electronics` shows electronics products
43+
44+
2. **Configuration ID vs Store ID**
45+
- Each configuration has its own distinct ID
46+
- This is different from the store ID (`storeId`)
47+
- Multiple configurations can exist within a single store
48+
49+
3. **Same-Store Operation**
50+
- `ConfigSwitcher` works within a single store instance
51+
- It extracts the configuration ID from the request
52+
- It executes queries using the appropriate configuration
53+
54+
::tip
55+
The `ConfigSwitcher` only affects middleware configuration. The frontend remains the same, but it receives data from different sources based on the URL path.
56+
::
57+
58+
### Key Distinctions To File-Based Inheritance
59+
60+
`ConfigSwitcher` operates differently from file-based inheritance:
61+
62+
| **File-Based Inheritance** | **ConfigSwitcher** |
63+
|-----------------------------------------|-----------------------------------------------|
64+
| Works **between different stores** | Works **within a single store** |
65+
| Creates separate deployable instances | Uses a single deployable instance |
66+
| Full codebase customization | Only middleware configuration changes |
67+
| Requires separate builds for each store | Single build supports multiple configurations |
68+
69+
Take a look at the diagram to see the difference:
70+
71+
<img src="../../img/file-based-vs-switcher-diagram.png" alt="Comparison of File-based Inheritance vs Config Switcher" class="mx-auto">
72+
73+
## Configurable Elements
74+
75+
The `ConfigSwitcher` extension allows you to change only the `configuration` object of the specific integration config.
76+
77+
A typical configuration file looks like this:
78+
```ts
79+
// /apps/storefront-middleware/integrations/<your-integration>/config.ts
80+
81+
import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
82+
import type { MiddlewareConfig } from '@vsf-enterprise/<your-integrarion>';
83+
84+
export const config = {
85+
configuration: {
86+
// configuration options
87+
},
88+
location: '@vsf-enterprise/<your-integration>/server',
89+
extensions: (extensions: ApiClientExtension[]) => [
90+
// extensions for the integration
91+
],
92+
} satisfies Integration<MiddlewareConfig>;
93+
```
94+
95+
Let's use SAPCC eCommerce integration as an example, by default the configuration file is located at: `/apps/storefront-middleware/integrations/sapcc/config.ts`
96+
97+
::warning
98+
If you've overridden this file for a specific store (e.g., `store-c`), your configuration would be at:
99+
100+
`apps/stores/store-c/storefront-middleware/integrations/sapcc/config.ts`
101+
::
102+
103+
A SAPCC specific configuration file looks like this:
104+
105+
```ts
106+
// /apps/storefront-middleware/integrations/sapcc/config.ts
107+
108+
import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
109+
import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
110+
111+
export const config = {
112+
configuration: {
113+
api: {
114+
baseSiteId: 'default',
115+
catalogId: 'defaultProductCatalog',
116+
catalogVersion: 'Online',
117+
defaultCurrency: 'USD',
118+
defaultLanguage: 'en',
119+
uri: 'https://<your-sap-api>',
120+
},
121+
OAuth: {
122+
clientId: '<your-client-id>',
123+
clientSecret: '<your-client-secret>',
124+
tokenEndpoint: '/oauth/token',
125+
tokenRevokeEndpoint: '/oauth/revoke',
126+
uri: 'https://<your-sap-api>/authorizationserver/',
127+
}
128+
},
129+
130+
extensions: (extensions: ApiClientExtension[]) => [
131+
...extensions
132+
],
133+
134+
location: '@vsf-enterprise/sapcc-api/server',
135+
} satisfies Integration<Config>;
136+
137+
export type Config = MiddlewareConfig;
138+
```
139+
140+
By looking at this config file you can see that you can modify anything inside of the `api` or `OAuth` objects.
141+
Other objects outside of the `configuration` object like the `extensions` and `location` cannot be modified using this tool.
142+
143+
## Implementation Guide
144+
145+
### Step 1: Create a configuration file
146+
147+
The first step is to create a dedicated configuration file for your integration, in which all possible configurations will be defined.
148+
149+
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`.
150+
151+
For the above SAPCC example, this file path would look like this: `/apps/storefront-middleware/integrations/sapcc/`.
152+
153+
::tip
154+
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:
155+
156+
`/apps/stores/store-c/storefront-middleware/integrations/sapcc/switcher.config.ts`
157+
::
158+
159+
### Step 2: Create a configuration object
160+
161+
Important: the keys of the `config` object will correspond to the configuration IDs that will be sent from the frontend. They must be consistent.
162+
163+
Example config object:
164+
165+
```ts
166+
// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
167+
168+
export const config = {
169+
default: {},
170+
electronics: {}
171+
}
172+
```
173+
174+
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.
175+
176+
### Step 3: Apply overrides
177+
178+
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:
179+
180+
181+
```ts
182+
// /apps/storefront-middleware/integrations/sapcc/switcher.config.ts
183+
184+
export const config = {
185+
default: {},
186+
electronics: {}, // [!code --]
187+
// [!code ++:7]
188+
electronics: {
189+
api: {
190+
baseSiteId: 'electronics',
191+
catalogId: 'electronicsProductCatalog',
192+
},
193+
},
194+
};
195+
```
196+
197+
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.
198+
199+
### Step 4: Create `ConfigSwitcher` extension
200+
201+
Now let's create a `ConfigSwitcher` extension file.
202+
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`.
203+
204+
Fill the newly created file with the content from the snippet below:
205+
206+
```ts
207+
// /apps/storefront-middleware/integrations/sapcc/extensions/configSwitcher.ts
208+
209+
import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
210+
import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
211+
212+
export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
213+
configuration: {},
214+
});
215+
```
216+
217+
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:
218+
219+
220+
```ts
221+
// /apps/storefront-middleware/integrations/sapcc/extensions/configSwitcher.ts
222+
223+
import { createConfigSwitcherExtension } from '@alokai/connect/config-switcher';
224+
import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
225+
226+
import { config } from '../switcher.config'; // [!code ++]
227+
228+
export const configSwitcherExtension = createConfigSwitcherExtension<MiddlewareConfig>({
229+
configuration: {}, // [!code --]
230+
configuration: config, // [!code ++]
231+
});
232+
```
233+
234+
### Step 5: Register the new extension
235+
236+
The final step is to add the `ConfigSwitcher` extension to the main configuration of the given integration.
237+
238+
```ts
239+
// /apps/storefront-middleware/integrations/sapcc/config.ts
240+
241+
import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
242+
import type { MiddlewareConfig } from '@vsf-enterprise/sapcc-api';
243+
244+
import { configSwitcherExtension } from './extensions/configSwitcher'; // [!code ++]
245+
246+
export const config = {
247+
configuration: {
248+
api: {
249+
baseSiteId: 'default',
250+
catalogId: 'defaultProductCatalog',
251+
catalogVersion: 'Online',
252+
defaultCurrency: 'USD',
253+
defaultLanguage: 'en',
254+
uri: 'https://<your-sap-api>',
255+
},
256+
OAuth: {
257+
clientId: '<your-client-id>',
258+
clientSecret: '<your-client-secret>',
259+
tokenEndpoint: '/oauth/token',
260+
tokenRevokeEndpoint: '/oauth/revoke',
261+
uri: 'https://<your-sap-api>/authorizationserver/',
262+
}
263+
},
264+
265+
extensions: (extensions: ApiClientExtension[]) => [
266+
...extensions,
267+
configSwitcherExtension, // [!code ++]
268+
],
269+
270+
location: '@vsf-enterprise/sapcc-api/server',
271+
} satisfies Integration<Config>;
272+
273+
export type Config = MiddlewareConfig;
274+
```
275+
276+
## Multiple Integrations
277+
278+
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.
279+
280+
Every `ConfigSwitcher` extensions must use the same configuration IDs, which means that you cannot use different configuration IDs in different extensions.
281+
282+
## Typescript
283+
284+
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.
285+
286+
287+
```ts
288+
// /apps/storefront-middleware/integrations/<your-integration>/switcher.config.ts
289+
290+
import type { Config } from './config';
291+
```
292+
293+
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:
294+
295+
```ts
296+
// /apps/storefront-middleware/integrations/sapcc/config.switcher.ts
297+
298+
// [!code ++:10]
299+
import type { Config } from './config';
300+
301+
type ConfigSwitcherItem = {
302+
api?: Partial<Config['api']>;
303+
};
304+
305+
export type ConfigSwitcher = {
306+
[key: string]: Partial<ConfigSwitcherItem>;
307+
};
308+
309+
export const config = { // [!code --]
310+
export const config: ConfigSwitcher = { // [!code ++]
311+
default: {},
312+
electronics: {
313+
api: {
314+
baseSiteId: 'electronics',
315+
catalogId: 'electronicsProductCatalog',
316+
},
317+
},
318+
};
319+
```
320+
321+
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.
322+
323+
324+
## Advanced Topics
325+
326+
This guide covered sub-path routing with the usage of headers strategy while used in the multibrand setup. For more advanced topics, see:
327+
- [Dynamic Configuration](/connect/middleware/2.guides/6.config-switcher.md#dynamic-configuration)
328+
- [Other Switch Strategies](/connect/middleware/2.guides/6.config-switcher.md#switch-strategies)
329+
- [Error Handling](/connect/middleware/2.guides/6.config-switcher.md#error-handling)
330+
331+
---
332+
333+
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.
334+
335+

‎docs/content/guides/6.multistore/img/file-based-vs-switcher-diagram.png

55.2 KB
Loading

0 commit comments

Comments
 (0)