docs: practical example of modifying integration's config based on re…

…quest (#6694) * docs: working on doc * docs: update * docs: updated the name * docs: gramarlly update * docs: update * docs: update * docs: update * docs: update * fix: typo Co-authored-by: Fifciuu <fjedrasik@vuestorefront.io> Co-authored-by: Filip Sobol <sobol.filip@gmail.com>
vuestorefront · Apr 6, 2022 · 6addc53 · 6addc53
1 parent 56ba576
commit 6addc53
Show file tree

Hide file tree

Showing 6 changed files with 118 additions and 19 deletions.
diff --git a/packages/core/docs/.vuepress/config.js b/packages/core/docs/.vuepress/config.js
@@ -164,6 +164,7 @@ module.exports = {
         children: [
           ['/integrate/extending-vue-storefront', 'Extending Vue Storefront'],
           ['/integrate/extending-integrations', 'Extending integrations'],
+          ['/integrate/cookie-based-config', 'Cookie-based configuration'],
           ['/integrate/integration-guide', 'Integrating e-commerce platform'],
           ['/integrate/cms', 'Integrating CMS platform'],
           ['/integrate/cache-driver', 'Integrating cache driver']
@@ -189,6 +190,13 @@ module.exports = {
           ['/performance/ssr-cache', 'SSR cache']
         ]
       },
+      {
+        title: 'Miscellaneous',
+        collapsable: true,
+        children: [
+          ['/miscellaneous/handling-cookies', 'Handling cookies']
+        ]
+      },
       {
         title: 'Reference',
         collapsable: true,

diff --git a/packages/core/docs/architecture/networking.md b/packages/core/docs/architecture/networking.md
@@ -1,6 +1,6 @@
 # Networking
 
-Vue Storefront differs slightly from most applications in the way it handles API communication. The most common way is for front-end applications to communicate directly with the API platforms (Service providers). However, In the Vue Storefront, there is a "proxy" between them called Server Middleware.
+Vue Storefront differs slightly from most applications in how it handles API communication. The most common way is for frontend applications to communicate directly with the API platforms (Service providers). However, in Vue Storefront, there is a "proxy" between them called Server Middleware.
 
 
 ## Data flow
@@ -14,7 +14,7 @@ Before we can understand Server Middleware, we need to discuss data flow from th
 We describe each of them in more detail in the following sections.
 
 :::tip There are exceptions
-For security reasons, data is sometimes sent directly from the user's browser to the Service providers. For example, the payment and authentication integrations communicate directly with or redirect to the third-party websites so that the sensitive customer information does not go through our servers.
+For security reasons, data is sometimes sent directly from the user's browser to the Service providers. For example, the payment and authentication integrations communicate directly with or redirect to the third-party websites so that sensitive customer information does not go through our servers.
 :::
 
 <figure style="text-align: center">
@@ -41,7 +41,7 @@ Server Middleware doesn't make any assumptions about the technologies used for t
 
 ### Service providers
 
-Server Middleware can communicate with a variety of service providers as long as they expose an API. It can use industry-standard libraries like `axios` or `Apollo` or platform-specific JavaScript SDKs.
+Server Middleware can communicate with various service providers as long as they expose an API. It can use industry-standard libraries like `axios` or `Apollo` or platform-specific JavaScript SDKs.
 
 In some scenarios, when the traffic should not go through the Server Middleware, it's possible to communicate directly between the browser and platforms. However, keep in mind that adding necessary libraries to your frontend can negatively impact the performance.
 

diff --git a/packages/core/docs/architecture/server-middleware.md b/packages/core/docs/architecture/server-middleware.md
@@ -5,12 +5,12 @@ The Server Middleware is an Express.js application implemented for a variety of
 - connect multiple services using different technologies and libraries,
 - allow you to create and [extend](/integrate/extending-integrations.html) integrations to add new capabilities or modify their behavior,
 - give you control of the requests sent to the integration platform and responses sent back to the Nuxt.js application,
-- securely store credentials on the server, without exposing them to the end-users of your application,
+- securely store credentials on the server without exposing them to the end-users of your application,
 - improve the performance by moving all logic of the networking layer to the server, thus shipping less code to the browser.
 
 ## Configuration
 
-Every Vue Storefront application comes with the `middleware.config.js` file located at the root of the project.  Inside this file, you can register packages that extend the Server Middleware by adding new API endpoints or modifying the Express.js application itself.
+Every Vue Storefront application comes with the `middleware.config.js` file located at the project's root. Inside this file, you can register packages that extend the Server Middleware by adding new API endpoints or modifying the Express.js application itself.
 
 ```javascript
 // middleware.config.js
@@ -48,7 +48,7 @@ To create Server Middleware integration, you can follow our [Integrating eCommer
 
 ## Extending an integrations
 
-As shown in the [Configuration](#configuration) section, integrations can be extended. You can follow our [Extending integrations](/integrate/extending-integrations.html) guide to learn more.
+As shown in the [Configuration](#configuration) section, integrations can be extended. To learn more, you can follow our [Extending integrations](/integrate/extending-integrations.html) guide.
 
 ## Separating Server Middleware from Nuxt.js
 
@@ -66,7 +66,7 @@ app.listen(8181, () => {
 });
 ```
 
-When you run this file using Node.js, the middleware will start its server without relying on Nuxt.js.
+When running this file using Node.js, the middleware will start its server without relying on Nuxt.js.
 
 You need to remove the Server Middleware module from the `nuxt.config.js` and configure the domain your middleware is using.
 
@@ -77,7 +77,7 @@ export default {
 -    '@vue-storefront/middleware/nuxt'
   ],
 +  publicRuntimeConfig: {
-+    middlewareUrl: 'https://api.commerce.com'
++    middlewareUrl: 'https://api.example.com'
 +  }
 }
 ```
diff --git a/packages/core/docs/integrate/cookie-based-config.md b/packages/core/docs/integrate/cookie-based-config.md
@@ -0,0 +1,75 @@
+# Cookie-based configuration
+
+This document shows how to dynamically change integration configuration in both Server Middleware and Nuxt based on the cookies.
+
+## Server Middleware integration
+
+You can change integration configuration in Server Middleware using extensions explained in the [Extending integrations](/integrate/extending-integrations.html) document.
+
+### Create integration extension
+
+Create a new JavaScript file and paste the code shown below. Let's assume that the path is `extensions/cookie-config.js`.
+
+```js
+// extensions/cookie-config.js
+
+module.exports = {
+  name: 'cookieBasedConfiguration',
+  hooks: (request) => ({
+    beforeCreate({ configuration }) {
+      const cookie = request.cookies.foo || 'default';
+      const cookieConfiguration = loadCookieConfiguration(cookie);
+
+      return {
+        ...configuration,
+        ...cookieConfiguration
+      };
+    }
+  })
+};
+```
+
+The extension has a `beforeCreate` hook, which gets called on every request to the integration before any other hook.
+
+We read the cookie value from the `request` object. Then using the `loadCookieConfiguration` function (which you must implement yourself), we load the associated configuration and override the base configuration.
+
+### Register the extension
+
+Now let's register our extension in the `middleware.config.js` file. Find the integration you want to override and add the `extensions` property if it doesn't exist already. Then, add the extension we created in the previous step to the returned array.
+
+```js{23}
+// middleware.config.js
+
+const cookieBasedConfiguration = require('./extensions/cookie-config');
+
+module.exports = {
+  integrations: {
+    '{INTEGRATION}': {
+      location: '{INTEGRATION}',
+      extensions: extensions => [...extensions, cookieBasedConfiguration]
+    }
+  }
+};
+```
+
+## Nuxt integration
+
+You can change the integration configuration in Nuxt using middleware.
+
+```ts
+export default ({ $vsf, $cookies }) => {
+  const cookie = $cookies.get('foo') || 'default';
+  const cookieConfiguration = loadCookieConfiguration(cookie);
+
+  const integration = $vsf.$integration; // Instead of `$integration`, use the integration key instead
+
+  integration.config = {
+    ...integration.config,
+    ...cookieConfiguration
+  };
+};
+```
+
+We read the cookie value using the `$cookies` property. Then using the `loadCookieConfiguration` function (which you must implement yourself), we load the associated configuration and override the base configuration.
+
+See the [Handling cookies](/miscellaneous/handling-cookies.html) document to learn more about cookies.
diff --git a/packages/core/docs/miscellaneous/handling-cookies.md b/packages/core/docs/miscellaneous/handling-cookies.md
@@ -0,0 +1,27 @@
+# Handling cookies
+
+Thanks to the preinstalled [cookie-universal-nuxt](https://www.npmjs.com/package/cookie-universal-nuxt) package, we can easily handle cookies from both components and middlewares.
+
+Handling cookies in components:
+
+```vue
+<script>
+import { useContext } from '@nuxtjs/composition-api';
+
+export default {
+  setup () {
+    const { $cookies } = useContext();
+
+    // `$cookies.get()` or `$cookies.set()`
+  }
+};
+</script>
+```
+
+Handling cookies in middlewares:
+
+```javascript
+export default ({ $cookies }) => {
+  // `$cookies.get()` or `$cookies.set()`
+};
+```
diff --git a/yarn.lock b/yarn.lock
@@ -4374,17 +4374,6 @@
     "@typescript-eslint/types" "4.33.0"
     eslint-visitor-keys "^2.0.0"
 
-"@vue-storefront/core@~2.5.4", "@vue-storefront/core@~2.5.5", "@vue-storefront/core@~2.5.6":
-  version "2.5.6"
-  resolved "https://registry.yarnpkg.com/@vue-storefront/core/-/core-2.5.6.tgz#dfbfce48487a9a4a6b34576fb23d625ed0ebfada"
-  integrity sha512-+nJHlcUdn0hJs0lD4AdxGZzLj3GrI9wXvPw1SFR4i2q0cJDiaCyoX/13e7BuRbJOuI8Cnoe/oK+O9VWZXrvXOQ==
-  dependencies:
-    axios "0.21.1"
-    express "^4.17.1"
-    is-https "^3.0.2"
-    lodash-es "^4.17.15"
-    vue "^2.6.11"
-
 "@vue-storefront/theme-utilities@^0.1.3":
   version "0.1.7"
   resolved "https://registrynpm.storefrontcloud.io/@vue-storefront%2ftheme-utilities/-/theme-utilities-0.1.7.tgz#0f54ad97daa27a9c2b674c205d729d27b1d9adbe"