docs: TypeScript support in Custom Applications and release v21.8 (#…

…2624)

* docs: document typescript use in custom applications

* docs: linter improvements

* docs: improvements

* docs: update typescript setup docs

* docs: improvements

* docs: update and improve typescript docs

* docs: typo

* docs: add release note for v21.8

* docs: improvements based on suggestions

* docs: improve wording

* docs: wording improvements

Co-authored-by: Stephen Armstrong <[email protected]>

* docs: wording improvements

* ci: trigger

Co-authored-by: Nicola Molinari <[email protected]>
Co-authored-by: Stephen Armstrong <[email protected]>

recommended.code-workspace

@@ -32,12 +32,9 @@
       "typescriptreact",
       "graphql"
     ],
-    "vscode-vale.path": "${workspaceFolder}/node_modules/.bin/commercetools-vale",
-    "vscode-vale.fileExtensions": [
-      "md",
-      "markdown",
-      "mdx"
-    ],
+    "vale.core.useCLI": true,
+    "vale.valeCLI.path": "${workspaceFolder}/node_modules/.bin/commercetools-vale-bin",
+    "vale.valeCLI.config": "${workspaceFolder}/node_modules/@commercetools-docs/writing-style/.vale.ini",
     "spellright.notificationClass": "error",
     "spellright.language": [
       "en"
@@ -58,7 +55,8 @@
         ],
         "url": "./packages/application-config/schema.json"
       }
-    ]
+    ],
+    "typescript.tsdk": "node_modules/typescript/lib"
   },
   "extensions": {
     "recommendations": [

website/src/content/api-reference/application-config.mdx

@@ -623,7 +623,7 @@ You can also pass multiple references to the same value:
 
 <Info>
 
-This feature is available from version `>= 20.8.0`.
+This feature is available from version `20.8.0` onwards.
 
 </Info>
 
@@ -652,7 +652,7 @@ The reference placeholder assumes that the Custom Application has the translatio
 
 <Info>
 
-This feature is available from version `>= 20.8.0`.
+This feature is available from version `20.8.0` onwards.
 
 </Info>
 

website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx

@@ -215,6 +215,34 @@ This component must be defined in a parent component where children of this comp
 | `skip`                          | `boolean`                  |    -     | -                 | false     | Disables loading images configuration.                                   |
 
 
+### useProjectExtensionImageRegex
+
+A React hook that allows accessing the project images configuration.
+
+```jsx highlightLines="4-6"
+import { useProjectExtensionImageRegex } from '@commercetools-frontend/application-shell-connectors';
+
+function MyComponent() {
+  const { isLoading, imageRegex } = useProjectExtensionImageRegex();
+
+  if (isLoading) return <LoadingSpinner />;
+
+  return (
+    <div>
+      <h1>Project images regex: {JSON.stringify(imageRegex)}</h1>
+    </div>
+  );
+}
+
+function MyApp() {
+  return (
+    <ProjectExtensionProviderForImageRegex>
+      <MyComponent />
+    </ProjectExtensionProviderForImageRegex>
+  );
+}
+```
+
 ### GetProjectExtensionImageRegex
 
 Use this component to access the project images configuration, using a `render` prop function.

website/src/content/concepts/integrate-with-your-own-api.mdx

@@ -37,7 +37,7 @@ To facilitate the usage of the [built-in Apollo client and the SDK actions](/dev
 
 <Info>
 
-This feature is available from version `>= 21.8.0`.
+This feature is available from version `21.8.0` onwards.
 
 </Info>
 
@@ -57,7 +57,7 @@ For example, given the forward-to URL `https://my-custom-app.com/api/123`, the `
 
 <Info>
 
-This feature is available from version `>= 20.2.0`.
+This feature is available from version `20.2.0` onwards.
 
 </Info>
 

website/src/content/development/adding-typescript.mdx

@@ -0,0 +1,101 @@
+---
+title: Adding TypeScript
+---
+
+[TypeScript](https://www.typescriptlang.org/) is a typed superset of JavaScript that compiles to plain JavaScript.
+
+Custom Applications have full support for developing applications in TypeScript.
+
+<Info>
+
+This feature is available from version `21.8.0` onwards.
+
+</Info>
+
+To start a new Custom Application project with TypeScript, you can use the TypeScript starter template:
+
+```console noPromptLines="2-3"
+npx @commercetools-frontend/create-mc-app@latest \
+  my-new-custom-application-project \
+  --template starter-typescript
+```
+
+The TypeScript starter template is the same as the standard JavaScript starter template in terms of functionality but it also includes the additional TypeScript setup.
+
+# Configuration
+
+Every TypeScript project requires a `tsconfig.json` file to instruct TypeScript how to compile the project.
+
+Therefore, we provide a base TSConfig to be used in your `tsconfig.json` file:
+
+```json
+{
+  "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json"
+}
+```
+
+Furthermore, we provide a `client.d.ts` declaration file with some basic type shims for importing media assets:
+
+- `.mod.css` and `.module.css`
+- `.png`
+- `.svg`
+
+You can include this using the TypeScript triple-slash directives:
+
+```ts
+/// <reference types="@commercetools-frontend/application-config/client" />
+```
+
+<Info>
+
+By default, this is included in the TypeScript starter template `src/index.tsx` entry point file.
+
+</Info>
+
+You can also include this in the `tsconfig.json` file in the `compilerOptions.types` field but we don't recommend
+doing so unless you are very familiar with the [implications of using the `types` field](https://www.typescriptlang.org/tsconfig#types).
+
+Additional adjustments to other config files are also required, in particular:
+
+- `.prettierrc`: use the `typescript` parser.
+- `jest.test.config.js`: use the `@commercetools-frontend/jest-preset-mc-app/typescript` preset.
+- `jest.eslint.config.js`: include the file extensions `ts` and `tsx` in `moduleFileExtensions`, then `<rootDir>/**/*.ts` and `<rootDir>/**/*.tsx` in `testMatch`.
+
+<Info>
+
+The TypeScript setup is already preconfigured when using the TypeScript starter template. Consider this document as a reference to match your setup.
+
+</Info>
+
+# Migrate to TypeScript
+
+If you have an existing Custom Application project and want to migrate to TypeScript, you should do the following:
+
+* Install the `typescript` dependency.
+* Add a `tsconfig.json` file. See [configuration](#configuration) for the tooling setup.
+* Migrate the JavaScript files to TypeScript, using either `.ts` or `.tsx` (if a file contains JSX syntax).
+
+  <Info>
+
+  Migrating source files to TypeScript can be done incrementally. We recommend starting from the "leaf files" and working up to the application entry point.
+  The [migrating from JavaScript documentation](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) can help you set up a basic plan.
+
+  All UI Kit and ApplicationKit packages provide declaration files and export useful types when necessary.
+
+  During migration you might need to loosen up the types strictness, for example by allowing explicit `any` types.
+
+  ```json title="tsconfig.json"
+  {
+    "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json",
+    "compilerOptions": {
+      "noExplicitAny": false,
+      "strict": false
+    }
+  }
+  ```
+
+  You should revert these once migration is complete, as using `any` should be avoided.
+
+  </Info>
+
+* Add the script command `"typecheck": "tsc --noEmit"` to your `package.json` to run the type checks of the application.

website/src/content/development/index.mdx

@@ -49,6 +49,12 @@ In particular, we'll be going through the following topics:
   >
     Learn more about implementing translations in your Custom Application.
   </Card>
+  <Card
+    title="Adding TypeScript"
+    href="/development/adding-typescript"
+  >
+    Learn more about developing your Custom Application using TypeScript.
+  </Card>
   <Card
     title="Going to Production"
     href="/development/going-to-production"

website/src/content/getting-started.mdx

@@ -24,6 +24,8 @@ npx @commercetools-frontend/create-mc-app@latest \
   --template starter
 ```
 
+To start with a [TypeScript](https://www.typescriptlang.org/) project, use the `--template=starter-typescript` flag. Read more about TypeScript in the [Adding TypeScript](/development/adding-typescript) page.
+
 <Info>
 
 Local development and login are only allowed for users being part of the `Administrators` Team of your Organization. Therefore, choose a Project that is part of an Organization where you are an administrator of.

website/src/data/navigation.yaml

@@ -38,6 +38,8 @@
       path: /development/translations
     - title: Permissions
       path: /development/permissions
+    - title: Adding TypeScript
+      path: /development/adding-typescript
     - title: Going to Production
       path: /development/going-to-production
 - chapter-title: Deployment Examples

website/src/releases/2020-06/hostname-migration.mdx

@@ -71,7 +71,7 @@ For example:
 In production, the `<ApplicationShell>` takes care of inferring the correct [Merchant Center Gateway API hostname](/concepts/merchant-center-api#hostnames) based on the Merchant Center hostname that the user is logged into.
 This results in the Custom Application to work in both new and legacy hostnames, even though the `mcApiUrl` is configured to a specific value.
 
-This feature is available from version `>= 16.2.1`.
+This feature is available from version `16.2.1` onwards.
 
 </Info>
 

website/src/releases/2022-07/release-v21.8.mdx

@@ -0,0 +1,48 @@
+---
+date: 2022-07-04
+title: Custom Applications v21.8
+description: The Application Kit packages have been released with several new features.
+type: feature
+topics:
+  - CLI
+  - Configuration
+  - Templates
+  - UI Components
+---
+
+The Application Kit packages have been released with a minor version `v21.8`.
+
+This release includes several new features that we would like to present:
+
+* Official support for developing Custom Applications in [TypeScript](https://www.typescriptlang.org/), including a new starter template. Read more about TypeScript in the [Adding TypeScript](/development/adding-typescript) page.
+* New policy option for configuring the `audience` field when [integrating your Custom Application with an external API](/concepts/integrate-with-your-own-api#configuring-the-audience-policy).
+* Improved accessibility of different elements using ARIA attributes.
+* Simpler and more readable list of time zone data, available from the `@commercetools-frontend/l10n` package.
+* New React hook `useProjectExtensionImageRegex` for accessing the project images configuration, available from the `@commercetools-frontend/application-shell-connectors` package.
+
+As always, if you have questions or feedback you can open a [GitHub Discussion](https://github.com/commercetools/merchant-center-application-kit/discussions) or a [GitHub Issue](https://github.com/commercetools/merchant-center-application-kit/issues).
+
+<!--more-->
+
+# Deprecations
+
+The `mc-scripts` CLI has deprecated some entry points.
+
+Importing the function `createPostcssConfig` from the main entry point `@commercetools-frontend/mc-scripts` is now deprecated. Use the entry point `@commercetools-frontend/mc-scripts/postcss` instead.
+
+```diff
+const {
+  createPostcssConfig,
+-} = require('@commercetools-frontend/mc-scripts');
++} = require('@commercetools-frontend/mc-scripts/postcss');
+```
+
+Importing the functions `createWebpackConfigForDevelopment` and `createWebpackConfigForProduction` from the main entry point `@commercetools-frontend/mc-scripts` is now deprecated. Use the entry point `@commercetools-frontend/mc-scripts/webpack` instead.
+
+```diff
+const {
+  createWebpackConfigForDevelopment,
+  createWebpackConfigForProduction,
+-} = require('@commercetools-frontend/mc-scripts');
++} = require('@commercetools-frontend/mc-scripts/webpack');
+```