Skip to main content

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.

note

If you want to examine and use TypeScript versions of several of the sample extensions in the Samples folder, see Samples-Typescript (GitHub) and follow the instructions to Use the TypeScript Samples.

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
note

The version of the types package must match the version of the Extensions API library you are using. You can specify the library version by appending the version number to the package name (@n.n.n). For example, npm install @tableau/extensions-api-types@1.3. You only need to match major and minor versions (for example, types 1.3.1 works with any 1.3.x version of the extensions library). If you don't specify a version number, npm will install the latest released package.

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>