typescript: setting up a project

I was working on a small kata to set up a Node CLI to run with Typescript and actually have debugging capabilities. I ran into a road block with the very first step: getting Typescript implemented. Setting up Typescript is something I’ve done on multiple occasions… but it turns out I never wrote down the basic steps (though I alluded to them when I wrote about tsconfig templates).

So, the very basic steps to get Typescript installed and configured on your project (with a lot of opportunities afterward for customizations)¹:

1. Initialize your project

   yarn init

2. Install Typescript

   yarn add --dev typescript

3. Initialize Typescript

   ./node_modules/.bin/tsc --init

   This will create the default tsconfig.json I described in my previous post about tsconfig templates. From here you can customize to your heart’s desire. This is technically all you need, however a few more steps might be helpful.

   One of the more useful settings is setting an outdir to dist or something distinct. This will make sure that when Typescript transpiles into Javascript, it places all of the files in a separate directory.

4. Add a Build script

   Instead of always having to reach into node_modules to access the Typescript binary, we can create a script within package.json to make this more ergonomic:

   package.json

   {
     "scripts": {
       "build": "tsc"
     }
   }

   A slightly more involved approach might combine a few different ideas:

   package.json

   {
     "scripts": {
       "build": "rimraf dist && npm run build:types && npm run build:js",
       "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
       "build:js": "babel src --out-dir dist --extensions \".ts,.tsx\" --source-maps inline --ignore \"**/*.test.*\""
     }
   }

   • rimraf removes the dist file before each build so that we always work with a clean directory.

   • Typescript is responsible for building the types (only emitting the type declarations). In this case, I also have a separate tsconfig for building which ignores test files:

     tsconfig.build.json

     {
       "extends": "./tsconfig.json",
       "exclude": ["**/*.test.ts"]
     }

     We didn’t need to specify tsconfig.json because that’s the default value and Typescript will look for that unless told otherwise.

   • Babel, using the @babel/preset-typescript preset, will handle the transpilation and compilation.

Footnotes

• ¹ The only real decision I’ll prescribe is to not use a global installation of Typescript (more of my thoughts on Global Node packages here).