@graphcommerce/docs 4.12.0-canary.2 → 4.12.0-canary.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## 4.12.0-canary.4
+
+### Patch Changes
+
+- [`9c3047c2f`](https://github.com/graphcommerce-org/graphcommerce/commit/9c3047c2fc6ea11ef9bd0c5128af883bffccc7e5) - Added GraphQL Injectable documentation ([@paales](https://github.com/paales))
+
+## 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

package/framework/plugins-graphql.md

@@ -0,0 +1,74 @@
+# Plugins GraphQL
+
+GraphCommerce's GraphQL plugin system allows you to extend GraphCommerce in a
+plug-and-play manner. Install a new package and the queries will be exdtended at
+the right places.
+
+## What problem are we solving?
+
+Without plugins it becomes complex to extend GraphQL queries and you'd probably
+need to overfetch in lots of places by doing additional queries.
+
+For example, to render additional attributes on the product listing, it was
+necessary to modify a GraphQL query and know all the points the query is used.
+
+The query below is inside the
+[@graphcomemrce/magento-product](https://github.com/graphcommerce-org/graphcommerce/blob/main/packages/magento-product/components/ProductList/ProductList.graphql)
+package and therefor it is not possible to modify:
+
+```graphql
+query ProductList(
+  $pageSize: Int = 24
+  $currentPage: Int = 1
+  $filters: ProductAttributeFilterInput = {}
+  $sort: ProductAttributeSortInput = {}
+  $search: String = ""
+) {
+  products(
+    pageSize: $pageSize
+    currentPage: $currentPage
+    filter: $filters
+    sort: $sort
+    search: $search
+  ) {
+    # Simplified from the original query
+    items {
+      __typename
+      uid
+      ...ProductListItem
+    }
+  }
+}
+
+# Fragment used for a ProductListItem used when rendering any listing
+fragment ProductListItem on ProductInterface @injectable {
+  uid
+  ...ProductLink
+  sku
+  name
+  small_image {
+    ...ProductImage
+  }
+  price_range {
+    minimum_price {
+      ...ProductListPrice
+    }
+  }
+}
+```
+
+## How to modify an existing query?
+
+Some Fragments inside GraphCommerce have been marked as `@injectable` which
+allows you to inject our own fields in the fragments.
+
+```graphql
+fragment MyCustomFragment on ProductInterface
+@inject(into: ["ProductListItem"]) {
+  my_custom_attribute
+}
+```
+
+This will add the field to the `ProductListItem` fragment. After codegen has
+been ran you will see that `my_custom_attribute` is also now present in
+`ProductListItem.gql.ts` and `ProductList.gql.ts`.

package/framework/{plugins.md → plugins-react.md}

@@ -1,6 +1,6 @@
-# Plugins
+# Plugins React
 
-GraphCommerce plugin system allows you to extend GraphCommerce in a
+GraphCommerce's React plugin system allows you to extend GraphCommerce in a
 plug-and-play manner. Install a new package and the code will be added at the
 right places.
 
@@ -169,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.2",
+  "version": "4.12.0-canary.4",
   "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