My TypeScript recommendations and cheatsheet

TypeScript official config reference is overwhelming to say the least. It includes many flags that were introduced and deprecated over the years. Standards and practices have evolved and it’s hard to keep up with the pace of changes.

The Fast Track if you’re in a hurry

I wrote a command line interface that helps you setup TypeScript quickly with a few interactive prompts:

npx simplefrontend setup typescript

This CLI can do a bit more, you can read about it here.

Server apps, librairies and local script

Getting started with good TypeScript configuration defaults

I will provide you with configurations that enable very simple and fast development and production setups. These recommendations are build on top of a good set of good and strict standards.

For server applications, librairies and local scripts, I’ve been using tsconfig/bases from Orta for a while now and that helps both abstract some of the baseline recommendations and keep up with the ecosystem changes especially to know which lib to target for which node versions.

So I’d recommended the following:

1. Install TypeScript config dependencies:

• @types/node to get type definitions for Node.JS .
• @tsconfig/node-lts to target the latest Node.JS long-term support version, you can also target different versions if you need.
• @tsconfig/strictest to start with the strictest baseline.

2. Update your package.json file to make use of the ES module syntax with the following:

    "type": "module"

3. a) For a server configuration or local scripts, use the following tsconfig.json

{
  "extends": [
    "@tsconfig/node-lts/tsconfig.json",
    "@tsconfig/strictest/tsconfig.json"
  ],
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",

    "types": ["node"],

    "moduleDetection": "force",
    "verbatimModuleSyntax": true,
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,

    "sourceMap": true,

    "forceConsistentCasingInFileNames": true,
    "noUncheckedSideEffectImports": true,
  },
  "include": ["./src"],
}

3. b) For a library, use the following tsconfig.json

{
  "extends": [
    "@tsconfig/node-lts/tsconfig.json",
    "@tsconfig/strictest/tsconfig.json"
  ],
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist",

    "moduleDetection": "force",
    "verbatimModuleSyntax": true,
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,

    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    "forceConsistentCasingInFileNames": true,
    "noUncheckedSideEffectImports": true,
  },
  "include": ["./src"],
}

These configurations allow a simple and fast development and production setups thanks to Node.JS type erasure with the following package.json scripts:

  "scripts": {
    "dev": "node --watch src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js"
  }

Here are some explanations and reasoning for my recommendations:

• include to make sure you’re not including uneeded files which would slow down the compilation.
• moduleDetection set to “force” to make TypeScript consider all files as modules which help catch more errors.
• verbatimModuleSyntax to help provide stronger guarantees on imports and prevent potential erroneous side effects on type imports.
• rewriteRelativeImportExtensions is a bit more opinionated: it makes things less indirect for me and simplifies the pure Node.JS development setup.
• erasableSyntaxOnly is also quite opinionated: it forces you to write TypeScript code which is easy to erase to run valid JavaScript. You then cannot use new constructs such as enums but I believe it’s a worthy trade-off as those are features I would not recommend to use anyway.
• forceConsistentCasingInFileNames and noUncheckedSideEffectImports are stricter best practices.

Client apps

Given the variety and complexity of client side setups, I recommend to follow the configurations starters for Vite starters which you can find here. They provide the latest best-in class TypeScript configuration recommendations you can extend to make stricter with some of the options I recommended above.