From aca2017cfdcebdfe360c66dc7513a901429bae68 Mon Sep 17 00:00:00 2001 From: Pierre Martin Date: Mon, 25 Mar 2019 19:53:51 +0100 Subject: [PATCH 1/3] Document remote schema support for GraphQL modules --- _config.yml | 1 + .../docs/advanced/graphql/remote-schemas.md | 191 ++++++++++++++++++ .../reference/graphql-module-definition.md | 49 +++++ 3 files changed, 241 insertions(+) create mode 100644 source/docs/advanced/graphql/remote-schemas.md diff --git a/_config.yml b/_config.yml index b2b1f47f..cf355ec4 100755 --- a/_config.yml +++ b/_config.yml @@ -23,6 +23,7 @@ sidebar_categories: - docs/advanced/graphql/overview - docs/advanced/graphql/meta-modules - docs/advanced/graphql/slim-down-resolvers-with-loaders + - docs/advanced/graphql/remote-schemas Checkout: - docs/advanced/checkout/overview - docs/advanced/checkout/add-custom-checkout-step diff --git a/source/docs/advanced/graphql/remote-schemas.md b/source/docs/advanced/graphql/remote-schemas.md new file mode 100644 index 00000000..f3a22895 --- /dev/null +++ b/source/docs/advanced/graphql/remote-schemas.md @@ -0,0 +1,191 @@ +--- +id: remote-schemas +title: Remote schemas +--- + +If you already have existing headless services exposing a GraphQL API, you might want to reuse them with the lowest possible overhead. + +Here are some use cases: + +- use GraphQL headless CMS such as [GraphCMS](https://graphcms.com) or [Strapi](https://strapi.io) without any overhead +- use Magento2 GraphQL endpoint _as-is_ (useful for unsupported features or custom extensions) +- develop and deploy your microservices using another technology, and expose its GraphQL API in your Front-Commerce GraphQL schema +- … many more! + +In Front-Commerce, GraphQL modules can declare their own local schema but they can also reuse remote schemas and make them available in the GraphQL schema. +This is referred to as **remote schema stitching**. + +This page explain how you could expose remote GraphQL schemas as part as your Front-Commerce GraphQL schema. + +
+ _This feature has been added in version `1.0.0-alpha.2`_ +
+ +## Exposing an entire remote schema + +The simplest use case is to entire the whole remote schema in your existing application. + +In this example, we are going to illustrate this feature by exposing the [Pokemon GraphQL API](https://graphql-pokemon.now.sh/) in our eCommerce application… you may find it useful if you are selling Pokemon related goodies! :-) + +First, let’s start by creating a new GraphQL module and register it in our application: + +```js +// my-module/server/modules/pokemon/index.js +module.exports = { + namespace: "Pokemon" +}; +``` + +```diff +// .front-commerce.js +module.exports = { + name: "Front-Commerce", + url: "https://www.front-commerce.test", + modules: [], + serverModules: [ + { name: "FrontCommerceCore", path: "server/modules/front-commerce-core" }, +- { name: "Magento2", path: "server/modules/magento2" } ++ { name: "Magento2", path: "server/modules/magento2" }, ++ { name: "Pokemon", path: "./my-module/server/modules/pokemon" } + ] +}; +``` + +
+ If you need more details about the steps above, you can read the [Extend the GraphQL schema](/docs/essentials/extend-the-graphql-schema.html) documentation page. +
+ +In its current state, this GraphQL module does nothing at all! +Let’s update it to expose the remote GraphQL schema, by adding a [`remoteSchema`](/docs/reference/graphql-module-definition.html#remoteSchema-optional) key to the module definition. + + +```diff +// my-module/server/modules/pokemon/index.js +module.exports = { +- namespace: "Pokemon" ++ namespace: "Pokemon", ++ remoteSchema: { ++ uri: "https://graphql-pokemon.now.sh/" ++ } +}; +``` + +**Restart your application** and explore your schema using the GraphQL playground (by default at +[http://localhost:4000/playground](http://localhost:4000/playground)). + +You must see several new top level queries prefixed by `Pokemon_`. +**Congratulations!** You now have access to all the Pokemon remote GraphQL queries and mutations in your Front-Commerce application, alongside your existing eCommerce ones. + +Try the query below for instance: + +```graphql +{ + Pokemon_pokemon(name:"raichu"){ + name + weight { minimum maximum } + image + classification + } + + product(sku:"VD11") { + name + } +} +``` + +## Default transforms + +You may have noticed in the previous example, that the `pokemon` query was named `Pokemon_pokemon`. +The reason is that Front-Commerce applies some transforms to the remote schema before merging it into the local schema. +The goal is to allow to quickly merge remote schemas by reducing the probability of a conflict. + +Here are the transforms applied to the remote schema by default. + +### Prefix root queries and mutations + +Root queries and mutations are prefixed with the GraphQL module namespace and an underscore. +In the example above, the remote query `pokemon(name: String!)` was renamed into `Pokemon_pokemon(name: String!)`. +If we renamed the module’s namespace in `MyPokedex` the query would be `MyPokedex_pokemon(name: String!)`. + +
+ **Important:** _special_ characters are stripped from the module namespace to obtain a valid name. + Example: for a module namespaced `Acme/Foo`, Front-Commerce will use `AcmeFoo_` as a prefix. +
+ +### Prefix types + +In a similar way, types from the remote schema are prefixed with the GraphQL module namespace and an underscore. + +In the Pokemon example above schema, the `PokemonDimension` type would be renamed to `Pokemon_PokemonDimension`. + +## Apply custom transforms + +When doing remote schema stitching, you may want to apply your own transforms to the remote schema. + +For instance, you may want to only expose the `pokemons` query from the remote schema. +Here is how you could achieve it thanks to Front-Commerce’s [`remoteSchema.transforms` GraphQL module definition key](/docs/reference/graphql-module-definition.html#transforms-optional): + +```diff ++ const { FilterRootFields } = require("graphql-tools"); ++ +module.exports = { + namespace: "Pokemon", + remoteSchema: { +- uri: "https://graphql-pokemon.now.sh/" ++ uri: "https://graphql-pokemon.now.sh/", ++ transforms: [ ++ new FilterRootFields( ++ (operation, rootField) => ++ operation === "Query" && rootField === "pokemons" ++ ) ++ ] + } +}; +``` + +
+ Please note that these transforms are applied **before** Front-Commerce default ones. +
+ +## Mix local and remote schemas + +A GraphQL module can expose both a remote schema and a local one with resolvers. +Front-Commerce will first merge the remote schema, and then the local one. + +It means that you can add resolvers to enrich remote types with local data. +In the example below, the module adds a custom `relatedProducts` to the remote `Pokemon` type (named `Pokemon_Pokemon` in Front-Commerce) resolving to products fetched from the pokemon id (in a hypothetical loader). + +```js +// my-module/server/modules/pokemon/index.js +const typeDefs = ` +extend type Pokemon_Pokemon { + relatedProducts: [Product] +} +`; + +module.exports = { + namespace: "Pokemon", + dependencies: ["Another/CatalogModule"], + typeDefs, + resolvers: { + Pokemon_Pokemon: { + relatedProducts: ({ id }, _, { loaders }) => { + return loaders.Product.loadByPokemon(id); + } + } + }, + remoteSchema: { + uri: "https://graphql-pokemon.now.sh/" + } +}; +``` + +## Caveats + +Please note that **remote schema changes will only appear in your schema after a server restart**. +The remote schema definition is fetched during the server bootstrap process. + +
+ This remote schema stitching feature is still being explored, and we are actively looking for feedback to make it better. + Please [get in touch](mailto:contact@front-commerce.com) if you want to share your wishes with us or ask any question! +
\ No newline at end of file diff --git a/source/docs/reference/graphql-module-definition.md b/source/docs/reference/graphql-module-definition.md index 5867de13..598d136e 100644 --- a/source/docs/reference/graphql-module-definition.md +++ b/source/docs/reference/graphql-module-definition.md @@ -217,3 +217,52 @@ module.exports = { } } ``` + +## `remoteSchema` (optional) + +The `remoteSchema` key allows you to achieve [remote schema stitching in Front-Commerce](/docs/advanced/graphql/remote-schemas.html). + +It should be an object with the following keys. + +### `uri` + +The `uri` key is **mandatory** and must contain the remote GraphQL endpoint. + +Example: + +```js +module.exports = { + namespace: "Acme/RemoteFeature", + remoteSchema: { + uri: "https://remote-feature.acme.org/graphql" + } +}; +``` + +By default all queries and mutations are merged with the current schema. +A set of default transformations are applied: read [the dedicated documentation section](/docs/advanced/graphql/remote-schemas.html#Default-transforms) for further information. + +### `transforms` (optional) + +The `transforms` key allows you to optionally manipulate the remote schema before it is stitched with the existing Front-Commerce schema. + +It must be an array of valid [`graphql-tools` Schema Transforms](https://www.apollographql.com/docs/graphql-tools/schema-transforms), and will be applied **before** Front-Commerce’s [default transforms](/docs/advanced/graphql/remote-schemas.html#Default-transforms). + +Example: + +```js +const { FilterRootFields } = require("graphql-tools"); + +module.exports = { + namespace: "Acme/RemoteFeature", + remoteSchema: { + uri: "https://remote-feature.acme.org/graphql" + transforms: [ + new FilterRootFields( + (operation, rootField) => + operation === "Query" && rootField === "aRootFieldToExpose" + ) + ] + } +}; +``` From df6ed21f96d738066ee1eaf8d5b2afa89179da66 Mon Sep 17 00:00:00 2001 From: Pierre Martin Date: Mon, 25 Mar 2019 19:54:13 +0100 Subject: [PATCH 2/3] =?UTF-8?q?Document=20Magento=E2=80=99s=20GraphQL=20su?= =?UTF-8?q?pport=20in=20Front-Commerce?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- _config.yml | 1 + source/docs/magento2/graphql.md | 66 ++++++++++++++++++++++++++++++++ source/docs/magento2/overview.md | 6 ++- 3 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 source/docs/magento2/graphql.md diff --git a/_config.yml b/_config.yml index cf355ec4..c06a7f3a 100755 --- a/_config.yml +++ b/_config.yml @@ -43,6 +43,7 @@ sidebar_categories: - docs/concepts/react-components-structure Magento2: - docs/magento2/overview + - docs/magento2/graphql Reference: - docs/reference/front-commerce-js - docs/reference/configurations diff --git a/source/docs/magento2/graphql.md b/source/docs/magento2/graphql.md new file mode 100644 index 00000000..a4fd475a --- /dev/null +++ b/source/docs/magento2/graphql.md @@ -0,0 +1,66 @@ +--- +id: magento2-graphql +title: Magento2 GraphQL schema +--- + +Front-Commerce aims at making Magento developers productive by allowing them to work with what they know from Magento. + +In order to achieve this, our goal is to expose as much [Magento’s GraphQL schema](https://devdocs.magento.com/guides/v2.3/graphql/) as possible in Front-Commerce. +We follow evolutions in Magento core very closely, and aim at including the new stable parts of this schema in Front-Commerce **as soon as they match the parts we’ve developed over the years in terms of feature, performance and stability**. + +This section details what is available so far. + +
+ Please note that it relies upon the [GraphQL modules remote schema](/docs/advanced/graphql/remote-schemas.html) support from Front-Commerce. + We recommend to have at least a basic understanding of how it works if you know Magento’s GraphQL schema and would like to find yourself at home in Front-Commerce! +
+ +## Enable Magento2 GraphQL module + +Front-Commerce supports both Magento 2.2 and 2.3 versions. +For this reason, GraphQL support for Magento is not part of the default Magento2 [meta module](/docs/advanced/graphql/meta-modules.html). + +To enable GraphQL support for Magento 2.3+, you must register the `server/modules/magento2-graphql` module in your application. + +To do so, add the following line in your [`.front-commerce.js`](/docs/reference/front-commerce-js.html) file: + +```diff +// .front-commerce.js +module.exports = { + name: "Front-Commerce", + url: "https://www.front-commerce.test", + modules: [], + serverModules: [ + { name: "FrontCommerceCore", path: "server/modules/front-commerce-core" }, +- { name: "Magento2", path: "server/modules/magento2" } ++ { name: "Magento2", path: "server/modules/magento2" }, ++ { name: "Magento2GraphQL", path: "server/modules/magento2-graphql" } + ] +}; +``` + +**Restart your server**, and you must now see the additional endpoints. + +## Store configurations + +The public store configurations are available under the `Magento2GraphQL_storeConfig` query. + +Example: + +```graphql +{ + Magento2GraphQL_storeConfig { + timezone + } +} +``` + +See [the related Magento DevDocs page](https://devdocs.magento.com/guides/v2.3/graphql/reference/store-config.html) for more information. + +## Is something missing? + +As detailed earlier, Front-Commerce already supports a wide range of Magento features. +We believe that — to date — **most of the features from Front-Commerce schema are more stable, performant and complete than Magento’s GraphQL counterpart** (even if the schema is slightly different). + +However, our goal is to reduce this gap (and our codebase!) and your feedback is welcome. +If you think something is missing in Front-Commerce, or stable enough in Magento to be used in production [send us an email](mailto:contact@front-commerce.com) and we could add it to our roadmap! \ No newline at end of file diff --git a/source/docs/magento2/overview.md b/source/docs/magento2/overview.md index fcf7b8b4..d5ad9e61 100644 --- a/source/docs/magento2/overview.md +++ b/source/docs/magento2/overview.md @@ -3,7 +3,11 @@ id: overview title: Overview --- -In this section, you will learn information about Magento 2 integration with Front-Commerce. We are still in the process of writing the documentation. But we will cover the following topics: +In this section, you will learn information about Magento 2 integration with Front-Commerce. + +* [Magento’s GraphQL support in Front-Commerce](/docs/magento2/graphql.html) + +We are still in the process of writing the documentation. But we will cover the following topics: * Configure the Magento 2 integration * Supported features and versions of Magento 2 From 5e76505e384934137cd26635505e3b482db3e138 Mon Sep 17 00:00:00 2001 From: Pierre Martin Date: Mon, 25 Mar 2019 19:54:35 +0100 Subject: [PATCH 3/3] =?UTF-8?q?1.0.0-alpha.2=20release=E2=80=99s=20announc?= =?UTF-8?q?ement?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/_posts/release-1.0.0-alpha.2.md | 91 ++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100755 source/_posts/release-1.0.0-alpha.2.md diff --git a/source/_posts/release-1.0.0-alpha.2.md b/source/_posts/release-1.0.0-alpha.2.md new file mode 100755 index 00000000..79591829 --- /dev/null +++ b/source/_posts/release-1.0.0-alpha.2.md @@ -0,0 +1,91 @@ +--- +title: "Release: 1.0.0-alpha.2" +date: 2019-03-25 +--- + +Front-Commerce `1.0.0-alpha.2` has been released with several improvements: revamped cart page, remote schema stitching, sitemap generation… + +Read more about what’s new in this release that makes us closer to 1.0! + + + +## Atoms improvements + +As you may know, [Front-Commerce UI components are organized according to Atomic Design’s principles](/docs/concepts/react-components-structure.html). +In this release, several atoms have been improved to make their API clearer and reduce the risk to use them incorrectly. + +The main components impacted are: `