Node.js API Best Practices

Chapter 1 · Practice 4 of 4

Use TypeScript and know the limits of native type stripping

From Project structure and configuration

Why it matters

Node.js runs .ts files directly by stripping types. It is on by default and was marked stable in Node.js 24.12, which removes a build step for many APIs. It has limits you need to know.

  • No type checking. Node only removes types and never checks them, so still run tsc --noEmit in CI.
  • No tsconfig.json. Node ignores it, so path aliases do not work. Use subpath imports starting with # instead.
  • No code generating syntax. enum, runtime namespace and parameter properties throw an error.

Turn on these compiler options so tsc flags problems before Node does:

json
{
  "compilerOptions": {
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

Write import type for type-only imports. Details are in the Node.js TypeScript docs.

Avoid

  • enum and decorators if you run TypeScript natively
  • Skipping the type check because Node runs the file anyway