From cff7916532e72626bdc02d57f650b794337f8990 Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Mon, 12 Oct 2020 11:29:21 +0200 Subject: [PATCH 1/2] docs: finish documenting migration steps for v17 --- .changeset/late-starfishes-care.md | 2 +- .changeset/lemon-radios-travel.md | 2 +- .../src/content/deployment/http-server.mdx | 2 +- website/src/content/main-concepts/graphql.mdx | 2 +- .../src/releases/2020-10/migrating-to-v17.mdx | 100 -------- website/src/releases/2020-10/release-v17.mdx | 233 ++++++++++++++++++ 6 files changed, 237 insertions(+), 104 deletions(-) delete mode 100644 website/src/releases/2020-10/migrating-to-v17.mdx create mode 100644 website/src/releases/2020-10/release-v17.mdx diff --git a/.changeset/late-starfishes-care.md b/.changeset/late-starfishes-care.md index 9ac7b2a23f..e4039b811e 100644 --- a/.changeset/late-starfishes-care.md +++ b/.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 diff --git a/.changeset/lemon-radios-travel.md b/.changeset/lemon-radios-travel.md index bc43700949..39ece2cf39 100644 --- a/.changeset/lemon-radios-travel.md +++ b/.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 diff --git a/website/src/content/deployment/http-server.mdx b/website/src/content/deployment/http-server.mdx index ebf081629b..0107fbfd78 100644 --- a/website/src/content/deployment/http-server.mdx +++ b/website/src/content/deployment/http-server.mdx @@ -4,6 +4,6 @@ title: HTTP Server -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). \ No newline at end of file diff --git a/website/src/content/main-concepts/graphql.mdx b/website/src/content/main-concepts/graphql.mdx index 84969de981..8baad4db05 100644 --- a/website/src/content/main-concepts/graphql.mdx +++ b/website/src/content/main-concepts/graphql.mdx @@ -33,6 +33,6 @@ Requests to the `/graphql` endpoint require one or more HTTP headers, to determi -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). diff --git a/website/src/releases/2020-10/migrating-to-v17.mdx b/website/src/releases/2020-10/migrating-to-v17.mdx deleted file mode 100644 index e012e298b4..0000000000 --- a/website/src/releases/2020-10/migrating-to-v17.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -date: 2020-10-12 -title: Migrating to 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: feature -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 relates to migrating to the new Apollo Client `v3`. See official migration guide https://www.apollographql.com/docs/react/migrating/apollo-client-3-migration/. - -Follow the steps below to migrate your Custom Application to the new versions. - - - -## 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 version `3.0`, the 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. If that is the case, you need to create your own Apollo client instance with the correct Apollo cache configuration, and pass it to the `` component. - -The `@commercetools-frontend/application-shell` package exposes a `createApolloClient` function to create a new Apollo client with some important defaults (for example Apollo links, some pre-configured cache policies). - -```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 ( - - ); -}; -``` - -## 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` - -> Passing the request metadata to the `variables` object still works for backwards compatibility but it is recommended to use the `context` object instead. - -## 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, - }, -}); -``` diff --git a/website/src/releases/2020-10/release-v17.mdx b/website/src/releases/2020-10/release-v17.mdx new file mode 100644 index 0000000000..6da91e1dcc --- /dev/null +++ b/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. + + + +# 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 `` 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 ( + + ); +}; +``` + +## 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` + + + +Passing the request metadata to the `variables` object still works for backwards compatibility but it is recommended to use the `context` object instead. + + + +## 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. + + + +Remember that after building your production bundles you need to [compile the Custom Application](/deployment/compiling-a-custom-application#deployment) for production usage. + + + +## 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. + + + +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`. + + + +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 `` component has been removed as well. From 0d2fc214efc9f5620dd0c3fde2094f18a8492bae Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Mon, 12 Oct 2020 13:05:42 +0200 Subject: [PATCH 2/2] docs: improve wording Co-authored-by: Tobias Deekens --- website/src/releases/2020-10/release-v17.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/src/releases/2020-10/release-v17.mdx b/website/src/releases/2020-10/release-v17.mdx index 6da91e1dcc..0b05f51150 100644 --- a/website/src/releases/2020-10/release-v17.mdx +++ b/website/src/releases/2020-10/release-v17.mdx @@ -34,7 +34,7 @@ With Apollo `v3`, the Apollo in-memory cache got some improvements as well, resu 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. +If that is the case, you need to configure the Apollo cache according to your needs, as only you know what the best caching strategy for your Custom Application is. To enable you to do so, the `` component now accepts an `apolloClient` prop, that allows you to configure your own instance of the Apollo client with the custom cache configuration. @@ -117,7 +117,7 @@ These hooks are thin wrappers around the original Apollo hooks and have the same 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. +Additionally, the CLI flag `--use-local-assets` has been removed as well. As such the default behavior of `mc-scripts compile-html` changed to compile the assets locally. 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. @@ -134,7 +134,7 @@ 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. +The `@commercetools-frontend/mc-http-server` package has been deprecated and will not receive any updates. 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. @@ -146,13 +146,13 @@ Remember that after building your production bundles you need to [compile the Cu ## 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. +We added a new command `mc-scripts serve` that can be used to start your Custom Application **locally** in `production` mode after it has been compiled. The command starts an HTTP server to serve the static assets from the `public` folder. -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`. +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`. Do not use this command to serve your Custom Application in production. @@ -195,7 +195,7 @@ After: } ``` -where the `intl-formatter.js` is something like this (depending on your translation tool): +where the `intl-formatter.js` should be defined as something like this, depending on your translation tool's needs: ```js title="intl-formatter.js" // https://formatjs.io/docs/tooling/cli#extraction @@ -224,7 +224,7 @@ Instead, you should pass the `disableApolloMocks` option to the `renderApp` and 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. +Additionally, you can also pass a custom `apolloClient` instance together with the `disableApolloMocks` option. This is only needed when your Custom Application uses a custom `apolloClient`, for example for configuring the cache policies. # Removing the deprecated options from `application-shell`