Cookielab's TypeScript Configuration

This package contains the TypeScript configuration for our code style.

The code style aims to be as astrict and defensive as possible to avoid bugs & unwanted side-effects and to improve code readability.

The ruleset is inspired by the Tiger Style coding principles and pretty much boils down to the following core principles:

1. Security
   1. A.k.a. eing proactive about bugs instead of reactive
2. Performance
3. Developer Experience
   1. Explicit over implicit code
   2. Consistent code style

Updating TypeScript & Configuration Versions

TypeScript >=6.0.0 & Configuration >=0.1.0

The following options were deprecated by TypeScript and will not be part of the configuration going forward:

1. downlevelIteration
2. outFile
3. alwaysStrict
4. baseUrl
5. esModuleInterop
6. allowSyntheticDefaultImport

In case your @types/* packages are not recognized by the TypeScript compiler, they will have to be added into your tsconfig.json. TypeScript has stopped automatically loading every @types/* package starting with version 6.0.0. A simple example of registering @types/node would be:

{
  "compilerOptions": {
    "types": ["node"]
  }
}

Versioning

For TypeScript versions <6.0.0, the configuration versions of 0.0.X are recommended. Starting with 0.1.0, many compilerOptions were removed with the major release and will not be maintained in the future versions of the configuration.

The 0.0.X configuration versions will still be maintained to provide compatibility for older TypeScript versions.

Documentation

As the configuration only handles compilerOptions, the reasoning behind each setting can be found in compilerOptions.

Installation

First add the package as a development dependency using your package manager of choice.

pnpm add -D -E @cookielab/typescript-config

Then extend your tsconfig.json using the extends directive:

{
  "extends": "@cookielab/typescript-config"
}

Do not forget to add includes or other necessary settings for your project - this configuration handles only the compiler options. The full configuration file may look something like this:

{
  "extends": "@cookielab/typescript-config",
  "includes": ["src/", "test/"]
}

Development

The project uses an autogenerated Zod schema from schemastore.org (https://json.schemastore.org/tsconfig). However, as Zod does not support generating schemas directly from JSON Schema, we use two convertors in between.

Firstly, the JSON schema in tsconfig.schema.json is converted into TypeScript types.

Afterward, the TypeScript types are then converted into a Zod schema. See the generated output for more details. Surprisingly enough, even the comments from the JSON Schema are preserved in the final Zod schema.

To generate a newer version of the configuration follow these steps:

pnpm schema:update # Downloads the latest version from schemastore.org into ./src/tsconfig.schema.json
pnpm schema:generate # Generates the Zod schema from ./src/tsconfig.schema.json

The project is type checked with the output configuration. To get an up-to-date results, build the project first

pnpm build
pnpm types