docs: finish documenting migration steps for v17

.changeset/late-starfishes-care.md

@@ -14,4 +14,4 @@
 Remove `mc-scripts extract-intl` command in favor of the official `@formatjs/cli` package.
 We recommend to update your script to extract Intl messages to use the `formatjs extract` command.
 
-See full release notes: https://docs.commercetools.com/custom-applications/releases/2020-10-12-migrating-to-v17
+See full release notes: https://docs.commercetools.com/custom-applications/releases/2020-10-14-custom-applications-v17

.changeset/lemon-radios-travel.md

@@ -7,4 +7,4 @@
 
 Migrate Apollo dependencies to `@apollo/client` package.
 
-See full release notes: https://docs.commercetools.com/custom-applications/releases/2020-10-12-migrating-to-v17
+See full release notes: https://docs.commercetools.com/custom-applications/releases/2020-10-14-custom-applications-v17

website/src/content/deployment/http-server.mdx

@@ -4,6 +4,6 @@ title: HTTP Server
 
 <Warning>
 
-As of `>= v17` this page no longer exists. Please refer to the [documentation about compiling a Custom Application](/deployment/compiling-a-custom-application) and the [release notes on how to replace the HTTP server](/releases/2020-10-12-migrating-to-v17).
+As of `>= v17` this page no longer exists. Please refer to the [documentation about compiling a Custom Application](/deployment/compiling-a-custom-application) and the [release notes on how to replace the HTTP server](/releases/2020-10-14-custom-applications-v17).
 
 </Warning>

website/src/content/main-concepts/graphql.mdx

@@ -33,6 +33,6 @@ Requests to the `/graphql` endpoint require one or more HTTP headers, to determi
 
 <Info>
 
-As of version `>=17` of the `@commercetools-frontend/application-shell` package, it is recommended to use the `context` object to pass request metadata instead of the `variables` object. See related [release notes](/releases/2020-10-12-migrating-to-v17).
+As of version `>=17` of the `@commercetools-frontend/application-shell` package, it is recommended to use the `context` object to pass request metadata instead of the `variables` object. See related [release notes](/releases/2020-10-14-custom-applications-v17).
 
 </Info>

website/src/releases/2020-10/release-v17.mdx

@@ -0,0 +1,233 @@
+---
+date: 2020-10-14
+title: Custom Applications v17
+description: |
+  The Application Kit packages have been released as a new major version v17.\
+  In this release note we go through the important migration steps.
+type: announcement
+topics:
+  - Breaking Changes
+  - Dependencies
+---
+
+The Application Kit packages have been released as a new **major version** `v17`. One of the most important changes in this release is about migrating to the new Apollo Client `v3`.
+
+Follow the steps below to migrate your Custom Application to the new versions.
+
+<!--more-->
+
+# Migrating to Apollo Client v3
+
+Migrating to the new Apollo Client `v3` requires some important migration steps.
+
+## Migrating Apollo imports
+
+Apollo ships now with a single package `@apollo/client` instead of multiple ones.
+
+For Custom Applications this means that the peer dependencies `apollo-client` and `react-apollo` are now replaced with the new peer dependency of `@apollo/client`.
+
+This is all you need to do to migrate to the latest version of Apollo, including of course [updating the Apollo imports](https://www.apollographql.com/docs/react/migrating/apollo-client-3-migration/#updating-imports).
+
+## About the new Apollo Cache
+
+With Apollo `v3`, the Apollo in-memory cache got some improvements as well, resulting in some breaking changes. Please make sure to [read this document](https://www.apollographql.com/docs/react/migrating/apollo-client-3-migration/#cache-improvements) to understand the changes.
+
+Depending on the GraphQL queries and mutations used by your Custom Application, it might be that the caching behavior of those queries needs to be adjusted. For example if objects do not have an `id` field as identifier, or if Apollo cannot automatically merge two objects that have different fields shape, and so on.
+
+If that is the case, you need to configure the Apollo cache according to your needs, as only you and your Custom Application can decide what is the best caching strategy.
+
+To enable you to do so, the `<ApplicationShell>` component now accepts an `apolloClient` prop, that allows you to configure your own instance of the Apollo client with the custom cache configuration.
+
+The `@commercetools-frontend/application-shell` package exposes a `createApolloClient` function that allows you to create a new Apollo client pre-configured with some important defaults (for example Apollo links, some basic cache policies, etc.).
+
+```jsx
+import { createApolloClient, ApplicationShell } from '@commercetools-frontend/application-shell';
+
+const apolloClient = createApolloClient({
+  cache: {
+    // Your custom configuration, according to the Apollo cache documentation.
+    // https://www.apollographql.com/docs/react/caching/cache-configuration/
+  },
+});
+
+const Application = () => {
+  return (
+    <ApplicationShell
+      apolloClient={apolloClient}
+      // ...other props
+    />
+  );
+};
+```
+
+## Changes about Apollo query variables and context
+
+Previously, to perform GraphQL requests to the Merchant Center API Gateway, you would need to specify request metadata options such as the [GraphQL Target](https://docs.commercetools.com/custom-applications/main-concepts/graphql#request-format).
+
+These values had to be specified in the query `variables` object, which the built-in Merchant Center Apollo HTTP Link would parse and assign it to the request as HTTP headers. We call these options **request context**.
+
+However, with a more stable support for the `context` option in Apollo Client, we can pass the request metadata options to the `context` object instead of the `variables` object.
+
+```diff
+const { loading, data, error } = useQuery(MyQuery, {
+- variables: {
++ context: {
+    target: GRAPHQL_TARGETS.COMMERCETOOLS_PLATFORM,
+  },
+});
+```
+
+The **request context** options include:
+
+- `target`
+- `projectKey`
+
+<Info>
+
+Passing the request metadata to the `variables` object still works for backwards compatibility but it is recommended to use the `context` object instead.
+
+</Info>
+
+## Enforcing a valid context object
+
+The recommended and preferred way of passing request context is to use the `context` object.
+To improve the TypeScript support and auto-completion for the **request context** options, the `@commercetools-frontend/application-shell` package now exports new React hooks. Note that autocompletion is possible, even if you are not using TypeScript.
+
+- `useMcQuery`
+- `useMcLazyQuery`
+- `useMcMutation`
+
+These hooks are thin wrappers around the original Apollo hooks and have the same API, with a minor difference. Namely, the `context` object is properly typed to conform with the Merchant Center **request context** instead of `any`.
+
+```diff
+-import { useQuery } from '@apollo/client/react';
++import { useMcQuery } from '@commercetools-frontend/application-shell';
+
+-const { loading, data, error } = useQuery(MyQuery, {
++const { loading, data, error } = useMcQuery(MyQuery, {
+  context: {
+    target: GRAPHQL_TARGETS.COMMERCETOOLS_PLATFORM,
+  },
+});
+```
+
+# Changes about the `mc-scripts` CLI
+
+## Removing deprecated options from `compile-html`
+
+Previously deprecated CLI options such as `--env`, `--csp`, `--headers`, have been removed.
+
+Additionally, the CLI flag `--use-local-assets` has been removed as well. The default behavior of `mc-scripts compile-html` now is to compile the assets locally, which is the only reasonable thing to do.
+
+When running the `mc-scripts compile-html` command, the `index.html` is compiled for production usage and it lives in the `public` folder, together with the other static assets. This is all you need to deploy your application.
+You can decide to [deploy the Custom Application statically to one of the popular cloud providers](/deployment/compiling-a-custom-application#deployment), or serve the files on your own using a static server.
+
+For example, to run locally the Custom Application using the production bundles:
+
+```console
+NODE_ENV=production MC_APP_ENV=development dotenv -- \
+  mc-scripts compile-html \
+  --transformer @commercetools-frontend/mc-dev-authentication/transformer-local.js
+
+mc-scripts serve
+```
+
+## Removing the `mc-http-server` package
+
+The `@commercetools-frontend/mc-http-server` package has been deprecated and won't be published anymore.
+
+With the usage of the `compile-html` command there is no need to have a pre-configured HTTP server anymore. If you are using this package, we recommend to use any other HTTP server package to serve your static files.
+
+<Info>
+
+Remember that after building your production bundles you need to [compile the Custom Application](/deployment/compiling-a-custom-application#deployment) for production usage.
+
+</Info>
+
+## New command `serve`
+
+We added a new command `mc-scripts serve` that can be used to start your Custom Application **locally** in `production` mode, after having it compiled.
+
+The command starts an HTTP server to serve the static assets from the `public` folder.
+
+<Warning>
+
+This command should only be used locally to test the Custom Application in production mode, as it contains the development routes for `/login` and `/logout`.
+
+</Warning>
+
+Before:
+
+```json title="package.json"
+{
+  "start:prod:local": "NODE_ENV=production MC_APP_ENV=development dotenv -- mc-http-server --use-local-assets"
+}
+```
+
+After:
+
+```json title="package.json"
+{
+  "compile-html:local": "NODE_ENV=production MC_APP_ENV=development dotenv -- mc-scripts compile-html --transformer @commercetools-frontend/mc-dev-authentication/transformer-local.js",
+  "start:prod:local": "yarn compile-html:local && mc-scripts serve",
+}
+```
+
+## Removing the `extract-intl` command
+
+The `mc-scripts extract-intl` command has been removed in favor of the [official `@formatjs/cli` package](https://formatjs.io/docs/tooling/cli#extraction).
+
+We recommend to update your script to extract Intl messages to use the `formatjs extract` command.
+
+Before:
+
+```json title="package.json"
+{
+  "i18n:build": "mc-scripts extract-intl --output-path=$(pwd)/src/i18n/data 'src/**/!(*.spec).js' --build-translations"
+}
+```
+
+After:
+
+```json title="package.json"
+{
+  "extract-intl": "formatjs extract --format=$(pwd)/intl-formatter.js --out-file=$(pwd)/src/i18n/data/core.json 'src/**/!(*.spec).js'"
+}
+```
+
+where the `intl-formatter.js` is something like this (depending on your translation tool):
+
+```js title="intl-formatter.js"
+// https://formatjs.io/docs/tooling/cli#extraction
+exports.format = function format(extractedMessages) {
+  return (
+    Object.keys(extractedMessages)
+      // transform strings to lowercase to imitate phraseapp sorting
+      .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()))
+      .reduce(
+        (allMessages, messageId) => ({
+          ...allMessages,
+          // Return a simple key/value JSON object.
+          [messageId]: extractedMessages[messageId].defaultMessage,
+        }),
+        {}
+      )
+  );
+};
+```
+
+# Changes about the `experimentalRenderAppWithRedux` from test utils
+
+The experimental render method `experimentalRenderAppWithRedux` from the `test-utils` has been removed.
+
+Instead, you should pass the `disableApolloMocks` option to the `renderApp` and `renderAppWithRedux` methods. When this option is set to `true`, the real `ApolloProvider` is rendered instead of Apollo's `MockProvider`.
+
+This is useful if you want to mock requests at the network level, for example when using [Mock Service Worker](https://mswjs.io/).
+
+Additionally, you can also pass a custom `apolloClient` instance together with the `disableApolloMocks` option. This is only useful when your Custom Application uses a custom `apolloClient`, for example for configuring the cache policies.
+
+# Removing the deprecated options from `application-shell`
+
+The `@commercetools-frontend/application-shell` package no longer exports the deprecated `AsyncChunkLoader` and `handleApolloErrors`.
+
+Additionally, the deprecated prop `trackingEventWhitelist` of the `<ApplicationShell>` component has been removed as well.