Documentation

This is the new documentation of Custom Applications. You can still visit the legacy documentation during the migration from Project-level Custom Applications.

Adding TypeScript

TypeScript 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:

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:

{
  "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 but we don't recommend to use that unless you are very familiar with the implications of using the types field.

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 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 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.

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