docs(tf-415): different configurations for same file (#7410)

Author: dawid-ziobro

docs/content/guides/6.multistore/3.patterns/3.data/1.different-config-same-integration.md

@@ -6,3 +6,212 @@ navigation:
 ---
 
 # Different configurations for the same integration
+
+When building a multistore solution, you'll often need to use the same integration with different configurations across your stores. This guide explains how to efficiently manage multiple configurations for the same integration while maintaining a clean and maintainable codebase.
+
+**What You'll Learn**
+
+::list{type="success"}
+- Understanding when you need different configurations for the same integration
+- How to implement store-specific integration configurations
+- Best practices for managing integration configurations across multiple stores
+- Using environment variables to reduce code duplication
+::
+
+## When Do You Need Multiple Configurations?
+
+Let's explore some common scenarios where you might need different configurations for the same integration:
+
+### Use Case 1: Different Content in Stores Using a CMS Integration
+
+Imagine running two stores where the same CMS integration is used, but each store needs distinct content. For instance, a fashion store and a sports store have entirely different marketing copy and visuals.
+
+### Use Case 2: Multiple Product Catalogs for an eCommerce Integration
+
+Suppose your solution uses an integration with SAP Commerce Cloud (SAPCC). You want to build two stores—one for B2C and another for B2B. Each store requires a different product catalog.
+
+## Solution: Store-Specific Integration Configurations
+
+You can create and customize the **middleware** configuration for each store using **file-based inheritance**. Here's how it works:
+
+1. Create a configuration file for each store
+2. Override specific values (like product catalogs) in each file
+3. Each store will have its own configuration with values specific to its needs
+
+### Implementation Example
+
+For our SAP Commerce Cloud example with B2C and B2B stores:
+
+```ts
+// B2C store
+// /apps/stores/b2c/storefront-middleware/integrations/sapcc/config.ts
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'b2c-site', // store specific value
+      catalogId: 'b2cProductsCatalog', // store specific value
+      // ...
+    },
+  }
+}
+```
+
+```ts
+// B2B store
+// /apps/stores/b2b/storefront-middleware/integrations/sapcc/config.ts
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: 'b2b-site', // store specific value
+      catalogId: 'b2bProductsCatalog', // store specific value
+      // ...
+    },
+  }
+}
+```
+
+After this operation, the file structure will look like this:
+
+```bash
+apps/
+├── storefront-middleware
+|  ├── integrations
+|  |  └── sapcc
+|  |     └── config.ts # base config will be overridden by stores config
+└── stores
+   ├── b2c
+   |  ├── storefront-middleware
+   |  |  ├── integrations
+   |  |  |  └── sapcc
+   |  |  |     └── config.ts # new file for b2c store 
+   └── b2b
+      └── storefront-middleware
+         └── integrations
+            └── sapcc
+               └── config.ts # new file for b2b store 
+```
+
+:::tip
+This approach leverages the [file-based inheritance](/guides/multistore/tooling-and-concepts/file-based-inheritance) system in Alokai, allowing you to override only what's different while inheriting everything else.
+:::
+
+## Best Practices
+
+### 1. Use Environment Variables
+
+Instead of creating separate configuration files for each store, leverage **environment variables** where possible. Different environment settings can dynamically configure the middleware or storefront application for each store.
+
+This approach helps avoid duplicated files and makes your solution more modular, clean, and easy to maintain.
+
+Let's improve our previous configuration example to use environment variables:
+
+```ts
+// base source code, not nested in stores
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+const { BASE_SITE_ID, PRODUCT_CATALOG_ID } = process.env;
+
+export const config = {
+  configuration: {
+    api: {
+      baseSiteId: BASE_SITE_ID, // dynamic value
+      catalogId: PRODUCT_CATALOG_ID, // dynamic value
+      // ...
+    },
+  }
+}
+```
+
+For local development, use `.env` files specific to each store:
+
+```plaintext
+# b2c store
+# /apps/stores/b2c/storefront-middleware/.env
+BASE_SITE_ID="b2c-site"
+PRODUCT_CATALOG_ID="b2cProductsCatalog"
+
+# b2b store
+# /apps/stores/b2b/storefront-middleware/.env
+BASE_SITE_ID="b2b-site"
+PRODUCT_CATALOG_ID="b2bProductsCatalog"
+```
+
+:::warning
+`.env` files are git ignored out of the box, but it's important to verify this and ensure they are not
+accidentally committed. Use `.env.example` to provide a template on what variables are used.
+:::
+
+### 2. Use small files for overrides
+
+Where environment variables aren't suitable (like in cases requiring a lot of customization), follow these steps:
+
+- Separate the **overridable parts** of your configurations into distinct files
+- Use **file-based inheritance** to share the majority of the configuration
+- Override only what needs to change for individual stores
+
+This approach ensures your codebase remains clean and maintainable without introducing unnecessary code duplication.
+
+See the example below to learn how to implement it:
+
+First, define the usage of the new override file in the base code:
+
+```ts
+// base source code, not nested in stores
+// /apps/storefront-middleware/integrations/sapcc/config.ts
+
+// new file with part of the store specific configuration
+import { configPart } from './storeSpecificConfig';
+
+export const config = {
+  configuration: {
+    api: {
+      ...configPart,
+      // ...
+    },
+  }
+}
+```
+
+Next, create a small file containing the store-specific portion of the configuration:
+
+```ts
+// B2C store
+// /apps/stores/b2c/storefront-middleware/integrations/sapcc/storeSpecificConfig.ts
+
+export const configPart = {
+  baseSiteId: 'b2c-site', // store specific value
+  catalogId: 'b2cProductsCatalog', // store specific value
+};
+```
+
+With this setup, the store-specific configuration will seamlessly integrate with the base configuration
+
+## Setting Up Environment Variables for instances in Alokai Console
+
+Every instance can have its own environment variables configured for middleware and storefront application. To find out how to provide environment variables, please check the [Console docs](/console/instance/settings/environment-variables).
+
+For developers, working with `.env` files is straightforward:
+1. Copy the `.env.example` file
+2. Rename it to `.env` and customize its values for the specific store
+3. The environment variables will be automatically loaded when you run the store locally
+
+## Final Recommendations
+
+1. **Modular Setup**: Use environment variables and file-based inheritance to avoid duplication and ensure shared code remains central.
+2. **Clean Configuration Files**: Keep files minimal with overrides only for values that differ between stores.
+3. **Versioned Examples**: Always provide `.env.example` templates and ensure sensitive data isn't pushed to the repository.
+
+By following these practices, your setup will remain clean, scalable, and easy to manage, no matter how many stores or integrations you add in the future.
+
+::card{title="Next: Different integrations in each store" icon="tabler:number-2-small" }
+
+#description
+Learn how to implement and manage different integrations across your stores.
+
+#cta
+:::docs-button{to="/guides/multistore/patterns/data/different-integrations-per-store"}
+Next
+:::
+::