docs: update and improve typescript docs

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/development/adding-typescript.mdx

@@ -0,0 +1,95 @@
+---
+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`.
+
+</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 JS starter template in terms of functionality but it includes the additional TypeScript setup.
+
+# Configuration
+
+Every TypeScript project requires a `tsconfig.json` file to instruct TypeScript on 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
+to use that 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 is 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`.
+
+# Migrate to TypeScript
+
+If you have an existing Custom Application project and would like to migrate it to TypeScript, you need to 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, 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 work your way up to the application entry point.
+  The [migrating from JavaScript documentation](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) can help with setting up a basic plan.
+
+  All UIKit and ApplicationKit packages provide declaration files and export useful types when necessary.
+
+  During the 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
+    }
+  }
+  ```
+
+  Please remember to revert that once the migration is over, as using `any` should be avoided.
+
+  </Info>
+
+* Add a script command `"typecheck": "tsc --noEmit"` in your `package.json` to compile the application.

website/src/content/development/index.mdx

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

website/src/data/navigation.yaml

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