@graphcommerce/docs 8.0.6-canary.3 → 8.1.0-canary.10

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Change Log
 
+## 8.1.0-canary.10
+
+## 8.1.0-canary.9
+
+### Patch Changes
+
+- [#2223](https://github.com/graphcommerce-org/graphcommerce/pull/2223) [`7652234`](https://github.com/graphcommerce-org/graphcommerce/commit/7652234e222c3f4d8de3817fe907b5b6925a5493) - Replaced next-sitemap with page router based robots.txt & sitemaps
+  ([@bramvanderholst](https://github.com/bramvanderholst))
+
+## 8.1.0-canary.8
+
+### Patch Changes
+
+- [#2247](https://github.com/graphcommerce-org/graphcommerce/pull/2247) [`444e446`](https://github.com/graphcommerce-org/graphcommerce/commit/444e446a218cc9da3defb940a6d5cce0229ff845) - Added clear upgrade instructions for linguiLocale
+  ([@paales](https://github.com/paales))
+
+## 8.1.0-canary.7
+
+## 8.1.0-canary.6
+
+### Patch Changes
+
+- [#1984](https://github.com/graphcommerce-org/graphcommerce/pull/1984) [`e05534f`](https://github.com/graphcommerce-org/graphcommerce/commit/e05534fff4990fd584fe401b55b6d9a33934e048) - Added docs about caching
+  ([@paales](https://github.com/paales))
+
+## 8.1.0-canary.5
+
+## 8.0.6-canary.4
+
 ## 8.0.6-canary.3
 
 ## 8.0.6-canary.2

package/framework/caching.md

@@ -0,0 +1,205 @@
+# Caching
+
+Caching can be a complex topic especially when you have multiple layers of
+caching.
+
+- [Cache on the server](#caching-on-the-server)
+- [Cache in the browser](#caching-in-the-browser)
+- [Cache in the service worker](#caching-in-the-service-worker)
+- [Cache invalidation limitations](#cache-invalidation-limitations)
+
+## Caching on the server
+
+### During development
+
+- Next.js will not cache any requests
+- Magento will cache GraphQL calls. This is done by Magento itself, not by
+  GraphCommerce.
+
+### How long will a page be cached (getStaticProps)?
+
+GraphCommerce uses
+[Incremental Static Regeneration (ISR)](https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration#on-demand-revalidation)
+to cache pages with getStaticProps.
+
+> If you set a revalidate time of 60, all visitors will see the same generated
+> version of your site for one minute. The only way to invalidate the cache is
+> from someone visiting that page after the minute has passed.
+
+The length is determined by the `revalidate` property on the object that is
+returned by `getStaticProps`. In GraphCommerce
+[we use 60 \* 20](https://github.com/search?q=repo%3Agraphcommerce-org%2Fgraphcommerce+revalidate%3A++path%3A%2F%5Eexamples%5C%2Fmagento-graphcms%5C%2Fpages%5C%2F%2F&type=code).
+
+This means that a cache will be regenerated when:
+
+1. 20 minutes has passed
+2. A new request is made to the page
+
+Note: A page will never fall out of the cache if it is not requested. Even if
+this is a very long time. In practice this can be _days_.
+
+## How long will a page be cached (getServerSideProps)
+
+Not all pages use getStaticProps, a
+[few pages that are not static use getServerSideProps](https://github.com/search?q=repo%3Agraphcommerce-org%2Fgraphcommerce+getServerSideProps+path%3A%2F%5Eexamples%5C%2Fmagento-graphcms%5C%2Fpages%5C%2F%2F&type=code)
+
+The pages that do not use ISR are `/c/[...url]` and `/search/[...url]` which are
+filtered pages. These pages are not cached by the server at all.
+
+Even though the `/c/[...url]` page
+[sets a Cache-Control header](https://github.com/graphcommerce-org/graphcommerce/blob/canary/examples/magento-graphcms/pages/c/%5B...url%5D.tsx#L14-L17)
+it isn't cached by Cloudflare and isn't cached by the browser / service worker.
+
+### What happens when a backend is offline?
+
+If a page is rendered with getStaticProps and the had been rendered before, it
+will keep showing the old page. If the page hadn't been rendered before, it will
+show a 500 error.
+
+### How does caching work with Magento GraphQL?
+
+Magento caches GraphQL queries that are send as GET requests (which are all
+queries from GraphCommerce) and have a `@cache` directive configured in the
+schema.
+
+[Magento caches certain queries in GraphQL](https://developer.adobe.com/commerce/webapi/graphql/usage/caching/#cached-and-uncached-queries),
+the following are relevant for GraphCommerce: `categories`, `products`, `route`.
+You can also find out what is cached by doing a
+[search in the Magento codebase](https://github.com/search?q=repo%3Amagento%2Fmagento2+%40cache%28cacheIdentity+path%3A*.graphqls&type=code).
+
+Cache invalidation is using the same system as any page that is cached in
+Varnish.
+[GraphQL invalidation docs](https://developer.adobe.com/commerce/webapi/graphql/usage/caching/#cache-invalidation)
+
+### ApolloClient InMemory cache used on the server
+
+By default a GraphQL API call is _not_ cached, but by configuring fetchPolicy:
+'cache-first' when running the query, we can cache the response of a GraphQL API
+call.
+
+To reduce the API calls to certain backends, we use an in-memory cache on the
+server. There are two queries that are cached by ApolloClient's InMemory cache:
+
+- Layout query
+  [`staticClient.query({ query: LayoutDocument, fetchPolicy: 'cache-first' })`](https://github.com/graphcommerce-org/graphcommerce/blob/7728774cd7e9a4463508a99344b177877e3c826b/examples/magento-graphcms/pages/%5B...url%5D.tsx#L156)
+- HygraphAllPages query
+  [`await client.query({ query: HygraphAllPagesDocument, fetchPolicy: alwaysCache })`](https://github.com/graphcommerce-org/graphcommerce/blob/7728774cd7e9a4463508a99344b177877e3c826b/packages/hygraph-ui/lib/hygraphPageContent.ts#L31)
+
+We do this because this reduces the amount of GraphQL requests made to Hygraph
+about 100x. The Layout and HygraphAllPages query would else be request on _all_
+pages.
+
+The InMemory cache is kept indefinitely, it is never flushed! There currently is
+no way to flush this cache. This means that while a serverless funtion is
+running or a node process is running the cache will be kept in memory:
+
+- For serverless functions (Vercel) this isn't a problem as they are killed
+  after a few minutes.
+- For node.js processes this means that they _need_ to be restarted every now
+  and then. (a few times a day is fine)
+
+## Caching in the browser
+
+### Apollo Client caching in the browser
+
+By default all the information stored in the ApolloClient InMemory cache is also
+persisted to localStorage. When the page is loaded, the cache is restored from
+localStorage.
+
+Apollo Client tries and use the cache as much as possible. This means that
+multiple useQuery calls with the same query+variables will return the same
+result and all use the cache (default `fetchPolicy: 'cache-first'`)
+
+The exception is when a query is made with a different `fetchPolicy`. We
+[use 'cache-and-network' on quite a few queries](https://github.com/search?q=repo%3Agraphcommerce-org%2Fgraphcommerce+fetchPolicy%3A+%27cache-and-network%27&type=code)
+to make sure that the user always sees up-to-date data.
+
+#### Improvements since GraphCommerce 6.2.0:
+
+We've introduced the
+[persistenceMapper](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/graphql/components/GraphQLProvider/persistenceMapper.ts#L27-L36)
+that makes sure not everything gets persisted to localStorage. We prune the
+cache based on a list of selectors. This aims to keep the cache as small as
+possible, without chaning the default behavior that 'everything is persisted to
+localStorage'.
+
+### What is stored in the localStorage?
+
+All queries made with useQuery are stored in the localStorage of the user and is
+restored when the user visits the website
+
+- With GraphCommerce < 6.2.0: All queries made with useQuery are stored in the
+  localStorage of the user and is restored when the user visits the website
+- With GraphCommerce >= 6.2.0
+
+### Which HTTP requests are cache by the browser?
+
+- `pages` and `_next/data` requests are not cached and are requested each time a
+  page is visited. The `_next/data` requests is the actual data of a page to be
+  able to navigate faster over the site.
+- `_next/static` requests are cached by the browser. These include `images`,
+  `fonts` and `js` and `css`. All files are hashed and cleaned up when a new
+  deployment is made.
+- `_next/image`requests are cached by the browser, but has a 'revalidate' header
+  so requests will be revalidated by the browser.
+
+### Which HTTP requests are cached by the service worker?
+
+Service worker sits between the browser and the network. It can cache requests
+and return them from the cache instead of the network. This can be seen as an
+_additional_ caching layer which can be configured separately from the browser
+cache.
+
+The service worker caches:
+
+- [static fonts](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L28)
+- [static images](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L39)
+- [\_next/image](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L50)
+- [js](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L85)
+
+Note: When a new deployment is made, the service worker is updated. This means
+that all previous caches are cleared and new caches are created.
+
+It does not cache:
+
+- [\_next/data](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L107):
+  Although it looks like it does, the regex is actually wrong and it does not
+  cache anything.
+- [pages](https://github.com/shadowwalker/next-pwa/blob/master/cache.js#L152)
+  Uses NetworkFirst strategy, which means it will always try to fetch the
+  resource from the network first, and only if that fails it will use the cache.
+
+## Cache invalidation limitations
+
+### Pages keep having old information even though Magento has updated the data
+
+Currently there is no communcation between Magento and Next.js to revalidate a
+page when a product or category is updated.
+
+This means that a page will only be revalidated when a user visits the page
+again _and_ the revalidate time has been reached.
+
+Suggested solution: Accept the revalidate time or reduce the revalidate time of
+products and categories.
+
+#### Pages keeps having stale global information
+
+Even when a the LayoutDocument is refreshed by restarting a node.js process the
+fresh data is not automatically shown to a user.
+
+This means that a page only gets revalidated when a user visits the page again
+_and_ the revalidate time has been reached.
+
+This results in the situation that an header change like a navigation item or a
+'global message' will see the old information for a long time.
+
+Suggested solution: Create a fresh deployment
+
+1. Manually create a fresh deployment.
+2. Vercel: Integrate a
+   [deploy hook](https://vercel.com/docs/concepts/deployments/deploy-hooks) as a
+   [Hygraph webhook](https://hygraph.com/docs/api-reference/basics/webhooks)
+3. Github actions: Integrate a
+   [webhook_run](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run)
+   as a
+   [Hygraph webhook](https://hygraph.com/docs/api-reference/basics/webhooks)

package/framework/config.md

@@ -402,9 +402,12 @@ Add a gcms-locales header to make sure queries return in a certain language, can
 
 #### linguiLocale: string
 
-Specify a custom locale for to load translations. Must be lowercase valid locale.
+Custom locale used to load the .po files. Must be a valid locale, also used for Intl functions.
 
-This value is also used for the Intl.
+#### robotsAllow: boolean
+
+Allow the site to be indexed by search engines.
+If false, the robots.txt file will be set to disallow all.
 
 ### MagentoConfigurableVariantValues
 

package/framework/plugins-react.md

@@ -1,7 +1,7 @@
 # Plugins GraphCommerce
 
-GraphCommerce's plugin system allows you to extend GraphCommerce's built-in
-components or functions with your own logic.
+GraphCommerce's plugin system allows you to extend or replace GraphCommerce's
+built-in components or functions with your own logic.
 
 - No runtime overhead: The plugin system is fully implemented in webpack and
 - Easy plugin creation: Configuration should happen in the plugin file, not a
@@ -13,10 +13,11 @@ components or functions with your own logic.
 A plugin is a way to modify React Components or a Function by wrapping them,
 without having to modify the code directly.
 
-For the M2 people: Think of around plugins, but without configuration files and
-no performance penalty.
+> For the M2 people: Think of around plugins, but without configuration files
+> and no performance penalty.
 
-GraphCommerce has two kinds of plugins, React Component plugins and Function
+GraphCommerce has three kinds of plugins, component plugins, function plugins
+and replacement plugins.
 
 React Component plugins, which can be used to:
 
@@ -33,103 +34,117 @@ Function plugins, which can be used to:
 - Modify the arguments of a function
 - Skip calling the original function conditionally
 
-## How do I write a React Component plugin?
+Replacement plugins, which can be used to:
+
+- Replace any export with your own implementation
+- Replace an internal component used by another internal component with your own
+  implementation.
+
+## How do I write a component plugin?
 
 In this example we're going to add some text to list items, just like the text
 ‘BY GC’ that can seen in the demo on
 [category pages](https://graphcommerce.vercel.app/en/women/business).
 
-1. Create a new file in `/plugins/ProductListItemByGC.tsx` with the following
-   contents:
-
-   ```tsx
-   import type { ProductListItem } from '@graphcommerce/magento-product'
-   import type { ReactPlugin } from '@graphcommerce/next-config'
-   import { Typography } from '@mui/material'
-
-   export const component = 'ProductListItem' // Component to extend, required
-   export const exported = '@graphcommerce/magento-product' // Location where the component is exported, required
-
-   const ListPlugin: ReactPlugin<typeof ProductListItem> = (props) => {
-     // Prev in this case is ProductListItem, you should be able to see this if you log it.
-     const { Prev, ...rest } = props
-     return (
-       <Prev
-         {...rest}
-         subTitle={
-           <Typography component='span' variant='caption'>
-             Plugin!
-           </Typography>
-         }
-       />
-     )
-   }
-   export const Plugin = ListPlugin // An export with the name Plugin, required
-   ```
-
-2. Trigger the 'interceptor generation' so GraphCommerce knows of the existence
-   of your plugin. To enable: Modify the page that you expect the plugin to
-   occur on. In this case modify `pages/[...url].tsx` by adding a few linebreaks
-   and save the file
-
-   If everything went as expected you should see `Plugin!` below the product
-   name. If that doesn't work try restarting the dev server.
-
-3. Happy programming!
-
-4. You can enable debug mode in your graphcommerce.config.js:
-
-   ```js
-   const config = {
-     debug: {
-       pluginStatus: true,
-     },
-   }
-   ```
+Create a new file in `/plugins/MyProductListItemPlugin.tsx` with the following
+contents:
 
-## How does it work?
+```tsx
+import type { ProductListItemProps } from '@graphcommerce/magento-product'
+import type { PluginConfig, PluginProps } from '@graphcommerce/next-config'
+import { Typography } from '@mui/material'
+
+export const config: PluginConfig = {
+  type: 'component',
+  module: '@graphcommerce/magento-product',
+}
+
+// Exported name should be the same as the function you want to create a plugin for
+export const ProductListItem = (props: PluginProps<ProductListItemProps>) => {
+  // Prev in this case is ProductListItem, you should be able to see this if you log it.
+  // Prev needs to be rendered and {...rest} always needs to be passed.
+  const { Prev, ...rest } = props
+  return (
+    <Prev
+      {...rest}
+      subTitle={
+        <Typography component='span' variant='caption'>
+          Plugin!
+        </Typography>
+      }
+    />
+  )
+}
+```
+
+## How do I write a function plugin?
+
+Create a new file in `/plugins/myFunctionPlugin.tsx` with the following
+contents:
+
+```tsx
+import type { graphqlConfig as graphqlConfigType } from '@graphcommerce/graphql'
+import type { FunctionPlugin, PluginConfig } from '@graphcommerce/next-config'
+import { createStoreLink } from '../link/createStoreLink'
+
+export const config: PluginConfig = {
+  type: 'function',
+  module: '@graphcommerce/graphql',
+}
+
+// Exported name should be the same as the function you want to create a plugin for
+export const graphqlConfig: FunctionPlugin<typeof graphqlConfigType> = (
+  prev,
+  conf,
+) => {
+  const results = prev(conf)
+  return {
+    ...results,
+    links: [...results.links, createStoreLink(conf.storefront.locale)],
+  }
+}
+```
 
-After the creation of the plugin file GraphCommerce will create an interceptor
-file to load you plugin. To see what has happened, open the
-`node_modules/@graphcommerce/magento-product/index.interceptor.tsx` and you
-should see something like:
+## How do I write a replacement plugin?
 
 ```tsx
-export * from '.'
-import { Plugin as AwesomeProductListItem } from '../../examples/magento-graphcms/plugins/AwesomeProductListItem'
-import { ComponentProps } from 'react'
-import { ProductListItem as ProductListItemBase } from '.'
-
-/**
- * Interceptor for `<ProductListItem/>` with these plugins:
- *
- * - `../../examples/magento-graphcms/plugins/AwesomeProductListItem`
- */
-type ProductListItemProps = ComponentProps<typeof ProductListItemBase>
-
-function AwesomeProductListItemInterceptor(props: ProductListItemProps) {
-  return <AwesomeProductListItem {...props} Prev={ProductListItemBase} />
+import { ProductCountProps } from '@graphcommerce/magento-product'
+import { PluginConfig } from '@graphcommerce/next-config'
+
+export const config: PluginConfig = {
+  type: 'replace',
+  module: '@graphcommerce/magento-product',
+}
+
+export function ProductListCount(props: ProductCountProps) {
+  const { total_count } = props
+  return <div>{total_count}</div>
 }
-export const ProductListItem = AwesomeProductListItemInterceptor
 ```
 
-If you read the interceptor file from the bottom up, you see:
+Note: The original component can not be used, because we completely rewrite the
+export. If you want to do this, a component or function plugin is a better
+choice.
 
-- The original `ProductListItem` is replaced with
-  `AwesomeProductListItemInterceptor`
-- `AwesomeProductListItemInterceptor` is a react component which renders
-  `AwesomeProductListItem` with a `Prev` prop.
-- `AwesomeProductListItem` is the plugin you just created.
-- `Prev` is the original `ProductListItem` (renamed to `ProductListItemBase`)
-- `ProductListItemProps` are the props of the original `ProductListItem` and
-  thus your plugin is automatically validated by TypeScript.
+## How do make sure my plugin is applied?
 
-So in conclusion, a plugin is a react component that renders the original
-component with a `Prev` prop. The `Prev` prop is the original component.
+When creating the plugin for the first time you need to restart your dev server
+once. After the first generation of the interceptor file, the file is watched
+and changes will be picked up.
 
-When opening the React debugger you can see the plugin wrapped.
+If everything went as expected you should see your plugin applied correct.
 
-<img width="263" alt="Scherm­afbeelding 2023-03-15 om 12 16 59" src="https://user-images.githubusercontent.com/1244416/225293707-1ce1cd87-108b-4f28-b9ee-0c5d68d9a886.png" />
+## How can I debug to see which plugins are applied?
+
+You can enable debug mode in your graphcommerce.config.js:
+
+```js
+const config = {
+  debug: { pluginStatus: true },
+}
+```
+
+Or use `GC_DEBUG_PLUGIN_STATUS=true` in your environment variables.
 
 ### How are plugins loaded?
 
@@ -141,33 +156,66 @@ Package locations are the root and all packages with `graphcommerce` in the name
 (This means all `@graphcommerce/*` packages and
 `@your-company/graphcommerce-plugin-name`)
 
-The Webpack plugin statically analyses the plugin file to find `component`,
-`exported` and `ifConfig` and extracts that information.
-
-### Possible use cases
+The Webpack plugin statically analyses the plugin files to find any valid
+configuration. This is then used to create the interceptors.
 
-In the examples above we've extended the product list items, but it should also
-work for other things such as:
+### Conditionally include a plugin
 
-- Googletagmanager
-- Googleanalytics
-- Google recaptcha
-- Compare functionality
-- Wishlist functionality?
-- Abstraction between GraphCommerce and Backends? (Magento, BigCommerce,
-  CommerceTools, etc.)
+Provide an ifConfig in the plugin config to conditionally include a plugin if a
+[configuration](./config.md) value is truthy:
 
-### Conditionally include a plugin
+```tsx
+export const config: PluginConfig = {
+  type: 'component',
+  module: '@graphcommerce/magento-product',
+  ifConfig: 'demoMode',
+}
+```
 
-Provide an ifConfig export in the plugin that will only include the plugin if a
-[configuration](./config.md) value is truthy.
+Or checking on a value:
 
 ```tsx
-import type { IfConfig } from '@graphcommerce/next-config'
-export const ifConfig: IfConfig = 'googleAnalytics'
+export const config: PluginConfig<'compareVariant'> = {
+  type: 'component',
+  module: '@graphcommerce/magento-product',
+  ifConfig: ['compareVariant', 'CHECKBOX'],
+}
 ```
 
 ### Plugin loading order
 
-A plugin is injected later than the dependencies of the package. So if a plugin
-is loaded to early, make sure the package has a dependency on the other package.
+The plugin loading order is determined by the order of the dependencies defined
+in the package.json. If the order isn't correct, make sure you've defined the
+correct dependencies in your package.json.
+
+Local plugins are closest to the original component, meaning that package
+specific plugins have already been called before your plugin is called.
+
+## How does it work?
+
+After the creation of the plugin file GraphCommerce will create an 'interceptor'
+for your file.
+
+To see the the created plugin for ProductListItem, '_Go to Definition_'
+(CMD/Ctrl+Click) on `<ProductListItem>` in
+`components/ProductListItems/productListRenderer.tsx`. You should now go to the
+`ProductListItem.interceptor.tsx` file.
+
+In this file the original `ProductListItem` is replaced with
+`PluginDemoProductListItemInterceptor`. The interceptor renders
+`<PluginDemoProductListItemSource />` with a `Prev` prop which is the plugin.
+
+The whole plugin 'chain' is constructed here and eventually ending up on
+`ProductListItemOriginal` which is the original component (but renamed).
+
+### Examples
+
+In the examples above we've extended the product list items, but it should also
+work for other things such as:
+
+- [Update the gallery when a configurable is selected](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/magento-product-configurable/plugins/ConfigurableProductPage/ConfigurableProductPageGallery.tsx)
+- [Insert the Google Recaptcha Script](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/googlerecaptcha/plugins/GrecaptchaGraphQLProvider.tsx)
+- [Activate Google Recaptcha when a form is loaded](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/googlerecaptcha/plugins/GrecaptchaApolloErrorSnackbar.tsx)
+- [Add a compare icon next to the cart icon](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/magento-compare/plugins/AddCompareFabNextToCart.tsx)
+- [Add a compare icon to the ProductListItem](https://github.com/graphcommerce-org/graphcommerce/blob/canary/packages/magento-compare/plugins/CompareAbleProductListItem.tsx)
+- etc.

package/framework/seo.md

@@ -35,29 +35,27 @@ Dynamic example
 />
 ```
 
-## Generate the XML sitemap
+## Robots.txt & XML sitemaps
 
-GraphCommerce uses
-[next-sitemap ↗](https://github.com/iamvishnusankar/next-sitemap) to generate
-the sitemap, which is located in the directory /public/sitemap.xml. For example,
-view the [demo sitemap.xml ↗](https://graphcommerce.vercel.app/sitemap.xml)
+GraphCommerce serves robots.txt & XML sitemap routes through the page router.
+(`pages/robots.txt.tsx` & `pages/sitemap/`)  
+By default the robots.txt allows/disallows robots based on the
+[`robotsAllow` configuration](./config.md#robotsallow-boolean) and contains a
+separate sitemap for product, category & content pages.
 
-Generating the sitemap.xml file is part of the static build process. Use
-`yarn build` to initiate the build process and to generate a new sitemap.xml
-file.
+### Multi domain setup
 
-Sitemap generation uses the
-[`canonicalBaseUrl` configuration](./config.md#canonicalbaseurl-string).
+When using a multi domain setup (e.g. https://mydomain.nl &
+https://mydomain.com) using the
+[`canonicalBaseUrl` configuration](./config.md#canonicalbaseurl-string), the
+robots.txt will only include sitemaps specific to that domain.
 
-## Modify /robots.txt
+### Multi locale setup
 
-GraphCommerce creates a /robots.txt file on build time. Its contents can be
-modified by editing /next-sitemap.js. For example, view the
-[demo robots.txt ↗](https://graphcommerce.vercel.app/robots.txt)
-
-Generating the robot.txt file is part of the static build process. Use
-`yarn build` to initiate the build process and to generate a new robots.txt
-file.
+When using a multi locale based setup (e.g.
+https://graphcommerce.vercel.app/en-gb), the robots.txt will include sitemaps
+for all locales on the global domain. Example:
+[robots.txt](https://graphcommerce.vercel.app/robots.txt)
 
 ## Next steps
 

package/framework/translations.md

@@ -158,10 +158,8 @@ msgstr "Cart ({0})"
  */
 const config = {
   i18n: [
-    {
-      locale: 'sv-fi',
-      magentoStoreCode: 'sv_FI',
-    },
+    { locale: 'sv-fi', magentoStoreCode: 'sv_FI', linguiLocale: 'sv' },
+    { locale: 'fr-be', magentoStoreCode: 'sv_FI', linguiLocale: 'fr-be' },
   ],
 }
 ```
@@ -176,6 +174,7 @@ const config = {
 ├─────────────┼─────────────┼─────────┤
 │ en (source) │     208     │    -    │
 │ sv          │     208     │   208   │
+│ fr-be       │     208     │   208   │
 └─────────────┴─────────────┴─────────┘
 ```
 

package/getting-started/create.md

@@ -64,7 +64,7 @@ Duplicate and rename the configuration example file to:
 ## Step 3: Start the app
 
 ```bash
-yarn
+touch yarn.lock && yarn
 # Install dependencies (may take a while)
 ```
 

package/magento/multi-theme-multi-website.md

@@ -0,0 +1,130 @@
+# Multiple themes/brands with multiple websites
+
+When deciding how to develop multiple themes/brands, there are several
+gradations of customizability.
+
+Deciding on how to approach this is a trade-off between the amount of
+customizability and the amount of code duplication.
+
+## Gradations of modularization/thematization
+
+### Level 1: One codebase, one build. Differences are configured in GraphCommerceStorefrontConfig
+
+- Advantage: Simple, everything is easy to configure in the config.
+- Advantage: Upgrade once
+- Disadvantage: Not tree shakable (very large differences between brands can
+  become problematic)
+
+This requires discipline from the developer that we maintain the 'Single
+responsibility' principle for components. Components that actually serve two
+completely separate functionalities depending on the brand are not desirable.
+
+Create a Config.graphqls in your graphql directory with the following contents:
+
+```graphql
+enum ThemeName {
+  BRAND_1
+  BRAND_2
+}
+
+extend input GraphCommerceStorefrontConfig {
+  themeName: ThemeName!
+}
+```
+
+Applying a different theme based on the store configuration:
+
+```tsx
+// in _app.tsx
+const { themeName } = useStorefrontConfig()
+const theme = useMemo(() => {
+  if (themeName === 'BRAND_1') {
+    const brand1Palette = ...
+    return createThemeWithPalette(brand1Palette)
+  }
+}, [domain])
+```
+
+Applying a different component based on the store configuration:
+
+```tsx
+export function MyComponent() {
+  const { themeName } = useStorefrontConfig()
+
+  if (themeName === 'BRAND_1') return <Brand1Component>
+  return <Brand2Component {...}/>
+}
+```
+
+### Level 2: One codebase, multiple builds. Differences are configured in GraphCommerceConfig
+
+- Advantage: Tree shakable
+- Advantage: Upgrade once
+- Disadvantage: Multiple builds
+- Disadvantage: Multiple deployments
+
+Create a Config.graphqls in your graphql directory with the following contents:
+
+```graphql
+enum ThemeName {
+  BRAND_1
+  BRAND_2
+}
+
+extend input GraphCommerceConfig {
+  themeName: ThemeName!
+}
+```
+
+During deploy you'd have to set the theme that is being build:
+`GC_THEME_NAME=BRAND_1`.
+
+Create a separate theme for each brand:
+
+```tsx
+let theme: Theme
+if (import.meta.graphCommerce.theme === 'BRAND_1') {
+  const brand1Palette = ...
+  theme = createThemeWithPalette(brand1Palette)
+} else if (import.meta.graphCommerce.theme === 'BRAND_2') {
+  const brand2Palette = ...
+  theme = createThemeWithPalette(brand2Palette)
+}
+theme.components = createOverrides(theme) as Components
+
+export { theme }
+```
+
+Replace/Plugin a component based on the theme:
+
+```tsx
+// plugins/BRAND_1/magento-product/Replace.tsx
+export const config: PluginConfig<'themeName'> = {
+  type: 'replace',
+  module: '@graphcommerce/magento-product',
+  ifConfig: ['themeName', 'BRAND_1'],
+}
+
+export function ProductListItem(props: ProductListItemProps) {
+  //...
+}
+```
+
+Now when a new brand is added you can copy-paste the BRAND_1 directory and you
+should be able to modify the components to your liking.
+
+<!--
+### Level 3: Monorepo with one graphcommerce instance, but a separate generic package per brand.
+
+- Advantage: Tree shakable
+- Advantage: Full flexibility
+- Disadvantage: Files are copied per brand.
+- Disadvantage: Upgrades are duplicated
+- Disadvantage: Projects diverge quickly and become hard to maintain.
+
+This requires you to modify all imports of the examples directory, thus making
+upgrades more difficult. GraphCommerce does not offer a flexible solution for
+this.
+
+To achieve this we could: Offer a way to also handle `export * from 'my-brand'`
+in plugins. -->

package/package.json

@@ -2,10 +2,10 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "8.0.6-canary.3",
+  "version": "8.1.0-canary.10",
   "sideEffects": true,
   "peerDependencies": {
-    "@graphcommerce/prettier-config-pwa": "^8.0.6-canary.3"
+    "@graphcommerce/prettier-config-pwa": "^8.1.0-canary.10"
   },
   "prettier": "@graphcommerce/prettier-config-pwa"
 }

package/upgrading/graphcommerce-8-to-9.md

@@ -0,0 +1,54 @@
+# Upgrading from GraphCommerce 8 to 9
+
+Depending on the amounts of customisations you've made, there are some manual
+steps. Please follow the regular [upgrade steps first](./readme.md).
+
+1. ReactPlugin TypeScript definition is removed.
+2. Locales now require an explicit configuration.
+
+## 1. ReactPlugin TypeScript definition is removed
+
+The `ReactPlugin` TypeScript definition has been removed and only `PluginProps`
+is available.
+
+Replace
+
+```tsx
+const MyPlugin: ReactPlugin<typeof OriginalComponent> = (props) => {
+  const { Prev, ...rest } = props
+  return <Prev {...rest} />
+}
+export const Plugin = MyPlugin
+```
+
+Now becomes:
+
+```tsx
+const MyPlugin = (props: PluginProps<OriginalComponentProps>) => {
+  const { Prev, ...rest } = props
+  return <Prev {...rest} />
+}
+export const Plugin = MyPlugin
+```
+
+There is a new plugin configuration method by using
+`export config: PluginConfig = {}`.
+
+2. linguiLocale now requires an explicit configuration where they differ from
+   the locale
+
+> linguiLocale: Custom locale used to load the .po files. Must be a valid
+> locale, also used for Intl functions.
+
+In the example below, the linguiLocale is not required for `en` as `en.po`
+exits, but it is required for `fr-be` as only `fr.po` exists. This thus also
+allows you to create `fr-be.po` and use that.
+
+```js
+const config = {
+  storefront: [
+    { locale: 'en', magentoStoreCode: 'en_US', defaultLocale: true },
+    { locale: 'fr-be', magentoStoreCode: 'nl_NL', linguiLocale: 'fr' },
+  ],
+}
+```