Setting up TypeScript support in Vaadin

Update. Vaadin 14.5 and later come with built-in TypeScript support. The following steps are only required for 14.4 and earlier.

A while back, I created a small demo project to show that as of Vaadin 14, you can now easily configure your project to support TypeScript in frontend templates.

Giovanni, an active community member, pointed out to me that I didn't really explain the steps needed to get TypeScript working. Instead of burying the steps in a GitHub ticket, I thought I'd write up a quick blog post outlining the steps. Hopefully, this will help others later on.

This guide is tested with Vaadin 14.

In addition to Java, you will need to have Node installed.

Get your Vaadin project ready

If you don't have a Vaadin 14+ project, download a starter at vaadin.com/start.

If you have a Vaadin project running an earlier version of Vaadin, read the migration guide and upgrade the project before continuing.

Run mvn package once to make sure that Vaadin fetches all needed dependencies

Install TypeScript and its Webpack loader

In the project folder, run

npm install --save-dev typescript ts-loader

Configure Webpack to handle TypeScript

Open webpack.config.js and edit the module.export declaration to the following:

module.exports = merge(flowDefaults, {
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.json']
  },
  devtool: 'inline-source-map',
  module: {
    rules: [{
      // Include ts, tsx, js, and jsx files.
      test: /\.tsx?$/,
      exclude: /node_modules/,
      loader: 'ts-loader',
    }],
  }
});

Here, we configure Webpack to run all typescript and JavaScript files through the TypeScript compiler. The reason we're also passing JavaScript files to the TypeScript compiler is that it can transpile newer JavaScript syntax to support older browsers if needed.

Configure the TypeScript compiler

In the project root, add a new file tsconfig.json with the following content

{
  "compilerOptions": {
    "target": "esnext" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017','ES2018' or 'ESNEXT'. */,
    "module": "es2015" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */,
    "declaration": true /* Generates corresponding '.d.ts' file. */,
    "sourceMap": true /* Generates corresponding '.map' file. */,
    "strict": true /* Enable all strict type-checking options. */,
    "moduleResolution": "node" /* Specify module resolution strategy: 'node' (Node.js) or 'classic' (TypeScript pre-1.6). */,
    "allowSyntheticDefaultImports": true /* Allow default imports from modules with no default export. This does not affect code emit, just typechecking. */,
    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
    "experimentalDecorators": true /* Enables experimental support for ES7 decorators. */
  }
}

See the file in the demo for more options you can configure.

Load a TypeScript file from Java

With the configuration taken care of, you can now place TypeScript (.ts) files in the /frontend folder and load them using @JsModule from Java.

/src/main/java/.../LitTemplate.java

@Tag("lit-template")
@JsModule("./src/lit-template.ts")
public class LitTemplate extends Component {
//...
}

That's it.

You can check out the complete demo source here: https://github.com/marcushellberg/vaadin-lit-typescript/

If you have any questions, post them below or reach out to me on Twitter @marcushellberg