Using Typescript

From 3.1.0, QuickBrick has tooling to support using Typescript to build plugins.

Prerequisites

you will need typescript installed on your machine, by running npm i -g typescript

Workspace configuration

Once your workspace is ready with the basic configuration, you can add the typescript configuration in your package and the the workspace.

  1. In your workspace root
  • add @types declaration you need
  • create a tsconfig.json file at the root of your workspace to provide the references for the type declarations
{
"compilerOptions": {
"typeRoots": ["node_modules/@types"]
}
}
  • in your package.json, add an applicaster.moduleMap to allow the development-app to use your source code instead of the compiled code declared in your package's package.json file. the path is relative from development-app so it should start with .. up to the src folder containing your index.ts(x) file in your plugin. the key is the name of the package, as it is used in require or import statements
{
/* ... */
"applicaster": {
"moduleMap": {
"my-ts-plugin": "../plugins/my-ts-plugin/src"
// require("my-ts-plugin") will be mapped to to `require("../plugins/my-ts-plugin/src")`
}
}
}
  1. In your typescript plugin
  • Add a tsconfig.json with your typescript compiler options
  • Add a build script in your package.json, called in the prepack hook to build your typescript code when publishing your plugin. Usually it will simply invoke the typescript compiler:
{
"name": "my-ts-package",
"scripts": {
"build": "tsc",
"prepack": "npm run build"
}
}
  • Make sure your package.json's main property is pointing to the transpiled code.

That's it ! With this setup, you can run the Quick Brick from your workspace, and write plugins using typescript

Accessing applicaster types declarations

Typescript types declaration usually come from two sources:

  • the modules themselves contain the signatures & typedefs for their classes and functions
  • other types & interfaces, as well as types relevant for non typescript projects are usually found in @types/... packages. Those packages must be pushed, approved and deployed through https://github.com/DefinitelyTyped/DefinitelyTyped

Since we are gradually building these type declarations, we created our own package for type definitions, which we can publish on our own, instead of relying on a process controled by a third party. Ultimately, we do want to provide a @types/applicaster package, but for now, we choose to rely on a package of our own.

The only difference is that these custom packages are not resolved automatically out of the box by the typescript compiler. If you want to rely on these types, you can do the following:

  • add @applicaster/applicaster-types package as a dev dependency to your plugin
  • in each file, add a triple-slash directive to reference these styles definitions:
/// <reference types="@applicaster/applicaster-types" />