Release 1.0.0 alpha.2

_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
@@ -42,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

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!
+
+<!-- more -->
+
+## 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: `<Button>` (and its variants), `<Link>`, `<ResizedImage>` and some form-related atoms.
+
+We also ensured that styles were not leaking across components, and that all variants were identified and used.
+
+Their Storybook stories were also cleaned and homogeneized.
+
+## Consistent variants API
+
+Components were exposing heterogeneous API for using a variant (boolean props, `type` pros…).
+
+To improve consistency and [make impossible states impossible](https://kentcdodds.com/blog/make-impossible-states-impossible), we’ve decided to change their API and always use an `appearance` property which is an enumeration of existing variants.
+
+**These changes are backward compatible.**
+Deprecation warnings will appear if you keep using the old properties.
+
+## Cart page revamped
+
+The Cart page was one of the oldest in our base theme.
+It used legacy components and was overriden in most of the existing Front-Commerce projects.
+
+Based on real-world use cases and feedbacks from partners, we revamped it to be more consistent with other pages.
+We reused several components from the checkout and atoms/molecules for a more consistent UI and a cleaner code.
+
+The Minicart has also been improved accordingly.
+
+## GraphQL remote schemas
+
+[GraphQL modules](/docs/essentials/extend-the-graphql-schema.html) can now register remote schemas to be stitched in the GraphQL schema, with custom transforms.
+
+It enables a wide range of use cases for reusing your existing GraphQL endpoints in you eCommerce storefront.
+Here are some example:
+
+- 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!
+
+Read more in our documentation: [GraphQL remote schemas](/docs/advanced/graphql/remote-schemas.html).
+
+## Magento2.3: store configurations are now exposed
+
+Several people asked us to be able to get Magento store configurations from the theme, so administrators could be autonomous for some storefront customizations.
+
+Thanks to remote schema stitching we have been able to reuse the `storeConfig` Magento2 GraphQL query.
+Frontend developers can access these configurations the same way they would in a standard Magento2 PWA project, from the `Magento2GraphQL_storeConfig` root query.
+
+<blockquote class="important">
+In order to allow compatibility with Magento 2.2 stores, you will have to register a new GraphQL module if you want to use it and are on Magento 2.3.
+See our [Magento2 GraphQL documentation page](/docs/magento2/graphql.html) for more information.
+</blockquote>
+
+<blockquote class="twitter-tweet" data-lang="fr"><p lang="en" dir="ltr">Here is the whole codebase of a module exposing Magento’s GraphQL queries in a <a href="https://twitter.com/Front_Commerce?ref_src=twsrc%5Etfw">@Front_Commerce</a> application.<br>This is why you can (should?) start an M2 shop right now with FC and adopt GraphQL/PWA Studio features when they’ll be stable. <a href="https://t.co/5kQNcj6yaX">pic.twitter.com/5kQNcj6yaX</a></p>&mdash; Pierre Martin (@pierremartin) <a href="https://twitter.com/pierremartin/status/1108157053732835329?ref_src=twsrc%5Etfw">20 mars 2019</a></blockquote>
+<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
+
+
+## Sitemap generation and image cache warmup scripts are back!
+
+During our first alpha releases, we had not taken the time to migrate existing scripts to the new architecture.
+This is now fixed and you can use scripts from Front-Commerce’s core on your servers.
+
+Read more about them in our documentation: [Front-Commerce’s scripts reference](/docs/reference/scripts.html).
+
+## And more
+
+There are a few other things that were included in this release:
+- bug fixes
+- `graphql-js` update to its latest version
+- removed unused methods from the core
+- resolve relative paths from the current file in `*.scss`
+
+To know more about this release, we recommend you to check the following pages:
+- [Migration guide from 1.0.0-alpha.1 to 1.0.0-alpha.2](/docs/appendices/migration-guides.html#1-0-0-alpha-1-gt-1-0-0-alpha-2)
+- [Full changelog from release notes](https://gitlab.com/front-commerce/front-commerce/releases) (Partners and Customers only)
+
+As always, feel free to send us [an email](mailto:[email protected]) or a [Slack](https://join.slack.com/t/front-commerce/shared_invite/enQtMzI2OTEyMDYzOTkxLWY0Y2JjYmRmNGQ2MWM1NzQyMjQwNzlmYzJmYzgzNTIwYzQ3MDVkMWZiYmYwNWFhODhmYWM5OTI4YjdiZDJkY2Q) message if you have any question.

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.
+
+<blockquote class="feature--new">
+  _This feature has been added in version `1.0.0-alpha.2`_
+</blockquote>
+
+## 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" }
+  ]
+};
+```
+
+<blockquote class="note">
+  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.
+</blockquote>
+
+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!)`.
+
+<blockquote class="important">
+  **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.
+</blockquote>
+
+### 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"
++      )
++    ]
+  }
+};
+```
+
+<blockquote class="info">
+  Please note that these transforms are applied **before** Front-Commerce default ones.
+</blockquote>
+
+## 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.
+
+<blockquote class="wip">
+  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:[email protected]) if you want to share your wishes with us or ask any question!
+</blockquote>

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.
+
+<blockquote class="info">
+  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!
+</blockquote>
+
+## 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:[email protected]) and we could add it to our roadmap!

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