@graphcommerce/docs 6.0.0-canary.26 → 6.0.0-canary.28

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## 6.0.0-canary.28
+
+### Patch Changes
+
+- [#1823](https://github.com/graphcommerce-org/graphcommerce/pull/1823) [`605d74434`](https://github.com/graphcommerce-org/graphcommerce/commit/605d74434b78baa83f3574b6a4249eae0431d570) - Fix/upgrade instructions ([@paales](https://github.com/paales))
+
+## 6.0.0-canary.27
+
 ## 6.0.0-canary.26
 
 ## 6.0.0-canary.25

package/framework/config.md

@@ -1,9 +1,79 @@
-<!-- auto generated -->
-## GraphCommerceConfig
+<!-- Automatically generated from Config.graphqls -->
+# GraphCommerce configuration system
 
-Global GraphCommerce configuration can be configured in your `graphcommerce.config.js` file in the root of your project.
+Global GraphCommerce configuration can be configured in your `graphcommerce.config.js` file
+in the root of your project and are automatically validated on startup.
 
-### `canonicalBaseUrl: String!`
+## Configuring with the configuration file.
+
+The configuration file is a javascript file that exports a `GraphCommerceConfig` object. See graphcommerce.config.js.example for an example.
+
+## Using configuration
+
+Configuration can be accessed in your project with the `import.meta.graphCommerce` object.
+
+```tsx
+import { i18nAll, i18nConfig, i18nConfigDefault, useI18nConfig } from '@graphcommerce/next-ui'
+
+// Accessing a global value
+const globalConf = import.meta.graphCommerce.cartDisplayPricesInclTax
+
+function MyComponent() {
+  // Configuration configured per i18n locale.
+  const scopedConfig = useI18nConfig().cartDisplayPricesInclTax
+
+  // Creating a fallback system
+  const scopedConfigWithFallback = scopedConfig ?? globalConf
+
+  // Or as single line
+  const scopedConfigWithFallback2 =
+    useI18nConfig().cartDisplayPricesInclTax ?? import.meta.graphCommerce.cartDisplayPricesInclTax
+
+  return <div>{googleRecaptchaKey}</div>
+}
+```
+
+## Environment variables to override configuration
+
+Configuration values can be overwriten by environment variables, with the following rules:
+- Convert from camelCase to `SCREAMING_SNAKE_CASE`
+- Prefix with `GC_`
+- Arrays can be indexed with _0, _1, _2, etc.
+- Objects can be accessed with _<key>.
+
+Examples:
+- `limitSsg` -> `GC_LIMIT_SSG="1"`
+- `i18n[0].locale` -> `GC_I18N_0_LOCALE="en"`
+- `debug.pluginStatus` -> `GC_DEBUG_PLUGIN_STATUS="1"`
+
+
+## Extending the configuration in your  project
+
+Create a graphql/Config.graphqls file in your project and extend the GraphCommerceConfig, GraphCommerceI18nConfig inputs to add configuration.
+
+```graphql
+extend input GraphCommerceConfig {
+  myOptionalBoolean: Boolean
+  myRequiredBoolean: Boolean!
+  myOptionalString: String
+  myRequiredString: String!
+  myOptionalInt: Int
+  myRequiredInt: Int!
+  myOptionalFloat: Float
+  myRequiredFloat: Float!
+}
+extend input GraphCommerceI18nConfig {
+  myField: Boolean
+}
+```
+
+## All configuration values
+
+Below is a list of all possible configurations that can be set by GraphCommerce.
+
+### GraphCommerceConfig
+
+#### `canonicalBaseUrl: String!`
 
 The canonical base URL is used for SEO purposes.
 
@@ -12,47 +82,30 @@ Examples:
 - https://example.com/en
 - https://example.com/en-US
 
-### `hygraphEndpoint: String!`
+#### `hygraphEndpoint: String!`
 
 The HyGraph endpoint.
 
 Project settings -> API Access -> High Performance Read-only Content API
 
-### `i18n: [GraphCommerceI18nConfig!]!`
+#### `i18n: [[GraphCommerceI18nConfig](#GraphCommerceI18nConfig)!]!`
 
 All i18n configuration for the project
 
-### `magentoEndpoint: String!`
+#### `magentoEndpoint: String!`
 
 GraphQL Magento endpoint.
 
 Examples:
 - https://magento2.test/graphql
 
-### `productFiltersPro: Boolean!`
-
-Product filters with better UI for mobile and desktop.
-
-@experimental This is an experimental feature and may change in the future.
-
-### `robotsAllow: Boolean!`
-
-Allow the site to be indexed by search engines.
-If false, the robots.txt file will be set to disallow all.
-
-### `singleProductRoute: Boolean!`
-
-On older versions of GraphCommerce products would use a product type specific route.
-
-This should only be set to false if you use the /product/[url] or /product/configurable/[url] routes.
-
-### `cartDisplayPricesInclTax: Boolean`
+#### `cartDisplayPricesInclTax: Boolean`
 
 Due to a limitation of the GraphQL API it is not possible to determine if a cart should be displayed including or excluding tax.
 
 When Magento's StoreConfig adds this value, this can be replaced.
 
-### `customerRequireEmailConfirmation: Boolean`
+#### `customerRequireEmailConfirmation: Boolean`
 
 Due to a limitation in the GraphQL API of Magento 2, we need to know if the
 customer requires email confirmation.
@@ -60,11 +113,11 @@ customer requires email confirmation.
 This value should match Magento 2's configuration value for
 `customer/create_account/confirm` and should be removed once we can query
 
-### `debug: GraphCommerceDebugConfig`
+#### `debug: [GraphCommerceDebugConfig](#GraphCommerceDebugConfig)`
 
 Debug configuration for GraphCommerce
 
-### `demoMode: Boolean`
+#### `demoMode: Boolean`
 
 Enables some demo specific code that is probably not useful for a project:
 
@@ -72,7 +125,7 @@ Enables some demo specific code that is probably not useful for a project:
 - Adds "dominant_color" attribute swatches to the product list items.
 - Creates a big list items in the product list.
 
-### `googleAnalyticsId: String`
+#### `googleAnalyticsId: String`
 
 See https://support.google.com/analytics/answer/9539598?hl=en
 
@@ -80,50 +133,67 @@ Provide a value to enable Google Analytics for your store.
 
 To enable only for a specific locale, override the value in the i18n config.
 
-### `googleRecaptchaKey: String`
+#### `googleRecaptchaKey: String`
 
 Google reCAPTCHA key, get from https://developers.google.com/recaptcha/docs/v3
 
 This value is required even if you are configuring different values for each locale.
 
-### `googleTagmanagerId: String`
+#### `googleTagmanagerId: String`
 
 The Google Tagmanager ID to be used on the site.
 
 This value is required even if you are configuring different values for each locale.
 
-### `limitSsg: Boolean`
+#### `legacyProductRoute: Boolean`
+
+On older versions of GraphCommerce products would use a product type specific route.
+
+This should only be set to true if you use the /product/[url] AND /product/configurable/[url] routes.
+
+#### `limitSsg: Boolean`
 
 Limit the static generation of SSG when building
 
-### `previewSecret: String`
+#### `previewSecret: String`
 
 To enable next.js' preview mode, configure the secret you'd like to use.
 
-### `wishlistHideForGuests: Boolean`
+#### `productFiltersPro: Boolean`
+
+Product filters with better UI for mobile and desktop.
+
+@experimental This is an experimental feature and may change in the future.
+
+#### `robotsAllow: Boolean`
+
+Allow the site to be indexed by search engines.
+If false, the robots.txt file will be set to disallow all.
+
+#### `wishlistHideForGuests: Boolean`
 
 Hide the wishlist functionality for guests.
 
-### `wishlistIgnoreProductWishlistStatus: Boolean`
+#### `wishlistIgnoreProductWishlistStatus: Boolean`
 
 Ignores wether a product is already in the wishlist, makes the toggle an add only.
 
-## GraphCommerceDebugConfig
+### GraphCommerceDebugConfig
 
 Debug configuration for GraphCommerce
 
-### `pluginStatus: Boolean`
+#### `pluginStatus: Boolean`
 
 Reports which plugins are enabled or disabled.
 
-### `webpackCircularDependencyPlugin: Boolean`
+#### `webpackCircularDependencyPlugin: Boolean`
 
 Cyclic dependencies can cause memory issues and other strange bugs.
 This plugin will warn you when it detects a cyclic dependency.
 
 When running into memory issues, it can be useful to enable this plugin.
 
-### `webpackDuplicatesPlugin: Boolean`
+#### `webpackDuplicatesPlugin: Boolean`
 
 When updating packages it can happen that the same package is included with different versions in the same project.
 
@@ -131,15 +201,15 @@ Issues that this can cause are:
 - The same package is included multiple times in the bundle, increasing the bundle size.
 - The Typescript types of the package are not compatible with each other, causing Typescript errors.
 
-## GraphCommerceI18nConfig
+### GraphCommerceI18nConfig
 
 All i18n configuration for the project
 
-### `locale: String!`
+#### `locale: String!`
 
 Must be a locale string https://www.unicode.org/reports/tr35/tr35-59/tr35.html#Identifiers
 
-### `magentoStoreCode: String!`
+#### `magentoStoreCode: String!`
 
 Magento store code.
 
@@ -150,7 +220,7 @@ Examples:
 - en-us
 - b2b-us
 
-### `canonicalBaseUrl: String`
+#### `canonicalBaseUrl: String`
 
 The canonical base URL is used for SEO purposes.
 
@@ -159,38 +229,38 @@ Examples:
 - https://example.com/en
 - https://example.com/en-US
 
-### `cartDisplayPricesInclTax: Boolean`
+#### `cartDisplayPricesInclTax: Boolean`
 
 Due to a limitation of the GraphQL API it is not possible to determine if a cart should be displayed including or excluding tax.
 
-### `defaultLocale: Boolean`
+#### `defaultLocale: Boolean`
 
 There can only be one entry with defaultLocale set to true.
 - If there are more, the first one is used.
 - If there is none, the first entry is used.
 
-### `domain: String`
+#### `domain: String`
 
 Domain configuration, must be a domain https://tools.ietf.org/html/rfc3986
 
-### `googleAnalyticsId: String`
+#### `googleAnalyticsId: String`
 
 Configure different Google Analytics IDs for different locales.
 
 To disable for a specific locale, set the value to null.
 
-### `googleRecaptchaKey: String`
+#### `googleRecaptchaKey: String`
 
 Locale specific google reCAPTCHA key.
 
-### `googleTagmanagerId: String`
+#### `googleTagmanagerId: String`
 
 The Google Tagmanager ID to be used per locale.
 
-### `hygraphLocales: [String!]`
+#### `hygraphLocales: [String!]`
 
 Add a gcms-locales header to make sure queries return in a certain language, can be an array to define fallbacks.
 
-### `linguiLocale: String`
+#### `linguiLocale: String`
 
 Specify a custom locale for to load translations.

package/framework/links.md

@@ -36,8 +36,8 @@ If you want to use props of next/link and satisfy typescript you need to provide
 `component={NextLink}`.
 
 ```tsx
-import { Link } from '@mui/material'
 import { NextLink } from '@graphcommerce/next-ui'
+import { Link } from '@mui/material'
 
 function MyComponent() {
   return (
@@ -51,72 +51,14 @@ function MyComponent() {
 ### Using next/link with a custom component
 
 ```tsx
-import { Chip } from '@mui/material'
 import { NextLink } from '@graphcommerce/next-ui'
+import { Chip } from '@mui/material'
 
 function MyComponent() {
   return <Chip component={NextLink} href={`/${url}`} label={'my label'} />
 }
 ```
 
-## Upgrading from Next.js 12
-
-Before Next.js 13, the next/link component needed to wrap a Material-UI Link
-component;
-
-```tsx
-import PageLink from 'next/link'
-import { Link } from '@mui/material'
-
-function MyComponent() {
-  return (
-    <PageLink href='/about' passHref>
-      <Link>About</Link>
-    </PageLink>
-  )
-}
-```
-
-To upgrade this component to Next.js 13, you can remove the PageLink component.
-
-```tsx
-import { Link } from '@mui/material'
-
-function MyComponent() {
-  return <Link href='/about'>About</Link>
-}
-```
-
-### Upgrading a Link that uses next/link props
-
-```tsx
-import PageLink from 'next/link'
-import { Link } from '@mui/material'
-
-function MyComponent() {
-  return (
-    <PageLink href='/about' passHref prefetch={false}>
-      <Link>Link without prefetch</Link>
-    </PageLink>
-  )
-}
-```
-
-```tsx
-import { Link } from '@mui/material'
-import { NextLink } from '@graphcommerce/next-ui'
-
-function MyComponent() {
-  return (
-    <>
-      <Link href='/about' component={NextLink} prefetch={false}>
-        Link without prefetch
-      </Link>
-    </>
-  )
-}
-```
-
 ## Further reading
 
 -

package/framework/patch-package.md

@@ -0,0 +1,28 @@
+# Patch package
+
+GraphCommerce relies on [patch-package ↗](https://github.com/ds300/patch-package) to make modifications to GraphCommerce where there are no ways to modify through props or plugins.
+
+`yarn create-patch @graphcommerce/magento-store`
+
+## Benefits of patching over copying a file to local
+
+- Get told in big red letters when the original file is changed and you need to check that your fix is still valid.
+- Patches can be reviewed as part of your normal review process, local changes will slip though the cracks.
+
+## When to make a local copy of a file
+
+- The change is too consequential to be modified in place.
+
+## Isn't this dangerous?
+
+Nope. The technique is quite robust. Here are some things to keep in mind though:
+
+- It's easy to forget to run yarn or npm when switching between branches that do and don't have patch files.
+- Long lived patches can be costly to maintain if they affect an area of code that is updated regularly and you want to update the package regularly too.
+- Big semantic changes can be hard to review. Keep them small and obvious or add plenty of comments.
+- Changes can also impact the behaviour of other untouched packages. It's normally obvious when this will happen, and often desired, but be careful nonetheless.
+
+## How to make a patch
+
+1. Make your changes to the file in node_modules.
+2. Run `yarn create-patch @graphcommerce/magento-store` to create a patch file.

package/package.json

@@ -2,10 +2,10 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "6.0.0-canary.26",
+  "version": "6.0.0-canary.28",
   "sideEffects": true,
   "devDependencies": {
-    "@graphcommerce/prettier-config-pwa": "6.0.0-canary.26"
+    "@graphcommerce/prettier-config-pwa": "6.0.0-canary.28"
   },
   "prettier": "@graphcommerce/prettier-config-pwa"
 }

package/upgrading/graphcommerce-5-to-6.md

@@ -0,0 +1,135 @@
+# Upgrading from GraphCommerce 5 to 6
+
+Upgrading from GraphCommerce 5 to 6 is a major upgrade. Please follow the
+regular [upgrade steps first](./readme.md).
+
+## Replace next/link with GraphCommerce's new Link behavior
+
+Before GraphCommerce 6 (before Next.js 13), the next/link component needed to
+wrap a Material-UI Link component; With GraphCommerce 6 we've integrated Next.js
+13's new Link behavior, see [links documentation](../framework/links.md).
+
+```tsx
+import PageLink from 'next/link'
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <PageLink href='/about' passHref>
+      <Link>About</Link>
+    </PageLink>
+  )
+}
+```
+
+To upgrade this component to Next.js 13, you can remove the PageLink component.
+
+```tsx
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return <Link href='/about'>About</Link>
+}
+```
+
+### Upgrading a Link that uses next/link props
+
+```tsx
+import PageLink from 'next/link'
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <PageLink href='/about' passHref prefetch={false}>
+      <Link>Link without prefetch</Link>
+    </PageLink>
+  )
+}
+```
+
+```tsx
+import { NextLink } from '@graphcommerce/next-ui'
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <Link href='/about' component={NextLink} prefetch={false}>
+      Link without prefetch
+    </Link>
+  )
+}
+```
+
+### Upgrading a Button that uses component='a'
+
+```tsx
+import PageLink from 'next/link'
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <PageLink href='/about' passHref>
+      <Button component='a'>Link with component='a'</Link>
+    </PageLink>
+  )
+}
+```
+
+```tsx
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <Button href='/about' prefetch={false}>
+      component='a' isn't needed
+    </Button>
+  )
+}
+```
+
+Note: If there is a case where this is required, make sure you use
+`component={NextLink}` instead of `component='a'`. A global search through the
+codebase will show you where this is used.
+
+```tsx
+import { NextLink } from '@graphcommerce/next-ui'
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <Button href='/about' component={NextLink} prefetch={false}>
+      component='a' isn't needed
+    </Button>
+  )
+}
+```
+
+## Upgrading a non button components like Chip, Box, etc.
+
+```tsx
+import PageLink from 'next/link'
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <PageLink href='/about' passHref>
+      <Chip>Chip</Link>
+    </PageLink>
+  )
+}
+```
+
+```tsx
+import { NextLink } from '@graphcommerce/next-ui'
+import { Link } from '@mui/material'
+
+function MyComponent() {
+  return (
+    <Chip href="/about" component={NextLink}>Chip</Link>
+  )
+}
+```
+
+## Further reading
+
+- [Upgrading](./readme.md)

package/{upgrading.md → upgrading/readme.md}

@@ -100,7 +100,11 @@ you commit, make sure to delete all the .rej files:
 find . -type f -name '*.rej' -delete
 ```
 
-After resolving the diff issues, run and validate your local environment:
+After resolving the diff issues, manually process upgrade instructions:
+
+- [Upgrading to GraphCommerce 5 to 6](./graphcommerce-5-to-6.md)
+
+Run and validate your local environment:
 
 - `yarn codegen` should run without errors
 - `yarn tsc:lint` should run without errors