# Adding TypeScript

Learn about developing your customizations using TypeScript.

[TypeScript](https://www.typescriptlang.org/) 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:

  ```console noPromptLines="2-3"
  npx @commercetools-frontend/create-mc-app@latest 
    my-new-custom-application-project 
    --template starter-typescript
  ```

- For Custom Views, use the following command:

  ```console noPromptLines="2-4"
  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. To help with this, 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" />
```

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](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`.

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](https://docs.commercetools.com/merchant-center-customizations/development/adding-typescript.md#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](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.

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

## Related pages

- [Section overview page](https://docs.commercetools.com/merchant-center-customizations.md)
- [Previous page: Page titles](https://docs.commercetools.com/merchant-center-customizations/development/page-titles.md)
- [Next page: Going to production](https://docs.commercetools.com/merchant-center-customizations/development/going-to-production.md)