@graphcommerce/docs 4.12.0-canary.1 → 4.12.0-canary.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## 4.12.0-canary.3
+
+### Patch Changes
+
+- [#1738](https://github.com/graphcommerce-org/graphcommerce/pull/1738) [`163be59f2`](https://github.com/graphcommerce-org/graphcommerce/commit/163be59f2bf0f1573e91da036e56455262c6abd5) - Better clone instructions when upgrading ([@paales](https://github.com/paales))
+
+- [#1738](https://github.com/graphcommerce-org/graphcommerce/pull/1738) [`6171ad02c`](https://github.com/graphcommerce-org/graphcommerce/commit/6171ad02c19782b1e1f0eb00ea25ea6b764250b5) - Added topological sorting to plugins and added ifEnv export to plugins to conditionally load plugins ([@paales](https://github.com/paales))
+
+## 4.12.0-canary.2
+
+### Patch Changes
+
+- [#1733](https://github.com/graphcommerce-org/graphcommerce/pull/1733) [`b2d73c726`](https://github.com/graphcommerce-org/graphcommerce/commit/b2d73c726fa123435fa6c54b4e0fd0db2df7c4ab) - Move to <Prev/> instead of <Component/> to call the plugin component ([@paales](https://github.com/paales))
+
 ## 4.12.0-canary.1
 
 ### Minor Changes

package/framework/plugins.md

@@ -74,11 +74,11 @@ export const exported = '@graphcommerce/magento-cart-payment-method'
 function AddPaymentMethodEnhancer(
   props: PluginProps<PaymentMethodContextProviderProps>,
 ) {
-  const { Component, modules, ...rest } = props
-  return <Component {...rest} modules={{ ...modules, purchaseorder }} />
+  const { Prev, modules, ...rest } = props
+  return <Prev {...rest} modules={{ ...modules, purchaseorder }} />
 }
 
-/** The export must be named `Plugin` and must accept a Component to render */
+/** The export must be named `Plugin` and must accept a Prev component to render */
 export const Plugin = AddIncludedMethods
 ```
 
@@ -97,37 +97,59 @@ export const Plugin = AddIncludedMethods
 Example of generated interceptor with additional comments:
 
 ```tsx
-// All plugins are imported, which will be used to enhance the original component.
-import { Plugin as AddIncludedMethods } from '@graphcommerce/magento-payment-included/plugins/AddIncludedMethods'
-import { Plugin as AddPaypalMethods } from '@graphcommerce/magento-payment-paypal/plugins/AddPaypalMethods'
-
-// This file is placed next to the original component, so it is imported with a relative path, in the Webpack plugin we
-// load the original file if it is loaded from the interceptor.
-import { PaymentMethodContextProvider as PaymentMethodContextProviderBase } from './PaymentMethodContext'
-
-// All original exports are exported, if the original file exports more than we're intercepting, it will still work.
-export * from './PaymentMethodContext'
+/* This file is automatically generated for @graphcommerce/magento-cart-payment-method */
 
-type PaymentMethodContextProviderBaseProps = React.ComponentProps<
+export * from '.'
+import { Plugin as GaPaymentMethodButton } from '@graphcommerce/googleanalytics/plugins/GaPaymentMethodButton'
+import { Plugin as GaPaymentMethodContextProvider } from '@graphcommerce/googleanalytics/plugins/GaPaymentMethodContextProvider'
+import { Plugin as AddIncludedMethods } from '@graphcommerce/magento-payment-included/plugins/AddIncludedMethods'
+import { ComponentProps } from 'react'
+import {
+  PaymentMethodButton as PaymentMethodButtonBase,
+  PaymentMethodContextProvider as PaymentMethodContextProviderBase,
+} from '.'
+
+/**
+ * Interceptor for `<PaymentMethodButton/>` with these plugins:
+ *
+ * - `@graphcommerce/googleanalytics/plugins/GaPaymentMethodButton`
+ */
+type PaymentMethodButtonProps = ComponentProps<typeof PaymentMethodButtonBase>
+
+function GaPaymentMethodButtonInterceptor(props: PaymentMethodButtonProps) {
+  return <GaPaymentMethodButton {...props} Prev={PaymentMethodButtonBase} />
+}
+export const PaymentMethodButton = GaPaymentMethodButtonInterceptor
+
+/**
+ * Interceptor for `<PaymentMethodContextProvider/>` with these plugins:
+ *
+ * - `@graphcommerce/magento-payment-included/plugins/AddIncludedMethods`
+ * - `@graphcommerce/googleanalytics/plugins/GaPaymentMethodContextProvider`
+ */
+type PaymentMethodContextProviderProps = ComponentProps<
   typeof PaymentMethodContextProviderBase
 >
 
-// We create new Interceptor components here, which allows us to wrap multiple plugins around the original component.
-const AddIncludedMethodsInterceptor = (
-  props: PaymentMethodContextProviderBaseProps,
-) => (
-  //For the first plugin we use the original component.
-  <AddIncludedMethods {...props} Component={PaymentMethodContextProviderBase} />
-)
-const AddPaypalMethodsInterceptor = (
-  props: PaymentMethodContextProviderBaseProps,
-) => (
-  // For the next components we use the previous Interceptor component.
-  <AddPaypalMethods {...props} Component={AddIncludedMethodsInterceptor} />
-)
-
-// Finally we return the resulting interceptor component.
-export const PaymentMethodContextProvider = AddPaypalMethodsInterceptor
+function AddIncludedMethodsInterceptor(
+  props: PaymentMethodContextProviderProps,
+) {
+  return (
+    <AddIncludedMethods {...props} Prev={PaymentMethodContextProviderBase} />
+  )
+}
+function GaPaymentMethodContextProviderInterceptor(
+  props: PaymentMethodContextProviderProps,
+) {
+  return (
+    <GaPaymentMethodContextProvider
+      {...props}
+      Prev={AddIncludedMethodsInterceptor}
+    />
+  )
+}
+export const PaymentMethodContextProvider =
+  GaPaymentMethodContextProviderInterceptor
 ```
 
 React profile will show that all components are nested:
@@ -147,28 +169,21 @@ work for other things such as:
 - Abstraction between GraphCommerce and Backends? (Magento, BigCommerce,
   CommerceTools, etc.)
 
-### Limitations
+### Conditionally include a plugin
 
-Work is planned to lift these limitations, but for now:
+Provide an ifEnv export in the plugin that will only include the plugin if the
+environment variable is set.
 
-React Refresh doesn't work correctly with Plugins, it will force a page reload
-on each file change and will throw an error in the console. To solve this issue,
-move your actual plugin outside of the plugin file and only have the plugin be a
-configuration file.
+```tsx
+export const ifEnv = 'MY_ENV_VARIABLE'
+```
 
-It currently isn't possible to provide a plugin sort order. The project root is
-intercepting last, followed by the packages in reverse alphabetical order,
-followed by dependencies' dependencies. We don't generate a proper graph at the
-moment to figure out the actual dependencies but is an artifact of how we
-resolve the dependencies.
+### When to use a plugin?
 
-There currently isn't a way for the plugin to determine if the plugin should be
-activated at all. For example, the code for Google Analytics should only be
-added if the user has configured it. This is currently not possible. Of if a
-user wants to disable a plugin, this is currently not possible.
+A plugin should be used when a new package is created that influences the
+behavior of other packages.
 
-It is currently is only possible to extend React Components. This however sets
-the foundation to allow for a more flexible plugin system in the future.
+### Plugin loading order
 
-Plugins should be optional for GraphCommerce to function properly. Plugins for
-mandatory packages shouldn't exist.
+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.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "4.12.0-canary.1",
+  "version": "4.12.0-canary.3",
   "sideEffects": true,
   "devDependencies": {
     "@graphcommerce/prettier-config-pwa": "^4.0.7"

package/upgrading.md

@@ -38,7 +38,7 @@ dependencies, while keeping your customizations.
 2. Download a fresh copy of the repository:
 
    ```bash
-   git clone git@github.com:graphcommerce-org/graphcommerce.git upgrade
+   git clone -b main --depth 1 https://github.com/graphcommerce-org/graphcommerce.git
    ```
 
 3. Navigate to the /upgrade directory you've just created. Run the following