@dnbhq/tsconfig

Shared TypeScript configurations for @davidsneighbour's projects.

• Installation
• Included prepared configs
  • Strict baseline
  • CLI apps
  • Astro projects
• Design notes
• Release
• Developer Notes

Installation

npm install --save-dev @dnbhq/tsconfig typescript

It's the consumer's responsibility to install TypeScript as a dev dependency, so that the version can be controlled independently of this package. The peer dependency is set to >=5.8 to allow any modern TypeScript version, but the package MAY use newer features that require a minimum version.

Included prepared configs

Strict baseline

Use this for generic TypeScript projects. Or don't. I personally use this on all my projects, even Astro ones, and then compose it with more specific configs as needed (see below).

{
  "extends": "@dnbhq/tsconfig/strict",
  "include": [
    "src/**/*.ts"
  ]
}

This config is intentionally strict but environment-agnostic. It does not include Node.js types, DOM types, or any other assumptions about the runtime environment. This allows it to be used as a baseline for various project types, including libraries, CLI tools, and Astro projects.

CLI apps

Use this for Node.js CLI tools and scripts.

{
  "extends": "@dnbhq/tsconfig/cli",
  "include": [
    "src/**/*.ts",
    "scripts/**/*.ts"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

It extends the strict baseline and adds Node.js types, as well as settings that are more suitable for CLI applications, such as moduleResolution: "node" and types: ["node"].

Astro projects

Use this for Astro projects using TypeScript.

{
  "extends": "@dnbhq/tsconfig/astro",
  "include": [
    ".astro/types.d.ts",
    "**/*"
  ],
  "exclude": [
    "dist"
  ]
}

It extends the strict baseline and composes it with Astro's own strict config (astro/tsconfigs/strict). This config includes settings that are optimized for Astro projects, such as moduleResolution: "node16" and types: ["astro/client"].

Design notes

The package intentionally does not define include, exclude, or files.

Those settings belong to the consuming project because TypeScript overwrites them during inheritance instead of merging them. The usage examples show how to set those in the consuming projects.

The strict baseline also avoids environment-specific assumptions such as Node.js types, DOM types, JavaScript migration settings, or Astro-specific module resolution.

Release

Dry run:

npm run release:dry

Release:

npm run release

Releases are handled by release-it and @release-it/conventional-changelog. Commit messages MUST follow Conventional Commits. When a tag is pushed to GitHub (e.g. v1.0.0), the release process will automatically generate release on npmjs.org that provides provenance for the release.

Developer Notes

• include, exclude, and files are project-local.TypeScript overwrites them from the consuming config, so the shared package should not define them. (TypeScript)
• Multiple extends are supported since TypeScript 5.0+, but many tools still document or assume a single string. For maximum compatibility, only astro.json uses an array because it needs to compose Astro's own strict config with your strict baseline. (Microsoft for Developers)
• Defaults may not be obvious. Consumers see only their local tsconfig.json, not the full resolved config. Use npx tsc --showConfig in projects when debugging inherited values.
• types is intentionally not in strict.json. Setting types restricts which global @types/* packages are included, so Node types belong in cli.json, not the generic strict baseline. (TypeScript)
• Astro config needs astro installed in the consuming project. astro.json extends astro/tsconfigs/strict, so that path must resolve from the project using the config.
• erasableSyntaxOnly requires a TypeScript version of 5.8+.
• Run tsc --showConfig to see the resulting config after inheritance and merging. This is helpful for debugging and understanding which settings are applied.