Skip to content
Skills Library
Programming · Building & coding

configuring-typescript-for-nodejs

/configuring-typescript-for-nodejs

Configures TypeScript for Node.js server projects: which version to pin, the tsconfig baseline for a Node-resolved runtime, and the decorator-metadata settings NestJS and TypeORM require. Use when starting a Node service, editing a server tsconfig, diagnosing emitDecoratorMetadata or class-field problems, or upgrading TypeScript in a backend.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Configures TypeScript for Node.js server projects: which version to pin, the tsconfig baseline for a Node-resolved runtime, and the decorator-metadata settings NestJS and TypeORM require. Use when starting a Node service, editing a server tsconfig, diagnosing emitDecoratorMetadata or class-field problems, or upgrading TypeScript in a backend.

Original author description

Configures TypeScript for Node.js server projects: which version to pin, the tsconfig baseline for a Node-resolved runtime, and the decorator-metadata settings NestJS and TypeORM require. Use when starting a Node service, editing a server tsconfig, diagnosing emitDecoratorMetadata or class-field problems, or upgrading TypeScript in a backend.

How it works

  1. When to Use
  2. Applicability and Precedence
  3. Non-negotiable Rules
  4. Reference Loading
  5. Procedure
  6. Related Skills
Original SKILL.md headings · 111 lines, 1,078 words
SKILL.md preview
---
name: configuring-typescript-for-nodejs
description: "Configures TypeScript for Node.js server projects: which version to pin, the tsconfig baseline for a Node-resolved runtime, and the decorator-metadata settings NestJS and TypeORM require. Use when starting a Node service, editing a server tsconfig, diagnosing emitDecoratorMetadata or class-field problems, or upgrading TypeScript in a backend."
when_to_use: "Trigger on: setting up tsconfig.json for a Node service, module or moduleResolution nodenext questions, experimentalDecorators or emitDecoratorMetadata problems, useDefineForClassFields breaking dependency injection or TypeORM entities, CommonJS to ESM questions forced by a resolution change, or an upgrade of the pinned TypeScript version in a backend repo."
paths:
  - "**/tsconfig*.json"
  - "**/*.ts"
  - "**/*.mts"
  - "**/*.cts"
  - "**/nest-cli.json"
---

# Configuring TypeScript for Node.js

TSH's recommended TypeScript setup for code that runs **on Node**: which version
to pin, the `tsconfig.json` baseline for a Node-resolved runtime, and the
decorator and class-field settings NestJS, TypeORM, and `class-validator` depend
on.

This skill is about **configuration**. How to model types — unions, branded
types, `unknown` over `any` — is out of its scope. Browser-targeted code is out of
scope too: a bundler-resolved frontend needs a different baseline, so a repo with
both compiles them as separate configs.

## When to Use

- Setting up `tsconfig.json` for a new Node service, or reviewing an existing one
- Choosing the TypeScript version for a Node project, or justifying the pinned one
- Deciding `target`, `module`, and `moduleResolution` for a deployed Node major
- Diagnosing decorator, DI, or reflection behavior that changed under a flag
- Moving a Node project from CommonJS to ESM
- Upgrading TypeScript and triaging the resulting errors

## Applicability and Precedence

Read the target repository's `tsconfig.json` (and anything it extends),
`package.json`, and build tooling before proposing anything. **Local conventions
outrank this skill's defaults.** Apply this guidance where the repository is
silent, and record a deliberate deviation rather than silently mixing conventions.

**The baseline below is a recommendation for new projects, not a verdict on
existing ones.** A working `tsconfig.json` that differs from it is not a defect.
In an existing repo, propose the smallest staged change that serves the task at
hand and read
[`adopting-in-a-brownfield-project.md`](./references/adopting-in-a-brownfield-project.md)
before proposing anything wider.

Framework requirements outrank this skill. NestJS and TypeORM constrain decorator
and class-field settings in ways that override general recommendations; where a
framework skill and this one disagree, the framework skill wins for the files it
owns.

## Non-negotiable Rules

| Severity | Rule |
| --- | --- |
| MUST | Treat this baseline as a recommendation for new projects. In an existing repo, propose the smallest staged change and record the remaining gap — never rewrite a working `tsconfig.json` wholesale to match this skill. |
| MUST | Enable `strict`. A project that cannot turn it on wholesale enables the individual flags progressively and records the remaining gap — never ships `strict: false` as a permanent state. |
| MUST | Pin an exact TypeScript version in `devDependencies` (no `^`). TypeScript does not follow semver — patch and minor releases add errors to previously compiling code. |
| MUST | Set `module` and `moduleResolution` to `node16`/`nodenext` (or `node20` on a current Node). Never leave the legacy `node`/`node10` resolver in a new project — it predates `package.json` `exports` and silently resolves the wrong entry point. |
| MUST | Set `useDefineForClassFields` **explicitly** in any project using decorators, and `false` for NestJS, TypeORM, and `class-validator` codebases. Left implicit, it flips with `target` and silently overwrites injected fields. |
| NEVER | Enable `verbatimModuleSyntax` in a project relying on `emitDecoratorMetadata` without verifying at runtime first — it elides type-only imports the metadata emit still needs. The failure is a runtime `undefined`, not a compile error. |
| NEVER | Enable `erasableSyntaxOnly` in a decorator-DI project without first converting every constructor parameter property to an explicit field assignment. It bans the idiomatic NestJS DI style outright. |
| MUST | Type-check in CI as its own step. A build that only transpiles (SWC, esbuild, `tsx`, Babel) does not check types; without a separate `tsc --noEmit`, type errors reach production. |
| MUST | Run the application — not just `tsc --noEmit` — after changing any emit-affecting option (`target`, `useDefineForClassFields`, `verbatimModuleSyntax`, `experimentalDecorators`). A green type-check cannot see this class of failure. |
| MUST | Treat a `@ts-expect-error` as debt: it carries a comment explaining the cause and the condition for removal. Prefer it over `@ts-ignore`, which silently rots when the error disappears. |

## Reference Loading

| Reference | Load when | Covers |
| --- | --- | --- |
| [Compiler options for Node.js](./references/compiler-options-for-nodejs.md) | Writing or reviewing a Node `tsconfig.json` | The baseline config, strictness ladder, `target`/`module`/`moduleResolution` for a deployed Node, `types`, emit and output layout, transpile-only runners |
| [Decorators and metadata](./references/decorators-and-metadata.md) | Decorators, DI, or runtime reflection are involved | Legacy vs standard decorators, `emitDecoratorMetadata`, `useDefineForClassFields`, `verbatimModuleSyntax`, `erasableSyntaxOnly`, framework baselines, diagnosing `undefined` injections |
| [Version and upgrades](./references/typescript-version-and-upgrades.md) | Choosing, justifying, or raising the TypeScript version | Version policy, what each recent major added, the upgrade procedure, per-major breaking changes, CommonJS to ESM |
| [Adopting in a brownfield project](./references/adopting-in-a-brownfield-project.md) | The repo already has a working config that differs from the baseline | Staged adoption order, ratcheting, per-flag sequencing, recording a deviation, when to leave a config alone |

## Procedure

**Step 1 — Read the ground truth.** Open `tsconfig.json` and every config it
extends, the `typescript` entry in `package.json`, the `engines` field or CI image
that fixes the Node version, and the build and test runners. Note the current
version, strictness, `target`, `module`, `moduleResolution`, and whether
decorators are in use before proposing anything.

**Step 2 — Decide greenfield or brownfield.** A new project takes the baseline as
written. An existing project gets the smallest staged change — read
[`adopting-in-a-brownfield-project.md`](./references/adopting-in-a-brownfield-project.md)
first.

**Step 3 — Load the relevant references.** Read
[`compiler-options-for-nodejs.md`](./references/compiler-options-for-nodejs.md)
before editing any `tsconfig.json`, and
[`decorators-and-metadata.md`](./references/decorators-and-metadata.md) before
touching a project that uses decorators. Those two account for most of the ways a
"harmless" config change breaks a running service.

**Step 4 — Establish the version baseline.** Confirm the TypeScript version is
pinned exactly and supported by the frameworks in `peerDependencies`. If the
change requires a newer version, treat the upgrade as its own step with its own
verification, not as a side effect.

**Step 5 — Apply the smallest change.** Prefer the narrowest edit that achieves
the goal. Whenever a proposed flag alters emit, say so explicitly in the same
breath as proposing it.

**Step 6 — Verify.** Run `tsc --noEmit` and the test suite. For any
emit-affecting flag, also start the application and exercise a DI-heavy path: a
passing type-check does not prove the runtime still wires up.

## Related Skills

- [`implementing-nestjs-api`](../implementing-nestjs-api/SKILL.md) — ships in this
  same plugin, so it is always available alongside this skill. It owns the NestJS
  module, CQRS, TypeORM, and REST guidance that sits on top of the compiler
  configuration here.
- `tsh-product-engineering` — TSH's discipline-level implementation and review
  workflows, independent of language. Optional; treat it as a bonus, never a
  prerequisite.

This skill does not configure browser or bundler builds, and does not cover type
modelling, linting, or formatting.
Files in this package (5)
  • SKILL.md 8 KB
  • references/adopting-in-a-brownfield-project.md 7 KB
  • references/compiler-options-for-nodejs.md 12 KB
  • references/decorators-and-metadata.md 9 KB
  • references/typescript-version-and-upgrades.md 15 KB

Versions

The database has no other skills named configuring-typescript-for-nodejs.

Database snapshot: 13.11.2026 · package version f32e2f79689a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90configuring-typescript-for-frontend
    Configures TypeScript for browser-targeted frontend projects: which version to pin, the tsconfig baseline for a bundler-resolved app, and the React + Vite project layout. Use when starting a frontend project, editing a frontend tsconfig, diagnosing JSX or module-resolution…
  • 100nestjs
    NestJS is a TypeScript framework for building server-side Node.js applications with modules, dependency injection, controllers, guards and pipes. Use when creating a NestJS REST API, adding validation, JWT guards, TypeORM or tests, or upgrading a NestJS 11 project to 12.
  • 100typescript
    Sets up and repairs TypeScript projects: picks tsconfig.json settings for a Node.js service, an npm library or a bundled web app, runs type-checking in CI, and replaces `any` and unsafe casts with types the compiler can verify. Use when someone asks to "set up TypeScript", "fix…
  • 90node-typescript-backend
    Build production Node.js/TypeScript backends (Fastify, NestJS, Express): structure, validation, async, errors, config, testing, performance. Use when writing or reviewing Node/TS services or APIs.
  • 100nodejs-backend
    Node.js backend patterns: layered architecture, TypeScript, validation, error handling, security, observability, logging, metrics, deployment. Use when building REST APIs, REST endpoints, middleware, Express/Fastify/Hono/NestJS/Koa servers, tRPC procedures, Bun servers, or server-side TypeScript.
  • 100implementing-nestjs-api
    Guides implementation and review of NestJS 11 REST APIs with TypeScript, @nestjs/cqrs, TypeORM 0.3, and @nestjs/platform-express. Use when bootstrapping a service, organizing vertical feature slices, adding CQRS behavior, or implementing and reviewing REST API changes.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.