Documentation

Adding TypeScript

Learn about developing your customizations using TypeScript.

TypeScript is a typed superset of JavaScript that compiles to plain JavaScript.

Customizations have full support for developing applications in TypeScript.

This feature is available from version 21.8.0 onwards.

To start a new Custom Application project with TypeScript, you can use the TypeScript starter template.

  • For Custom Applications, use the following command:

    npx @commercetools-frontend/create-mc-app@latest \
      my-new-custom-application-project \
      --template starter-typescript

  • For Custom Views, use the following command:

    npx @commercetools-frontend/create-mc-app@latest \
      my-new-custom-view-project \
      --application-type custom-view \
      --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:

{
  "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:

/// <reference types="@commercetools-frontend/application-config/client" />

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. However, we don't recommend doing so unless you are familiar with the implications of using the types field.

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.

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 customization project and want to migrate to TypeScript, you can do the following:

  • Install the typescript dependency.

  • Add a tsconfig.json file. See configuration for the tooling setup.

  • 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 working up to the application entry point. The migrating from JavaScript documentation 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.

    tsconfig.jsonjson
    {
      "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.

  • Add the script command "typecheck": "tsc --noEmit" to your package.json to run the type checks of the application.