From 33e4639e1b18754028f3068e7a1600dc21525482 Mon Sep 17 00:00:00 2001 From: Kacper Krzywiec Date: Tue, 24 May 2022 10:24:29 +0200 Subject: [PATCH 01/13] docs: document typescript use in custom applications --- website/src/content/development/index.mdx | 6 + .../src/content/development/typescript.mdx | 213 ++++++++++++++++++ website/src/data/navigation.yaml | 2 + 3 files changed, 221 insertions(+) create mode 100644 website/src/content/development/typescript.mdx diff --git a/website/src/content/development/index.mdx b/website/src/content/development/index.mdx index df24bb968f..c3622f7595 100644 --- a/website/src/content/development/index.mdx +++ b/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. + + Learn more about using TypeScript in your Custom Application. + + +Note that Custom Applications in JavaScript are fully functional and porting them to TypeScript is entirely optional. + +If you find TypeScript not beneficial for your Custom Application, you can skip to the next section. + + + +# TypeScript: optional static typing for JavaScript + +[TypeScript](https://www.typescriptlang.org/) is a superset of JavaScript: JS syntax is therefore valid TS. The goal of TypeScript is to help detect errors in code without running it and make development more efficient. Another considerable benefit is enabling a richer IntelliSense within IDEs for a great developer experience. It enables, for example, spotting common mistakes as you type the code, intelligent code completion and hover info. + +TypeScript compiler checks your code and produces the equivalent plain JavaScript code without the type information for browsers to run. + +# Why TypeScript? + +TypeScript's main advantages are: + +- compile-time error checking +- code readability and self-documentation +- great developer experience due to rich IntelliSense support +- availability of new JavaScript features without native browser support + +TypeScript also has some disadvantages: + +- considerable learning curve +- more code to write and maintain +- certain TypeScript features (for example types based on [generics](https://www.typescriptlang.org/docs/handbook/2/generics.html)) can lead to over-engineered code bases. + +In the end, the decision regarding the adoption of TypeScript must be well-thought-out. + +# Creating a Custom Application in TypeScript from scratch + +You can create a new Custom Application in TypeScript using the `starter-typescript` template. The template can be installed using the `npx` command. Replace `` with the name of the folder where the template should be installed into. + +```bash +$ npx @commercetools-frontend/create-mc-app --template starter-typescript +``` + +# Adding TypeScript support to an existing Custom Application in JavaScript + +Certain configuration steps are required for enabling TypeScript support in Custom Applications: + +## TypeScript configuration + +In order to work with TypeScript a configuration file named [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) is required. +It enables numerous [configuration options](https://www.typescriptlang.org/tsconfig). To simplify the initial setup we provide a base `tsconfig.json` file in `@commercetools-frontend/tsconfig` package to extend from in your Custom Application. + +### Installation + +``` +yarn add @commercetools-frontend/tsconfig + +# or + +npm --save install @commercetools-frontend/tsconfig +``` + +### Usage + +Create a `tsconfig.json` file in the root directory of your application and add contents: + +```json +{ + "extends": "@commercetools-frontend/tsconfig" +} +``` + +`tsconfig.json` is [easily extensible](https://www.typescriptlang.org/tsconfig#extends) and allows to create your custom configurations. + +To compile TypeScript files to JavaScript files [Babel](https://babeljs.io/) (since version 7) or [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) CLI can be used, but there are certain [differences](https://www.typescriptlang.org/docs/handbook/babel-with-typescript.html) to take into account. + + + + +Custom Applications by default have a preconfigured Babel support to compile TypeScript. + +In order to make sure that Babel configuration is set properly check if `babel.config.js` contains `@commercetools-frontend/babel-preset-mc-app` as a preset, and that the package is listed as the application dependency in `package.json`. + +`tsc` CLI is only used as a type checking tool, for example, run as `yarn typecheck` script: + +```json title="package.json" +{ + "scripts": { + ... + "typecheck": "tsc --noEmit" + } +} +``` + + + +## Prettier configuration + +To enable code formatting while typing TypeScript code edit `.prettierrc` configuration file: + +```json title=".prettierrc" +{ + ... + "parser": "typescript" +} +``` + +To run prettier as a script add the following contents to your `package.json`: + +```json title="package.json" +{ + "scripts": { + ... + "format:js": "prettier --write '**/*.{js,ts,tsx}'" + } +} +``` + +## ESLint configuration + +Custom Applications by default have a preconfigured code linting for TypeScript files with ESLint. + +In order to make sure that ESLint configuration is set properly check if `.eslintrc.js` extends `@commercetools-frontend/eslint-config-mc-app`, and that the package is listed as an application dependency in `package.json`. + +To run ESLint as a script edit the contents of `jest.eslint.config.js` configuration file in the root folder of the application: + +```js title="jest.eslint.config.js" +module.exports = { + ... + moduleFileExtensions: ['js', 'ts', 'tsx'], + testMatch: ['/**/*.js', '/**/*.ts', '/**/*.tsx'], +}; +``` + +To run ESLint run the following script from your `package.json`: + +```json title="package.json" +{ + "scripts": { + ... + "lint": "jest --config jest.eslint.config.js" + } +} +``` + +## Jest configuration + +For enabling Jest-based tests in TypeScript `@commercetools-frontend/jest-preset-mc-app` must be a installed as a dependency and configured as below in the `jest.test.config.js` file in the root folder of the application: + +```js title="jest.test.config.js" +const jestPresetForTypeScript = require('@commercetools-frontend/jest-preset-mc-app/jest-preset-for-typescript'); +module.exports = { + ...jestPresetForTypeScript, +}; +``` + +Make sure the config file is passed to `jest`: +```json title="package.json" +{ + "scripts": { + ... + "test": "jest --config jest.test.config.js" + } +} +``` + +# Migrating the Custom Application codebase to TypeScript + +Migration of an extensive codebase to TypeScript can be a strenuous task. It should be carefully considered and planned. +[TypeScript documentation](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) can help with setting up a basic plan. + + + +Two key recommendations for a successful migration: +- refrain from introducing functional changes at the same time +- ensure test coverage is sufficient before the migration to confidently progress without regressions + + + +Please mind that with the recommended `tsconfig.json` configuration any type checking errors will not prevent the compilation, so don't be discouraged by the missing types as the application remains functional. + +If the configuration seems too strict to start with it might be loosen up by, for example, allowing explicit `any` type. In such case edit `tsconfig.json`: +```json title="tsconfig.json" +{ + "extends": "@commercetools-frontend/tsconfig", + "compilerOptions": { + "noExplicitAny": false, + "strict": false + } +} +``` + +Additionally, edit ESLint config file `.eslintrc.js`: +```js title=".eslintrc.js" +module.exports = { + extends: ['@commercetools-frontend/eslint-config-mc-app'], + rules: { + ... + '@typescript-eslint/no-explicit-any': 'off' + }, +}; +``` + + +We advice not to make this change permanent as `any` type does not provide type safety. + + \ No newline at end of file diff --git a/website/src/data/navigation.yaml b/website/src/data/navigation.yaml index df4ced9142..80649463b6 100644 --- a/website/src/data/navigation.yaml +++ b/website/src/data/navigation.yaml @@ -38,6 +38,8 @@ path: /development/translations - title: Permissions path: /development/permissions + - title: TypeScript + path: /development/typescript - title: Going to Production path: /development/going-to-production - chapter-title: Deployment Examples From 32b89c9a95000c7239f6ebc20c0cc17ad4a555de Mon Sep 17 00:00:00 2001 From: Kacper Krzywiec Date: Tue, 24 May 2022 16:03:26 +0200 Subject: [PATCH 02/13] docs: linter improvements --- website/src/content/development/typescript.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/src/content/development/typescript.mdx b/website/src/content/development/typescript.mdx index 18dcdeb1f8..0faeac05a1 100644 --- a/website/src/content/development/typescript.mdx +++ b/website/src/content/development/typescript.mdx @@ -29,7 +29,7 @@ TypeScript's main advantages are: - compile-time error checking - code readability and self-documentation - great developer experience due to rich IntelliSense support -- availability of new JavaScript features without native browser support +- availability of new JavaScript features without current browser support TypeScript also has some disadvantages: @@ -53,7 +53,7 @@ Certain configuration steps are required for enabling TypeScript support in Cust ## TypeScript configuration -In order to work with TypeScript a configuration file named [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) is required. +The [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file is required to work with TypeScript. It enables numerous [configuration options](https://www.typescriptlang.org/tsconfig). To simplify the initial setup we provide a base `tsconfig.json` file in `@commercetools-frontend/tsconfig` package to extend from in your Custom Application. ### Installation @@ -85,7 +85,7 @@ To compile TypeScript files to JavaScript files [Babel](https://babeljs.io/) (si Custom Applications by default have a preconfigured Babel support to compile TypeScript. -In order to make sure that Babel configuration is set properly check if `babel.config.js` contains `@commercetools-frontend/babel-preset-mc-app` as a preset, and that the package is listed as the application dependency in `package.json`. +To make sure that Babel configuration is set properly check if `babel.config.js` contains `@commercetools-frontend/babel-preset-mc-app` as a preset, and that the package is listed as the application dependency in `package.json`. `tsc` CLI is only used as a type checking tool, for example, run as `yarn typecheck` script: @@ -126,7 +126,7 @@ To run prettier as a script add the following contents to your `package.json`: Custom Applications by default have a preconfigured code linting for TypeScript files with ESLint. -In order to make sure that ESLint configuration is set properly check if `.eslintrc.js` extends `@commercetools-frontend/eslint-config-mc-app`, and that the package is listed as an application dependency in `package.json`. +To make sure that ESLint configuration is set properly check if `.eslintrc.js` extends `@commercetools-frontend/eslint-config-mc-app`, and that the package is listed as an application dependency in `package.json`. To run ESLint as a script edit the contents of `jest.eslint.config.js` configuration file in the root folder of the application: From c70e0006e2f394139c2db89e14ba260edc516d68 Mon Sep 17 00:00:00 2001 From: Kacper Krzywiec Date: Wed, 25 May 2022 10:50:44 +0200 Subject: [PATCH 03/13] docs: improvements --- website/src/content/development/typescript.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/website/src/content/development/typescript.mdx b/website/src/content/development/typescript.mdx index 0faeac05a1..7d764d2f64 100644 --- a/website/src/content/development/typescript.mdx +++ b/website/src/content/development/typescript.mdx @@ -29,7 +29,7 @@ TypeScript's main advantages are: - compile-time error checking - code readability and self-documentation - great developer experience due to rich IntelliSense support -- availability of new JavaScript features without current browser support +- availability of new JavaScript features without current browser support. TypeScript also has some disadvantages: @@ -54,7 +54,7 @@ Certain configuration steps are required for enabling TypeScript support in Cust ## TypeScript configuration The [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file is required to work with TypeScript. -It enables numerous [configuration options](https://www.typescriptlang.org/tsconfig). To simplify the initial setup we provide a base `tsconfig.json` file in `@commercetools-frontend/tsconfig` package to extend from in your Custom Application. +It enables numerous [configuration options](https://www.typescriptlang.org/tsconfig). To simplify the initial setup we provide a base `tsconfig.json` file in the `@commercetools-frontend/tsconfig` package to extend from in your Custom Application. ### Installation @@ -68,7 +68,7 @@ npm --save install @commercetools-frontend/tsconfig ### Usage -Create a `tsconfig.json` file in the root directory of your application and add contents: +Create a `tsconfig.json` file in the root directory of your application and add the contents: ```json { @@ -83,7 +83,7 @@ To compile TypeScript files to JavaScript files [Babel](https://babeljs.io/) (si -Custom Applications by default have a preconfigured Babel support to compile TypeScript. +Custom Applications are preconfigured to use Babel compilation to TypeScript. To make sure that Babel configuration is set properly check if `babel.config.js` contains `@commercetools-frontend/babel-preset-mc-app` as a preset, and that the package is listed as the application dependency in `package.json`. @@ -124,11 +124,11 @@ To run prettier as a script add the following contents to your `package.json`: ## ESLint configuration -Custom Applications by default have a preconfigured code linting for TypeScript files with ESLint. +Custom Applications are preconfigured to lint TypeScript files with ESLint. To make sure that ESLint configuration is set properly check if `.eslintrc.js` extends `@commercetools-frontend/eslint-config-mc-app`, and that the package is listed as an application dependency in `package.json`. -To run ESLint as a script edit the contents of `jest.eslint.config.js` configuration file in the root folder of the application: +To run ESLint as a script edit the contents of the `jest.eslint.config.js` configuration file in the root folder of the application: ```js title="jest.eslint.config.js" module.exports = { @@ -185,7 +185,7 @@ Two key recommendations for a successful migration: Please mind that with the recommended `tsconfig.json` configuration any type checking errors will not prevent the compilation, so don't be discouraged by the missing types as the application remains functional. -If the configuration seems too strict to start with it might be loosen up by, for example, allowing explicit `any` type. In such case edit `tsconfig.json`: +If the recommended configuration seems too strict to start with it might be loosen up by, for example, allowing explicit `any` type. In such case edit `tsconfig.json`: ```json title="tsconfig.json" { "extends": "@commercetools-frontend/tsconfig", From 955f86fd7090d5ca2c88dd6d04901b1174913732 Mon Sep 17 00:00:00 2001 From: Kacper Krzywiec Date: Tue, 7 Jun 2022 16:26:38 +0200 Subject: [PATCH 04/13] docs: update typescript setup docs --- website/src/content/development/typescript.mdx | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/website/src/content/development/typescript.mdx b/website/src/content/development/typescript.mdx index 7d764d2f64..3af44c6ca0 100644 --- a/website/src/content/development/typescript.mdx +++ b/website/src/content/development/typescript.mdx @@ -54,16 +54,16 @@ Certain configuration steps are required for enabling TypeScript support in Cust ## TypeScript configuration The [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file is required to work with TypeScript. -It enables numerous [configuration options](https://www.typescriptlang.org/tsconfig). To simplify the initial setup we provide a base `tsconfig.json` file in the `@commercetools-frontend/tsconfig` package to extend from in your Custom Application. +It enables numerous [configuration options](https://www.typescriptlang.org/tsconfig). To simplify the initial setup we provide a base `tsconfig-mc-app.json` file in the `@commercetools-frontend/application-config` package to extend from in your Custom Application. ### Installation ``` -yarn add @commercetools-frontend/tsconfig +yarn add @commercetools-frontend/application-config # or -npm --save install @commercetools-frontend/tsconfig +npm --save install @commercetools-frontend/application-config ``` ### Usage @@ -72,7 +72,7 @@ Create a `tsconfig.json` file in the root directory of your application and add ```json { - "extends": "@commercetools-frontend/tsconfig" + "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json" } ``` @@ -151,12 +151,11 @@ To run ESLint run the following script from your `package.json`: ## Jest configuration -For enabling Jest-based tests in TypeScript `@commercetools-frontend/jest-preset-mc-app` must be a installed as a dependency and configured as below in the `jest.test.config.js` file in the root folder of the application: +For enabling Jest-based tests in TypeScript `@commercetools-frontend/jest-preset-mc-app` must be installed as a dependency and configured as below in the `jest.test.config.js` file in the root folder of the application: ```js title="jest.test.config.js" -const jestPresetForTypeScript = require('@commercetools-frontend/jest-preset-mc-app/jest-preset-for-typescript'); module.exports = { - ...jestPresetForTypeScript, + preset: '@commercetools-frontend/jest-preset-mc-app/typescript', }; ``` @@ -188,7 +187,7 @@ Please mind that with the recommended `tsconfig.json` configuration any type che If the recommended configuration seems too strict to start with it might be loosen up by, for example, allowing explicit `any` type. In such case edit `tsconfig.json`: ```json title="tsconfig.json" { - "extends": "@commercetools-frontend/tsconfig", + "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json", "compilerOptions": { "noExplicitAny": false, "strict": false From 313d933b08b62c90e6b857675738aab85b8c30ca Mon Sep 17 00:00:00 2001 From: Kacper Krzywiec Date: Tue, 21 Jun 2022 14:20:46 +0200 Subject: [PATCH 05/13] docs: improvements --- website/src/content/development/typescript.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/website/src/content/development/typescript.mdx b/website/src/content/development/typescript.mdx index 3af44c6ca0..afc63b5e25 100644 --- a/website/src/content/development/typescript.mdx +++ b/website/src/content/development/typescript.mdx @@ -85,8 +85,6 @@ To compile TypeScript files to JavaScript files [Babel](https://babeljs.io/) (si Custom Applications are preconfigured to use Babel compilation to TypeScript. -To make sure that Babel configuration is set properly check if `babel.config.js` contains `@commercetools-frontend/babel-preset-mc-app` as a preset, and that the package is listed as the application dependency in `package.json`. - `tsc` CLI is only used as a type checking tool, for example, run as `yarn typecheck` script: ```json title="package.json" @@ -126,9 +124,9 @@ To run prettier as a script add the following contents to your `package.json`: Custom Applications are preconfigured to lint TypeScript files with ESLint. -To make sure that ESLint configuration is set properly check if `.eslintrc.js` extends `@commercetools-frontend/eslint-config-mc-app`, and that the package is listed as an application dependency in `package.json`. +To make sure that ESLint configuration is set properly check if `.eslintrc.js` extends `@commercetools-frontend/eslint-config-mc-app`, and that the package is listed as the application dependency in `package.json`. -To run ESLint as a script edit the contents of the `jest.eslint.config.js` configuration file in the root folder of the application: +To run ESLint as a script, edit the contents of the `jest.eslint.config.js` configuration file in the root folder of the application: ```js title="jest.eslint.config.js" module.exports = { From 1629be5aeaaf5fb8c5c7c7f5da88157046b1e7fb Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Wed, 29 Jun 2022 17:53:54 +0200 Subject: [PATCH 06/13] docs: update and improve typescript docs --- recommended.code-workspace | 12 +- .../content/development/adding-typescript.mdx | 95 ++++++++ website/src/content/development/index.mdx | 6 +- .../src/content/development/typescript.mdx | 210 ------------------ website/src/data/navigation.yaml | 4 +- 5 files changed, 105 insertions(+), 222 deletions(-) create mode 100644 website/src/content/development/adding-typescript.mdx delete mode 100644 website/src/content/development/typescript.mdx diff --git a/recommended.code-workspace b/recommended.code-workspace index ce0d89eb34..015d276fc0 100644 --- a/recommended.code-workspace +++ b/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": [ diff --git a/website/src/content/development/adding-typescript.mdx b/website/src/content/development/adding-typescript.mdx new file mode 100644 index 0000000000..5b03373474 --- /dev/null +++ b/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. + + + +This feature is available from version `>= 21.8.0`. + + + +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 +/// +``` + + + +By default, this is included in the TypeScript starter template `src/index.tsx` entry point file. + + + +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 `/**/*.ts` and `/**/*.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). + + + + 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. + + + +* Add a script command `"typecheck": "tsc --noEmit"` in your `package.json` to compile the application. diff --git a/website/src/content/development/index.mdx b/website/src/content/development/index.mdx index c3622f7595..df5b2e5b37 100644 --- a/website/src/content/development/index.mdx +++ b/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. - Learn more about using TypeScript in your Custom Application. + Learn more about developing in your Custom Application in TypeScript. - -Note that Custom Applications in JavaScript are fully functional and porting them to TypeScript is entirely optional. - -If you find TypeScript not beneficial for your Custom Application, you can skip to the next section. - - - -# TypeScript: optional static typing for JavaScript - -[TypeScript](https://www.typescriptlang.org/) is a superset of JavaScript: JS syntax is therefore valid TS. The goal of TypeScript is to help detect errors in code without running it and make development more efficient. Another considerable benefit is enabling a richer IntelliSense within IDEs for a great developer experience. It enables, for example, spotting common mistakes as you type the code, intelligent code completion and hover info. - -TypeScript compiler checks your code and produces the equivalent plain JavaScript code without the type information for browsers to run. - -# Why TypeScript? - -TypeScript's main advantages are: - -- compile-time error checking -- code readability and self-documentation -- great developer experience due to rich IntelliSense support -- availability of new JavaScript features without current browser support. - -TypeScript also has some disadvantages: - -- considerable learning curve -- more code to write and maintain -- certain TypeScript features (for example types based on [generics](https://www.typescriptlang.org/docs/handbook/2/generics.html)) can lead to over-engineered code bases. - -In the end, the decision regarding the adoption of TypeScript must be well-thought-out. - -# Creating a Custom Application in TypeScript from scratch - -You can create a new Custom Application in TypeScript using the `starter-typescript` template. The template can be installed using the `npx` command. Replace `` with the name of the folder where the template should be installed into. - -```bash -$ npx @commercetools-frontend/create-mc-app --template starter-typescript -``` - -# Adding TypeScript support to an existing Custom Application in JavaScript - -Certain configuration steps are required for enabling TypeScript support in Custom Applications: - -## TypeScript configuration - -The [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file is required to work with TypeScript. -It enables numerous [configuration options](https://www.typescriptlang.org/tsconfig). To simplify the initial setup we provide a base `tsconfig-mc-app.json` file in the `@commercetools-frontend/application-config` package to extend from in your Custom Application. - -### Installation - -``` -yarn add @commercetools-frontend/application-config - -# or - -npm --save install @commercetools-frontend/application-config -``` - -### Usage - -Create a `tsconfig.json` file in the root directory of your application and add the contents: - -```json -{ - "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json" -} -``` - -`tsconfig.json` is [easily extensible](https://www.typescriptlang.org/tsconfig#extends) and allows to create your custom configurations. - -To compile TypeScript files to JavaScript files [Babel](https://babeljs.io/) (since version 7) or [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) CLI can be used, but there are certain [differences](https://www.typescriptlang.org/docs/handbook/babel-with-typescript.html) to take into account. - - - - -Custom Applications are preconfigured to use Babel compilation to TypeScript. - -`tsc` CLI is only used as a type checking tool, for example, run as `yarn typecheck` script: - -```json title="package.json" -{ - "scripts": { - ... - "typecheck": "tsc --noEmit" - } -} -``` - - - -## Prettier configuration - -To enable code formatting while typing TypeScript code edit `.prettierrc` configuration file: - -```json title=".prettierrc" -{ - ... - "parser": "typescript" -} -``` - -To run prettier as a script add the following contents to your `package.json`: - -```json title="package.json" -{ - "scripts": { - ... - "format:js": "prettier --write '**/*.{js,ts,tsx}'" - } -} -``` - -## ESLint configuration - -Custom Applications are preconfigured to lint TypeScript files with ESLint. - -To make sure that ESLint configuration is set properly check if `.eslintrc.js` extends `@commercetools-frontend/eslint-config-mc-app`, and that the package is listed as the application dependency in `package.json`. - -To run ESLint as a script, edit the contents of the `jest.eslint.config.js` configuration file in the root folder of the application: - -```js title="jest.eslint.config.js" -module.exports = { - ... - moduleFileExtensions: ['js', 'ts', 'tsx'], - testMatch: ['/**/*.js', '/**/*.ts', '/**/*.tsx'], -}; -``` - -To run ESLint run the following script from your `package.json`: - -```json title="package.json" -{ - "scripts": { - ... - "lint": "jest --config jest.eslint.config.js" - } -} -``` - -## Jest configuration - -For enabling Jest-based tests in TypeScript `@commercetools-frontend/jest-preset-mc-app` must be installed as a dependency and configured as below in the `jest.test.config.js` file in the root folder of the application: - -```js title="jest.test.config.js" -module.exports = { - preset: '@commercetools-frontend/jest-preset-mc-app/typescript', -}; -``` - -Make sure the config file is passed to `jest`: -```json title="package.json" -{ - "scripts": { - ... - "test": "jest --config jest.test.config.js" - } -} -``` - -# Migrating the Custom Application codebase to TypeScript - -Migration of an extensive codebase to TypeScript can be a strenuous task. It should be carefully considered and planned. -[TypeScript documentation](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) can help with setting up a basic plan. - - - -Two key recommendations for a successful migration: -- refrain from introducing functional changes at the same time -- ensure test coverage is sufficient before the migration to confidently progress without regressions - - - -Please mind that with the recommended `tsconfig.json` configuration any type checking errors will not prevent the compilation, so don't be discouraged by the missing types as the application remains functional. - -If the recommended configuration seems too strict to start with it might be loosen up by, for example, allowing explicit `any` type. In such case edit `tsconfig.json`: -```json title="tsconfig.json" -{ - "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json", - "compilerOptions": { - "noExplicitAny": false, - "strict": false - } -} -``` - -Additionally, edit ESLint config file `.eslintrc.js`: -```js title=".eslintrc.js" -module.exports = { - extends: ['@commercetools-frontend/eslint-config-mc-app'], - rules: { - ... - '@typescript-eslint/no-explicit-any': 'off' - }, -}; -``` - - -We advice not to make this change permanent as `any` type does not provide type safety. - - \ No newline at end of file diff --git a/website/src/data/navigation.yaml b/website/src/data/navigation.yaml index 80649463b6..a5c08333f2 100644 --- a/website/src/data/navigation.yaml +++ b/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 From a12fcc5cf8474e7cd12c8d6b5b87a9bd2574947a Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Wed, 29 Jun 2022 18:21:55 +0200 Subject: [PATCH 07/13] docs: typo --- website/src/content/development/adding-typescript.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/content/development/adding-typescript.mdx b/website/src/content/development/adding-typescript.mdx index 5b03373474..a7c9250084 100644 --- a/website/src/content/development/adding-typescript.mdx +++ b/website/src/content/development/adding-typescript.mdx @@ -74,7 +74,7 @@ If you have an existing Custom Application project and would like to migrate it 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. + All UI Kit 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. From 144c3c048fc4fd4c3ea6338e7abe83adec8021b9 Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Wed, 29 Jun 2022 21:31:11 +0200 Subject: [PATCH 08/13] docs: add release note for v21.8 --- ...-frontend-application-shell-connectors.mdx | 28 +++++++++++ website/src/content/getting-started.mdx | 2 + .../src/releases/2022-07/release-v21.8.mdx | 48 +++++++++++++++++++ 3 files changed, 78 insertions(+) create mode 100644 website/src/releases/2022-07/release-v21.8.mdx diff --git a/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx b/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx index 991370cb88..a665e4b4fc 100644 --- a/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx +++ b/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 to access 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 ; + + return ( +
+

Project images regex: {JSON.stringify(imageRegex)}

+
+ ); +} + +function MyApp() { + return ( + + + + ); +} +``` + ### GetProjectExtensionImageRegex Use this component to access the project images configuration, using a `render` prop function. diff --git a/website/src/content/getting-started.mdx b/website/src/content/getting-started.mdx index 1c021de7b5..5e264ff9ad 100644 --- a/website/src/content/getting-started.mdx +++ b/website/src/content/getting-started.mdx @@ -24,6 +24,8 @@ npx @commercetools-frontend/create-mc-app@latest \ --template starter ``` +If you want to start with a [TypeScript](https://www.typescriptlang.org/) project you can use the `--template=starter-typescript` option. Read more about TypeScript in the [Adding TypeScript](/development/adding-typescript) page. + 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. diff --git a/website/src/releases/2022-07/release-v21.8.mdx b/website/src/releases/2022-07/release-v21.8.mdx new file mode 100644 index 0000000000..cf6eb2f624 --- /dev/null +++ b/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 to use correct 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). + + + +# 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'); +``` From 071c808bb9e43f10d74bf4b4f576480d00020ae0 Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Thu, 30 Jun 2022 09:53:34 +0200 Subject: [PATCH 09/13] docs: improvements based on suggestions --- website/src/content/development/adding-typescript.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/website/src/content/development/adding-typescript.mdx b/website/src/content/development/adding-typescript.mdx index a7c9250084..b56389fc17 100644 --- a/website/src/content/development/adding-typescript.mdx +++ b/website/src/content/development/adding-typescript.mdx @@ -55,12 +55,18 @@ By default, this is included in the TypeScript starter template `src/index.tsx` 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: +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 `/**/*.ts` and `/**/*.tsx` in `testMatch`. + + +The TypeScript setup is already preconfigured when using the TypeScript starter template. Consider this document as a reference to match your setup. + + + # 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: From e502be11efda152fccc623b3015506ae5cc65f86 Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Thu, 30 Jun 2022 09:54:19 +0200 Subject: [PATCH 10/13] docs: improve wording --- website/src/content/development/adding-typescript.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/content/development/adding-typescript.mdx b/website/src/content/development/adding-typescript.mdx index b56389fc17..35ba9dad3a 100644 --- a/website/src/content/development/adding-typescript.mdx +++ b/website/src/content/development/adding-typescript.mdx @@ -98,4 +98,4 @@ If you have an existing Custom Application project and would like to migrate it -* Add a script command `"typecheck": "tsc --noEmit"` in your `package.json` to compile the application. +* Add a script command `"typecheck": "tsc --noEmit"` in your `package.json` to run the type checks of the application. From c52c2c51a74542773bd52ac4dfd116734528c5ef Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Thu, 30 Jun 2022 16:53:07 +0200 Subject: [PATCH 11/13] docs: wording improvements Co-authored-by: Stephen Armstrong <77231096+industrian@users.noreply.github.com> --- ...-frontend-application-shell-connectors.mdx | 2 +- .../content/development/adding-typescript.mdx | 22 +++++++++---------- website/src/content/development/index.mdx | 2 +- website/src/content/getting-started.mdx | 2 +- .../src/releases/2022-07/release-v21.8.mdx | 2 +- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx b/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx index a665e4b4fc..3541c437aa 100644 --- a/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx +++ b/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx @@ -217,7 +217,7 @@ This component must be defined in a parent component where children of this comp ### useProjectExtensionImageRegex -A React hook that allows to access the project images configuration. +A React hook that allows accessing the project images configuration. ```jsx highlightLines="4-6" import { useProjectExtensionImageRegex } from '@commercetools-frontend/application-shell-connectors'; diff --git a/website/src/content/development/adding-typescript.mdx b/website/src/content/development/adding-typescript.mdx index 35ba9dad3a..cb02e20c9a 100644 --- a/website/src/content/development/adding-typescript.mdx +++ b/website/src/content/development/adding-typescript.mdx @@ -8,7 +8,7 @@ Custom Applications have full support for developing applications in TypeScript. -This feature is available from version `>= 21.8.0`. +This feature is available from version `21.8.0` onwards. @@ -20,11 +20,11 @@ npx @commercetools-frontend/create-mc-app@latest \ --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. +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 on how to compile the project. +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: @@ -53,7 +53,7 @@ By default, this is included in the TypeScript starter template `src/index.tsx` 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). +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: @@ -69,20 +69,20 @@ The TypeScript setup is already preconfigured when using the TypeScript starter # 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: +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, either `.ts` or `.tsx` (if a file contains JSX syntax). +* Migrate the JavaScript files to TypeScript, using either `.ts` or `.tsx` (if a file contains JSX syntax). - 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. + 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 the migration you might need to loosen up the types strictness, for example by allowing explicit `any` types. + During migration you might need to loosen up the types strictness, for example by allowing explicit `any` types. ```json title="tsconfig.json" { @@ -94,8 +94,8 @@ If you have an existing Custom Application project and would like to migrate it } ``` - Please remember to revert that once the migration is over, as using `any` should be avoided. + You should revert these once migration is complete, as using `any` should be avoided. -* Add a script command `"typecheck": "tsc --noEmit"` in your `package.json` to run the type checks of the application. +* Add the script command `"typecheck": "tsc --noEmit"` to your `package.json` to run the type checks of the application. diff --git a/website/src/content/development/index.mdx b/website/src/content/development/index.mdx index df5b2e5b37..f0f8941d22 100644 --- a/website/src/content/development/index.mdx +++ b/website/src/content/development/index.mdx @@ -53,7 +53,7 @@ In particular, we'll be going through the following topics: title="Adding TypeScript" href="/development/adding-typescript" > - Learn more about developing in your Custom Application in TypeScript. + Learn more about developing your Custom Application using TypeScript. diff --git a/website/src/releases/2022-07/release-v21.8.mdx b/website/src/releases/2022-07/release-v21.8.mdx index cf6eb2f624..d8ce34dea5 100644 --- a/website/src/releases/2022-07/release-v21.8.mdx +++ b/website/src/releases/2022-07/release-v21.8.mdx @@ -16,7 +16,7 @@ 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 to use correct ARIA attributes. +* 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. From ead54944b82aa0953fe069741d2678d43a9b4554 Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Thu, 30 Jun 2022 18:26:04 +0200 Subject: [PATCH 12/13] docs: wording improvements --- website/src/content/api-reference/application-config.mdx | 4 ++-- website/src/content/concepts/integrate-with-your-own-api.mdx | 4 ++-- website/src/releases/2020-06/hostname-migration.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/website/src/content/api-reference/application-config.mdx b/website/src/content/api-reference/application-config.mdx index 277e75b092..a5d6716b78 100644 --- a/website/src/content/api-reference/application-config.mdx +++ b/website/src/content/api-reference/application-config.mdx @@ -623,7 +623,7 @@ You can also pass multiple references to the same value: -This feature is available from version `>= 20.8.0`. +This feature is available from version `20.8.0` onwards. @@ -652,7 +652,7 @@ The reference placeholder assumes that the Custom Application has the translatio -This feature is available from version `>= 20.8.0`. +This feature is available from version `20.8.0` onwards. diff --git a/website/src/content/concepts/integrate-with-your-own-api.mdx b/website/src/content/concepts/integrate-with-your-own-api.mdx index c57d8bf192..c313924ee0 100644 --- a/website/src/content/concepts/integrate-with-your-own-api.mdx +++ b/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 -This feature is available from version `>= 21.8.0`. +This feature is available from version `21.8.0` onwards. @@ -57,7 +57,7 @@ For example, given the forward-to URL `https://my-custom-app.com/api/123`, the ` -This feature is available from version `>= 20.2.0`. +This feature is available from version `20.2.0` onwards. diff --git a/website/src/releases/2020-06/hostname-migration.mdx b/website/src/releases/2020-06/hostname-migration.mdx index a1614a95b9..56946e7402 100644 --- a/website/src/releases/2020-06/hostname-migration.mdx +++ b/website/src/releases/2020-06/hostname-migration.mdx @@ -71,7 +71,7 @@ For example: In production, the `` 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. From d9de2926b24eb7151072a6fe95887a52f9042a17 Mon Sep 17 00:00:00 2001 From: Nicola Molinari Date: Fri, 1 Jul 2022 12:35:51 +0200 Subject: [PATCH 13/13] ci: trigger