Minimal Typescript Boilerplate

If you are in fact here to use this code, go ahead and just clone the repository into an existing directory.

npx degit fhollermayer/typescript-starter

Motivation

As a programmer, coming from a language like C# or Java, you are most probably used to a workflow as simple as Start favorite IDE, New Project to run whatever your heart desires. With Typescript or even vanilla JavaScript, that is most often not the case. All the options for pre-compilers, unit-testing frameworks, bundlers, and so on keep you from simply executing a file. More than once, I found myself using https://www.typescriptlang.org/play or https://codesandbox.io/ instead of investing 30 minutes in setting up a simple boilerplate. I finally did it!

Prerequisites

git

Even in the most basic application, I find myself in need of some version management. In most cases The file history and Ctrl + Z is enough, but from time to time, I wish I just would've persisted the last working state: Add everything not excluded via .gitignore and commit.

git add . && git commit -m "no message"

Node Version Manager

If you do or plan to work with Node.js productively, you are sooner or later in need of multiple Node.js versions simultaneously. nvm allows you to install all of them. nvm sets up a SYMLINK from C:\\Program Files\nodejs to %userprofile\.nvm\version\node\.... You can control which version it takes via nvm install --lts or nvm install 16.13.2 and nvm use 16.13.2. Beware: Some Anti-Virus utilities block nvm from unpacking the node directory. In this case get the binaries for nodejs and unzip them directly into the corresponding directory e.g. %userprofile\.nvm\version\node\16.13.2

VSCode

In my opinion, the best choice for JavaScript/TypeScript. It's even available as a web-app at vscode.dev

Optional: WSL

If you are on Windows, Powershell is ofc the superior console, but the internet is more UNIX - it's easier to go with that. Go to "Programs and Features," install the "Windows Subsystem For Linux," add a "Distribution" using the store, and you are good to go. Or just simply use PowerShell to install WSL.

Steps to reproduce

Set up a project

git init && npm init

Create a .gitignore

node_modules

Stage everything and commit the current state

git add . && git commit -m "initializes project"

Add TypeScript

npm i -D typescript @types/node@16

./node_modules/.bin/tsc --init

Create src/index.ts

console.log("It's working!");

You may check if the typescript compiler is working as expected by compiling and executing. Clean up after that.

./node_modules/.bin/tsc --build

node src/index.js

./node_modules/.bin/tsc --build --clean

To get rid of the manual compiling step; Install ts-node, which does in on the fly.

npm i -D ts-node

Update tsconfig.json to use a base config (utilizing @tsconfig/bases)

{
    "extends": "ts-node/node16/tsconfig.json",
    "ts-node": {
        "compilerOptions": {}
    },
    "compilerOptions": {
        /* Visit https://aka.ms/tsconfig.json to read more about this file */
    }
}

Update package.json by adding a convenient entry point.

{
    // ...
    "scripts": {
        "start": "ts-node src/index.ts"
    }
    // ...
}

Admire the convenience by using:

npm run start

git add . && git commit -m "adds typescript support"

---

Unit-Testing

mocha is the test-runner of my choice and chai a compatible assertion library.

npm i -D mocha chai

Both modules originate from the realm of javascript, so no typing in the module itself. @types provides corresponding definition files.

npm i -D @types/mocha @types/chai

mocha does not search for typescript files out of the box. Create a .mocharc.json and override the necessary properties to fix that.

{
    "extension": ["ts"],
    "spec": "**/*.spec.ts",
    "require": "ts-node/register"
}

Being a righteous software developer, you follow the teachings of TDD, so you first write a test file src/index.spec.ts

import {main} from "./index";

describe("main", () => {
    it("runs without error", () => {
        main();
    })
})

Make src/index.ts a module by exporting its functionality and let it fail

export function main() {
    throw new Error("Not implemented yet!");
    // console.log("It's working!");
}

main();

Verify the test failure

./node_modules/.bin/mocha

Fix the module

Update src/index.ts

export function main() {
    console.log("It's working again!");
}

Check you implementation

./node_modules/.bin/mocha

Add a test script to package.json. (Inside the scripts-section npm will save you the effort to add a path-prefix to your executables by automatically searching in ./node_modules/.bin.)

Update package.json

{
    // ...
    "scripts": {
        // ...
        "test": "mocha"
    }
    // ...
}

git add . && git commit -m "adds unit testing"

Documentation