PhpStorm 2016.3 Help

Transpiling TypeScript to JavaScript

On this page:

Introduction

TypeScript code is not processed by browsers that work with JavaScript code. Therefore to be executed, TypeScript code has to be translated into JavaScript. This operation is referred to as transpilation and the tools that perform it are called transpilers.

In addition to this, transpilation also can involve generation of source maps that set correspondence between lines in your TypeScript code and in the generated JavaScript code, otherwise your breakpoints will not be recognised and processed correctly.

In PhpStorm, TypeScript code is transpiled into JavaScript using the built-in TypeScript compiler.

Configuring and activating the built-in TypeScript compiler

  1. Open the Settings / Preferences Dialog by pressing Ctrl+Alt+S or by choosing File | Settings for Windows and Linux or PhpStorm | Preferences for OS X, and click Typescript under Languages & Frameworks.
  2. On the TypeScript Compiler page that opens, select the Enable TypeScript Compiler check box to activate the compiler. When the check box is selected, syntax highlighting and code completion are provided based only on the data from the built-in Typescript compiler. After you select this check box, the fields below in the area become active and you can configure the behaviour of the compiler. By default, the check box is cleared.
  3. To have the compiler "wake up" upon any change to a TypeScript file, select the Track changes check box.

    When this check box is cleared, the built-in compiler ignores changes to TypeScript files. To re-activate the compiler, open the TypeScript Compiler Tool Window (View | Tool Windows | TypeScript Compiler), and click the Compile All button icon_ts_compile_all on the toolbar.

    If you have not opened the TypeScript Compiler Tool Window yet and it is not available from the View menu, choose Help | Find Action, then find and launch the TypeScript Compile All action from the list.

  4. In the other fields of the TypeScript Compiler page, specify the following:
    • In the Node interpreter field, specify the location of the Node.js executable file. In most cases, PhpStorm detects the Node.js executable and fills in the field automatically.
    • In the TypeScript version area, specify the version of the compiler to use (PhpStorm displays the currently chosen version):
      1. Click Edit.
      2. In the Configure TypeScript Compiler dialog box that opens, choose one of the following options:
        • Detect: if you choose this option, PhpStorm searches fir a typescript package in the current project. If a typescript package is found, PhpStorm uses it. Otherwise the default bundled package is used. This option is chosen by default.
        • Bundled: if you choose this option, PhpStorm uses it without attempting to find another typescript package.
        • Custom directory: choose this option to use a custom version of the compiler. In the text box, specify the location of the typescriptServices.js, lib.d.ts, and lib.es6.d.ts files downloaded from https://github.com/Microsoft/TypeScript/.
    • From the Scope drop-down list, choose the scope to apply the compiler in. The available options are:
      • Project Files: all the files within the project content roots (see Content Root and Configuring Content Roots).
      • Project Production Files: all the files within the project content roots excluding test sources.
      • Project Test Files: all the files within the project test source roots.
      • Open Files: all the files that are currently opened in the editor.

      VCS Scopes: these scopes are only available if your project is under version control.

      • Changed Files: all changed files, that is, all files associated with all existing changelists.
      • Default: all the files associated with the changelist Default.
      Alternatively, click the Browse button and configure a custom scope in the Scopes dialog box that opens. For more details on scopes, see the pages Scopes and Scopes dialog.
    • Choose the Set options manually to configure transpilation manually:
      • In Command line options field, specify the command line options to be passed to the compiler. See the list of acceptable options at TSC arguments. Note that, the -w or --watch option (Watch input files) is irrelevant.
      • Select the Generate source maps check box to generate source maps that set correspondence between lines in your TypeScript code and in the generated JavaScript code, otherwise your breakpoints will not be recognised and processed correctly.
      • Select the Compile main file only check box to have PhpStorm compile only a specific file and the files that are referenced from it and ignore all the other files in the project. This may be helpful if you have a dedicated main.ts file which only references other files.
      • Select the Use output path check box to have the built-in compiler store the generated JavaScript files and source map in a custom folder. Specify the path to this folder explicitly or use one of the listed available macros in the format: $<macros_name>$. The available macros are:
        • FileDir: the path to the folder where the file is stored.
        • FileRelativeDir: the path to the file directory relative to the project root.
        • FileDirRelativeToProjectRoot: the path to the file directory relative to the project root.
        • ModuleFileDir: the path to the project root folder.
        • SourcePath: the path to the source folder under the content root to which the file belongs, see Configuring Content Roots and Configuring Folders Within a Content Root.
        • FileDirRelativeToSourcePath: the path to the file relative to the source folder under the content root to the file belongs.
    • Choose the Use tsconfig.json option, have the built-in compiler analyze the code according to the settings specified in the tsconfig.json file. When you open a project, PhpStorm starts searching for a tsconfig.json file in it. If a tsconfig.json file is found, the compiler uses the options specified in it. Otherwise an error is reported.

Transpiling TypeScript using the built-in compiler

  1. To activate a previously configured built-in transpiler, select the Enable TypeScript Compiler check box on the TypeScript Compiler page.

    Alternatively, use the buttons on the pane which PhpStorm displays when you open a TypeScript file.

    • To enable an already configured compiler, click Enable.
    • To configure a compiler, click Configure and specify the settings on the TypeScript Compiler page that opens.
    • To leave the compiler disabled and suppress showing the pane in the future, click Dismiss, whereupon the compiler can be later activated only on the TypeScript Compiler page.

  2. View the errors detected during compilation, compile separate files and the entire project in the TypeScript Compiler Tool Window. If you have configured the compiler to track changes, which is the default behaviour, the tool window opens automatically as soon as you start editing a TypeScript file.

    If tracking changes is disabled and you have closed the tool window, to re-open it choose View | Tool WIndows | TypeScript Compiler.

    • Click the Compile Current File toolbar button icon_ts_compile_current_file.png to run the compiler against the entire file opened in the active editor tab. This approach is helpful if you do not want the compiler to wake up on any change as you edit your code and for this purpose the Track Changes check box on the TypeScript page of the Settings dialog box is cleared.

      If you click this button from the Project Errors pane, after compilation PhpStorm switches to the Current Errors pane.

    • Click the Compile All toolbar button icon_ts_compile_all.png to run the compiler against all the TypeScript files in the current project. If you click this button from the Current Errors pane, after compilation PhpStorm switches to the Project Errors pane.
    • To clear the contents of the current pane, click the Clear All toolbar button /help/img/idea/2016.3/clear_all.png.
    • To navigate to the fragment of code where an error occurred during compilation, select the error message in question and choose Jump to Source on the context menu of the selection.

The compiler stores the generated output in a separate file. The JavaScript file has the name of the source TypeScript file and the extension js, the source map file has the name of the source TypeScript file and the js.map extension. In the Project Tree, the files are shown under the source TypeScript file which is now displayed as a node. This presentation is preserved even if you turn off the compiler during a PhpStorm session.

Running the built-in TypeScript compiler as a before-launch task

You can run the built-in compiler before launching a run configuration to make sure that all the changes you made to your TypeScript code are reflected in the generated JavaScript files.

  1. Check whether the compiler is activated on the TypeScript Compiler page, see Transpiling TypeScript to JavaScript above.
  2. Open the Run/Debug Configurations dialog by choosing Run | Edit Configurations on the main menu, and select the required configuration from the list or create it anew by clicking /help/img/idea/2016.3/new.png and choosing the relevant run configuration type.
  3. In the dialog box that opens, click /help/img/idea/2016.3/new.png in the Before launch area and choose Compile TypeScript from the drop-down list.
  4. In the TypeScript Compile Settings dialog that opens, select or clear the Check errors check box to configure the behaviour of the compiler in case any errors are detected:
    • If the Check errors check box is selected, the compiler will show all the errors and the run configuration will not start.
    • If the Check errors check box is cleared, the compiler will show all the detected errors but the run configuration still will be launched.

See Also

Last modified: 1 December 2016