Use TypeScript with the Extensions API

The Extensions API is a JavaScript library. If you author in TypeScript, Tableau provides the Extensions API type definitions (@types) so you can author your extension in TypeScript and enjoy the benefits of type annotations and type-checking. In addition, TypeScript provides support for classes and interfaces, and if you write your source files in Visual Studio, the Tableau Extensions API types provides IntelliSense.

In this section

• Install the Tableau Extensions API TypeScript types
• Import the type definitions
• Set compiler options for type definitions
• Compile your code with the TypeScript compiler
• Use the compiled JavaScript output in your extension
• Related resources

Install the Tableau Extensions API TypeScript types

The Tableau Extension API type definitions are available as an npm @types package.

npm install @tableau/extensions-api-types

Import the type definitions

Import the Extensions API type definitions into your TypeScript code. It is best to only import the modules and interfaces that you need in your code.

For example, to import the module, Parameter, from @tableau/extensions-api-types you would use the following:

import { Parameter } from "@tableau/extensions-api-types";

If you want to use Tableau enumerations as parameters to functions, or as a member variables inside class definitions, you need to import the type definitions from @tableau/extensions-api-types. You can then declare parameters or variables of that type. For example, to be able to use the DataType enum as a parameter to a function, you need to use the following import statement:

import { DataType } from "@tableau/extensions-api-types";

You can then use DataType as a type for a parameter in a class method. You can’t use the fully qualified name as a parameter type (tableau.DataType), even though you can use the fully qualified name within a method.

 private foo(value: DataType) {

 switch (value) {
     case tableau.DataType.String:
         console.log(value);
         break;
     // ... do other things
 }
}

Please note that @tableau/extension-api-types submodules are subject to change. Import only from @tableau/extensions-api-types.

Set compiler options for type definitions

You can set the tsc compiler options in the tsconfig.json file for the project. You can set the typeRoots option to point to the folder that contains the Extensions API type definitions. The following example is used for the sample extensions in the Samples-Typescript folder. In the tsconfig.json file, the typeRoots options includes the ./node_modules/@tableau path. The TypeScript samples use Node.js and webpack to build the extensions.

{
  "compilerOptions": {
    /* Basic Options */
    "target": "esnext",
    "module": "commonjs",
    "sourceMap": true,
    "alwaysStrict": true,
    "baseUrl": "./Samples-Typescript",
    "typeRoots": ["./node_modules/@tableau", "./node_modules/@types"]
  }
}

Compile your code with the TypeScript compiler

If you need to install the compiler, see TypeScript in Visual Studio Code. Visual Studio Code supports TypeScript, but does not automatically include the TypeScript compiler (tsc). The TypeScript compiler transpiles your TypeScript source code to JavaScript. You include the JavaScript output in your extension .html file(s).

Use the compiled JavaScript output in your extension

The TypeScript compiler (tsc) transpiles the source code into JavaScript. You just need to include the path to the JavaScript file in your extension code.

For example, the extensions in the Samples-Typescript folder all link to Extensions API JavaScript library tableau.extensions.1.latest.js and to the compiled JavaScript file for the extension (not the TypeScript source file). In the HTML code for the extensions, the JavaScript files are referenced. The following example, links to the datasources.js file.

<!-- Extensions Library (this will be hosted on a CDN eventually) -->
<script src="../../lib/tableau.extensions.1.latest.js"></script>

<!-- The  extension code (webpack) -->
<script src="../../dist/datasources.js"></script>

Related resources

• TypeScript

• TypeScript in Visual Studio Code

• TypeScript Sample Extensions (GitHub) and Use the TypeScript samples