typescript-project-setup

name	typescript-project-setup
description	Guides expert-level TypeScript project configuration: tsconfig.json with strict mode, path aliases, declaration file generation, composite projects for monorepos, and ESM configuration. Covers the decisions that determine type safety and developer experience. Use when the user asks about setting up a TypeScript project, configuring tsconfig.json, setting up path aliases, composite projects, or TypeScript build configuration. Do NOT use when the user asks about TypeScript type patterns (use `typescript-type-patterns`), runtime validation (use `typescript-runtime-safety`), or Node.js setup (use `nodejs-project-setup`).
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"typescript best-practices template","category":"software-engineering","subcategory":"languages-runtimes","depends":"","disclaimer":"none","difficulty":"intermediate"}

TypeScript Project Setup

When to Use

Use this skill when:

• The user is initializing a new TypeScript project and needs a tsconfig.json configured from scratch -- including a library, application, CLI tool, or monorepo package
• The user is experiencing module resolution errors such as "Cannot find module" or "File is not a module" and needs to understand how moduleResolution settings interact with their runtime or bundler
• The user wants to configure path aliases (@/components, ~utils) and needs both the TypeScript and the runtime/bundler sides of that configuration
• The user is setting up a monorepo (Turborepo, Nx, pnpm workspaces) and needs composite projects, project references, and shared base configs for incremental builds
• The user is building a publishable npm library and needs correct declaration file generation, declarationMap, rootDir/outDir pairing, and proper package.json exports field alignment
• The user is migrating an existing JavaScript project to TypeScript and needs a phased allowJs/checkJs migration strategy
• The user is configuring TypeScript for ESM output with Node.js 18+ and needs to understand .js extension requirements in imports, "type": "module" in package.json, and node16/nodenext resolution
• The user asks about tsc --build (project references), watch mode performance, or build output caching with TypeScript

Do NOT use this skill when:

• The user wants TypeScript type system patterns (generics, conditional types, mapped types, template literal types) -- use typescript-type-patterns
• The user wants runtime validation (Zod, Valet, class-validator, io-ts) to complement TypeScript's compile-time types -- use typescript-runtime-safety
• The user wants Node.js-specific project setup beyond TypeScript configuration (package.json structure, scripts, ESLint, Prettier, CI) -- use nodejs-project-setup
• The user is asking about testing configuration (Jest, Vitest, ts-jest, type testing with expect-type) -- use javascript-testing-patterns
• The user wants JavaScript patterns that don't involve TypeScript configuration -- use javascript-idioms
• The user is asking about TypeScript decorators or metadata reflection -- use typescript-decorators
• The user wants framework-specific setup where the framework provides its own tsconfig (Angular CLI, Nuxt) -- check framework-specific skills first

---

Process

Step 1: Classify the Project Type and Target Environment

Determine which of four project archetypes applies, because every subsequent decision depends on this:

• Application (bundler target): Code is processed by Vite, webpack, esbuild, Parcel, or Rollup. TypeScript is used only for type checking -- the bundler handles compilation. Set "noEmit": true. Use "moduleResolution": "bundler". This unlocks the most permissive and ergonomic module resolution, supporting extensionless imports and index file resolution without requiring .js extensions.
• Library (npm publish): TypeScript emits .js and .d.ts files that other projects consume. Set "declaration": true, "declarationMap": true, "composite": true. Use "moduleResolution": "node16" or "nodenext". This enforces the same constraints your consumers face.
• Node.js CLI or server (direct execution): TypeScript compiles to .js files run by Node.js directly or via a loader like tsx or ts-node. Use "module": "Node16" or "NodeNext" with matching "moduleResolution". If using a bundler (esbuild for Lambda), treat it as the bundler case.
• Monorepo package: One or more packages depend on others in the same repo. Every internal package must use "composite": true. Use project references (references array) so tsc --build can incrementally compile in dependency order. Never cross-import source files across package boundaries.

Secondary environment questions to resolve now, not later:

• Is JSX required? (React, Preact, Solid) -- determines "jsx" setting and lib needs
• What is the minimum runtime target? ES2022 for Node.js 18+, ES2020 for Node.js 14+, never below ES2015 for new projects
• Is this a dual-CJS/ESM library? (requires two separate tsconfig files and two build outputs)

Step 2: Establish the Strict Type Safety Baseline

Start from the strictest reasonable configuration and relax only with explicit justification. Never start permissive and attempt to tighten later -- the cost is orders of magnitude higher.

The core strict flags and what each one buys you:

• "strict": true -- umbrella flag that enables strictNullChecks, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, noImplicitAny, noImplicitThis, alwaysStrict, useUnknownInCatchVariables. Enable this unconditionally on new projects.
• "exactOptionalPropertyTypes": true -- differentiates { prop?: string } (property absent) from { prop: string | undefined } (property present but undefined). Prevents a large class of subtle bugs where explicitly writing undefined to an optional key has different semantics than omitting it. This is not included in the strict umbrella -- add it explicitly.
• "noUncheckedIndexedAccess": true -- adds | undefined to all index signature results and array element access. arr[0] becomes string | undefined instead of string. This forces you to handle the case where an index is out of bounds. Not in the strict umbrella -- add it explicitly. Note: this affects for...of loops benignly (element type is still correct) but will generate errors for array[i] patterns used without null checks.
• "noImplicitReturns": true -- errors when a function has code paths that return without a value. Catches missing return statements in complex conditionals.
• "noFallthroughCasesInSwitch": true -- errors on switch cases that fall through without break or return. Prevents accidental fallthrough.
• "noImplicitOverride": true -- requires the override keyword when overriding a base class method. Catches typos in method names that silently create new methods instead of overriding.
• "forceConsistentCasingInFileNames": true -- prevents import casing mismatches that pass on macOS/Windows (case-insensitive filesystems) but break Linux CI. Always enable.

Flags that are deliberately excluded from the default recommendation and why:

• "noPropertyAccessFromIndexSignature": true -- forces bracket notation for index signature access. Useful in some codebases but creates friction with common patterns. Evaluate per project.
• "allowUnusedLabels": false and "allowUnreachableCode": false -- catch dead code, but conflict with common debugging patterns. Better handled by ESLint.

Step 3: Configure Module and Module Resolution Settings

This is the single most error-prone area of TypeScript configuration. The module and moduleResolution settings are separate concerns but must be coherent:

Decision matrix:

Scenario	module	moduleResolution	Notes
Vite/webpack/esbuild app	ESNext	bundler	Most ergonomic, extensionless imports
Next.js app	ESNext	bundler	Next.js plugin handles actual compilation
Node.js with ESM ("type": "module")	Node16 or NodeNext	node16 or nodenext	Requires .js extensions in imports
Node.js with CJS ("type": "commonjs")	CommonJS	node16 or nodenext	Can use extensionless imports
npm library (ESM output)	Node16	node16	Matches consumer constraints
npm library (dual CJS+ESM)	Two tsconfig files	See edge cases	One per output format

Critical pitfalls in module resolution:

• "moduleResolution": "node" (legacy) does not understand package.json exports field. Any library that uses exports for path mapping will resolve incorrectly. Never use this on new projects.
• "moduleResolution": "bundler" cannot be used when TypeScript emits files (i.e., when noEmit is false). It assumes a bundler handles actual file resolution. Setting composite: true or declaration: true with bundler resolution will error.
• When using "module": "Node16" or "NodeNext", TypeScript enforces that relative imports use explicit file extensions. You must write import { foo } from './utils.js' even though the source file is utils.ts. TypeScript understands that .js in an import refers to the compiled output.
• "esModuleInterop": true -- enables helper functions that make CommonJS default imports work without * as syntax. Required for importing packages like path, fs, or any CJS-only package with a default export. Always enable. It also implies "allowSyntheticDefaultImports": true.

Step 4: Configure Path Aliases

Path aliases improve import ergonomics but require configuration in two places: TypeScript (for type checking) and the runtime/bundler (for actual resolution). TypeScript's paths do not affect compilation output -- they are hints for the type checker only.

TypeScript side:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}

baseUrl must be set for paths to work. It is relative to the tsconfig.json file location. Set it to "." to anchor paths to the repo root, or to "src" if you want shorter aliases.

Runtime/bundler side -- each tool has its own syntax:

• Vite: resolve.alias in vite.config.ts. Use fileURLToPath(new URL('./src', import.meta.url)) for the path value in ESM configs.
• webpack: resolve.alias in webpack.config.js.
• Jest/Vitest: moduleNameMapper in jest config or resolve.alias in vitest config.
• Node.js (no bundler): Use package.json imports field with "#utils/*": "./src/utils/*" syntax (note the # prefix required by Node.js subpath imports). Then use "paths": { "#utils/*": ["./src/utils/*"] } in tsconfig.
• ts-node / tsx: These tools read tsconfig.json paths directly via tsconfig-paths package, or natively in newer versions.

Alias naming conventions that minimize confusion:

• @/* for the general source root -- widely understood convention
• # prefix only for Node.js subpath imports (different semantic)
• Avoid single-character aliases (~, $) -- they conflict with shell expansion in some contexts
• Maximum two levels of nesting: @/components/Button is fine, @/ui/components/forms/inputs/TextInput suggests a structural problem

Step 5: Configure Output Settings

Output configuration differs fundamentally between applications and libraries:

For applications (bundler handles compilation):

{
  "compilerOptions": {
    "noEmit": true,
    "sourceMap": false
  }
}

noEmit: true tells TypeScript to run only type checking. The bundler produces actual output. Source maps are irrelevant here -- the bundler generates its own.

For libraries:

{
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "declarationDir": "./dist/types",
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "emitDeclarationOnly": false
  }
}

Key output decisions for libraries:

• "declarationDir" separates .d.ts files from .js files when you want a flat dist/ with types/ subdirectory. Omit it to colocate .d.ts with .js.
• "declarationMap": true generates .d.ts.map files that map declaration file positions back to source. This enables "Go to Definition" in consuming projects to jump to your TypeScript source instead of the compiled declaration file. Always include it in libraries -- it has zero runtime cost.
• "sourceMap": true generates .js.map files for debugger integration. Include in libraries so consumers can debug into your code.
• "emitDeclarationOnly": true is useful when a separate tool (esbuild, Rollup) handles .js output but you still need TypeScript to generate .d.ts files. This is a common pattern: esbuild for fast JS compilation, tsc --emitDeclarationOnly for types.

The rootDir/outDir relationship is critical: rootDir must be an ancestor of all source files. If any source file is outside rootDir, TypeScript errors. This is why rootDir: "src" and include: ["src/**/*.ts"] must be consistent.

Incremental compilation:

• "incremental": true writes a .tsbuildinfo file that caches type checking results. Dramatically speeds up repeated tsc runs. Safe to enable in both applications and libraries.
• "tsBuildInfoFile": "./.tsbuildinfo" controls where the cache file is written. For monorepos, put it inside each package's directory.
• "composite": true implies "incremental": true automatically.

Step 6: Configure for Specific Frameworks and Runtimes

React / Preact (Vite):

• "jsx": "react-jsx" -- uses the automatic JSX transform (no import React required). Default for React 17+.
• "jsx": "react" -- classic transform, requires import React from 'react' in every JSX file. Only for React 16.
• "jsx": "preserve" -- emits JSX unchanged for a downstream bundler to transform. Used by Next.js (Next handles JSX compilation via SWC).
• Add "DOM" and "DOM.Iterable" to lib for browser API types.

Next.js 14/15:

• Use "plugins": [{ "name": "next" }] in compilerOptions for the Next.js TypeScript plugin, which provides route type checking and other Next-specific features in the IDE.
• "moduleResolution": "bundler" is correct for Next.js (confirmed in Next.js docs).
• Next.js generates next-env.d.ts -- include this file in the include array.
• Do not set "module" to "CommonJS" -- Next.js expects "ESNext".

Node.js 18+ with native ESM:

• Set "type": "module" in package.json.
• Set "module": "Node16" and "moduleResolution": "node16" in tsconfig.
• All relative imports in TypeScript source must use .js extension (not .ts).
• tsc output will use .js extensions as written -- the TypeScript compiler does not rewrite extensions.
• Named exports from package.json exports field are fully supported.

Deno:

• "moduleResolution": "bundler" or "node16" both work.
• Deno supports URL imports -- add "allowImportingTsExtensions": true for first-party .ts imports.
• Use Deno's deno.json or deno.jsonc for import maps rather than tsconfig paths.

Step 7: Set Up Monorepo Project References

For any monorepo with multiple TypeScript packages, project references are mandatory for correct incremental builds and cross-package "Go to Definition" support.

Structure requirements:

• Every package that is referenced by another must have "composite": true.
• composite: true requires: "declaration": true, an explicit "rootDir", and all input files covered by include/files.
• The consuming package lists references: "references": [{ "path": "../shared-types" }].
• Build with tsc --build (or tsc -b) from the root, not tsc alone.
• tsc --build --watch for development mode.

Base config inheritance:

• Create a tsconfig.base.json at the repo root with shared strict settings.
• Each package's tsconfig extends it: "extends": "../../tsconfig.base.json".
• The base config should NOT include include/exclude/references -- these are package-specific.
• Override only what differs per package (module system, jsx, outDir).

The paths problem in monorepos:

• TypeScript paths do not cross package boundaries via project references -- they are local to each tsconfig.
• Do not use paths to reference sibling packages. Use actual npm package names (@myorg/shared-types) resolved via node_modules symlinks (pnpm workspaces, yarn workspaces, npm workspaces) plus project references.
• The paths alias and the project reference must agree: if you alias @myorg/shared-types to a local path, also add the corresponding reference.

Step 8: Validate and Iterate

Validation must happen in this order -- each step catches different classes of problems:

1. tsc --noEmit -- type checking pass only. Zero errors required before any other step. On a library, run tsc --build instead to validate project references.
2. IDE type resolution check -- open a consuming file, hover over an imported symbol, confirm the type shows correctly (not any). If types show as any, module resolution or path aliases are broken.
3. "Go to Definition" check -- in the IDE, press F12 on an imported symbol. It should jump to the TypeScript source file, not a .d.ts file. If it jumps to .d.ts, declarationMap is missing or not being generated.
4. Build output check -- for libraries, inspect dist/ for: .js files, .d.ts files, .d.ts.map files, .js.map files. Missing any of these breaks consumers.
5. Consumer simulation -- create a temporary consuming project, install your library from the local dist/, and verify imports, types, and source maps work end-to-end. This catches package.json exports misalignments.

---

Output Format

When providing TypeScript project configuration, deliver the following structure:

Project Assessment Summary

Project type:    [Application | Library | Node.js service | Monorepo package]
Bundler/runtime: [Vite | webpack | Node.js native | Next.js | Deno | none]
Output target:   [Browser | Node.js 18+ | Node.js 16+ | Dual CJS+ESM]
JSX required:    [Yes (React 17+) | Yes (React 16) | No]
Path aliases:    [Yes -- list aliases | No]
Monorepo:        [Yes -- list tools | No]
Key constraints: [List any non-standard requirements]

tsconfig.json Files

Provide all tsconfig files needed for the project, labeled clearly:

Files to create:
  tsconfig.base.json          (if monorepo)
  tsconfig.json               (always)
  tsconfig.build.json         (if library with separate type-check and build configs)
  packages/*/tsconfig.json    (if monorepo)

Each tsconfig with inline comments explaining non-obvious settings:

// tsconfig.json
{
  "compilerOptions": {
    // -- Language target --
    "target": "ES2022",           // Minimum: ES2022 for Node 18+, ES2020 for Node 14+
    "lib": ["ES2022"],            // Match target unless polyfilling

    // -- Module system --
    "module": "ESNext",           // Use Node16/NodeNext for native Node ESM
    "moduleResolution": "bundler",// Use node16/nodenext when emitting files

    // -- Strict type checking --
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "forceConsistentCasingInFileNames": true,

    // -- Emit --
    "noEmit": true,              // Set to false for libraries
    "sourceMap": true,           // For libraries: true; for bundler apps: false
    "incremental": true,

    // -- Interop --
    "esModuleInterop": true,
    "isolatedModules": true,     // Required when using esbuild/SWC for compilation
    "skipLibCheck": true,

    // -- Path aliases --
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Bundler Alias Configuration (when applicable)

Provide the matching alias configuration for the build tool:

// vite.config.ts
import { defineConfig } from 'vite'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

package.json Exports (for libraries)

{
  "name": "@myorg/my-library",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"]
}

Validation Checklist

[ ] tsc --noEmit passes with zero errors
[ ] tsc --build passes (monorepos / libraries with composite)
[ ] IDE shows correct types on imported symbols (not `any`)
[ ] "Go to Definition" jumps to source .ts files (not .d.ts)
[ ] dist/ contains .js, .d.ts, .d.ts.map, .js.map (libraries)
[ ] Path aliases resolve in IDE and in build output
[ ] No circular project references (monorepos)

---

Rules

1. ALWAYS enable "strict": true. Never ship a tsconfig without it. The time cost of enabling strict on an existing codebase is 10--50x higher than starting strict. If a user asks to disable strict for "simplicity," explain the trade-off and offer the phased migration path instead.

2. ALWAYS add "exactOptionalPropertyTypes": true and "noUncheckedIndexedAccess": true explicitly. These are not included in the strict umbrella and address a large proportion of real production bugs. They are the two most impactful non-umbrella flags.

3. NEVER use "moduleResolution": "node" (legacy) on new projects. It ignores the exports field in package.json, which means any library using path mapping (like @tanstack/query/react) will resolve incorrectly. The correct minimum is "node16" for emit scenarios or "bundler" for non-emit scenarios.

4. NEVER use "moduleResolution": "bundler" when TypeScript must emit files. bundler resolution is incompatible with TypeScript emission (composite: true, declaration: true, or any config without noEmit: true). This combination produces a TypeScript compiler error: "Option 'moduleResolution: bundler' requires 'noEmit: true' or 'emitDeclarationOnly: true'."

5. ALWAYS pair "paths" configuration with runtime resolution. TypeScript paths are erased at compile time -- they do not affect the compiled output. A path alias that is not also configured in the bundler (Vite, webpack), test runner (Jest moduleNameMapper, Vitest resolve.alias), or Node.js (package.json imports field) will cause runtime "Cannot find module" errors even though TypeScript type-checks correctly.

6. ALWAYS use "composite": true and project references for monorepo packages. Without project references, tsc --build cannot determine build order and will not produce correct incremental output. Without composite, the TypeScript server cannot cache type information for referenced packages, causing IDE slowness proportional to monorepo size.

7. NEVER cross-import source .ts files from a sibling package in a monorepo. Always import through the package's public API (its main/exports field pointing to dist/), or through project references that consume the compiled output. Direct source imports break build caching and create tight coupling that makes packages non-independently deployable.

8. ALWAYS set "isolatedModules": true when using esbuild, SWC, or Babel for compilation. These tools compile files one-at-a-time without access to the full type graph, which means they cannot handle const enum, namespace merging, or re-exported types without explicit type imports. isolatedModules surfaces these incompatibilities at compile time rather than silently producing incorrect output. Also enforce "verbatimModuleSyntax": true as a stricter alternative that enforces import type for all type-only imports.

9. NEVER set "target" below "ES2020" for new projects without explicit IE11 or legacy environment requirements. Targeting ES5 or ES6 forces TypeScript to emit large polyfill helpers (__awaiter, __generator, __assign) for async/await and object spread. Modern bundlers tree-shake and conditionally polyfill based on target browsers far more efficiently than TypeScript's emit helpers. Minimum target for Node.js 18+ is ES2022 to use native Array.at(), Error.cause, Object.hasOwn(), and top-level await.

10. ALWAYS include "skipLibCheck": true in application tsconfigs. Library declaration files often contain type errors due to version mismatches between a library's @types package and the library itself. skipLibCheck skips type-checking of all .d.ts files in node_modules. The performance gain on medium-to-large projects is 30--60% faster type checking. For libraries you publish, do NOT skip lib checking on your own .d.ts output -- run tsc on your output to verify your declarations are valid.

11. ALWAYS regenerate tsconfig.tsbuildinfo when changing compilerOptions significantly. Stale incremental build caches cause TypeScript to skip re-checking files it should re-check. Run tsc --build --clean to wipe the cache when changing strict, target, module, moduleResolution, or paths.

12. NEVER mix "module": "CommonJS" with "type": "module" in package.json. If package.json has "type": "module", all .js files are interpreted as ESM. If TypeScript emits CommonJS into those files, Node.js will throw SyntaxError: Cannot use import statement in a module. Use .cjs extension for CommonJS output in an ESM package, or change "type" to "commonjs" and use .mjs for ESM files.

---

Edge Cases

Migrating from JavaScript to TypeScript Incrementally

Start permissive and tighten. Never attempt a big-bang migration:

1. Add tsconfig.json with "allowJs": true, "checkJs": false, "noEmit": true, "strict": false.
2. Rename the entry point file from .js to .ts. Fix only the errors introduced by that one file.
3. Work outward from leaf modules (pure utilities with no imports) toward the entry point. Leaf modules have no dependencies to fight with.
4. After the codebase is fully .ts, enable flags one at a time in this order: noImplicitAny → strictNullChecks → strictFunctionTypes → strict: true → exactOptionalPropertyTypes → noUncheckedIndexedAccess.
5. Use // @ts-ignore and // @ts-expect-error sparingly as temporary suppressions with a TODO comment referencing a ticket. Never suppress errors permanently.
6. The as unknown as TargetType double cast is acceptable during migration when the type relationship is genuinely established by program logic TypeScript cannot verify -- but document it.

Dual CJS and ESM Library Output

Publishing a library that works in both CommonJS and ESM environments requires two separate tsconfig files and careful package.json exports:

// tsconfig.esm.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "Node16",
    "moduleResolution": "node16",
    "outDir": "./dist/esm",
    "declaration": false   // Emit declarations from ESM build only
  }
}

// tsconfig.cjs.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "CommonJS",
    "moduleResolution": "node16",
    "outDir": "./dist/cjs",
    "declaration": true,
    "declarationDir": "./dist/types"
  }
}

Build script: tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json

package.json exports field:

{
  "exports": {
    ".": {
      "import": { "types": "./dist/types/index.d.ts", "default": "./dist/esm/index.js" },
      "require": { "types": "./dist/types/index.d.ts", "default": "./dist/cjs/index.js" }
    }
  }
}

The CJS output directory should contain a package.json with { "type": "commonjs" } to prevent Node.js from misinterpreting .js files as ESM. The ESM output directory gets { "type": "module" }.

Non-TypeScript File Imports (CSS Modules, SVG, WASM)

TypeScript does not know about non-standard file types. Create declaration files in src/ to teach it:

// src/declarations.d.ts

// CSS Modules
declare module '*.module.css' {
  const classes: Record<string, string>
  export default classes
}

// SVG as React components (SVGR)
declare module '*.svg' {
  import type { FC, SVGProps } from 'react'
  const ReactComponent: FC<SVGProps<SVGSVGElement>>
  export { ReactComponent }
  export default ReactComponent
}

// WebAssembly -- typed at instantiation level
declare module '*.wasm' {
  const content: WebAssembly.Module
  export default content
}

// JSON -- TypeScript handles this natively with "resolveJsonModule": true
// No declaration needed, but add to tsconfig: "resolveJsonModule": true

Keep declaration files in src/ and include them in include array. Never add them to node_modules or global scope unless they are genuinely global types.

TypeScript with Decorators (Legacy and Standard)

TypeScript supports two decorator systems with different tsconfig requirements:

• Legacy decorators (TypeScript < 5.0, Angular, NestJS): Require "experimentalDecorators": true and "emitDecoratorMetadata": true. The latter requires reflect-metadata as a runtime dependency. These decorators use a different syntax and are not compatible with the TC39 standard decorators.
• Standard decorators (TypeScript 5.0+, TC39 Stage 3): Do NOT set experimentalDecorators. Standard decorators are enabled by default in TypeScript 5+. They do not support metadata emission -- if you need metadata, use a separate mechanism.

NestJS currently requires legacy decorators. Angular 15+ supports standard decorators. Do not mix the two systems.

Path Aliases Breaking in Jest or Vitest

The most common post-setup failure: TypeScript is happy, the build works, but tests fail with "Cannot find module '@/utils/format'". This is because Jest and Vitest resolve modules independently of TypeScript and the application bundler.

For Jest:

// jest.config.json
{
  "moduleNameMapper": {
    "^@/(.*)$": "<rootDir>/src/$1"
  }
}

For Vitest:

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { fileURLToPath, URL } from 'node:url'

export default defineConfig({
  test: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

Alternatively, Vitest can extend the Vite config: import { defineConfig } from 'vitest/config' combined with mergeConfig(viteConfig, vitestConfig) -- this automatically inherits Vite's resolve.alias settings and avoids duplication.

Circular Project References in Monorepos

tsc --build detects circular references between packages and errors immediately. Common causes:

• Package A references Package B, and Package B references Package A.
• A shared utility package that imports from a feature package that it should not know about.
• Incorrectly placed types that should be in a separate base package.

Resolution strategy:

1. Draw the dependency graph explicitly (package names as nodes, references as directed edges).
2. The graph must be a DAG (directed acyclic graph). Any cycle must be broken.
3. Extract the shared type or utility into a third package that neither A nor B imports from each other.
4. Commonly: @myorg/types (no dependencies), @myorg/utils (depends on types), @myorg/feature (depends on both). Never let types or utils depend on feature packages.

skipLibCheck Hiding Real Errors

skipLibCheck: true skips ALL .d.ts files, including your own generated declarations if you mistakenly include dist/ in include. This can hide malformed declaration output.

Safe practice:

• Add "dist" and "**/*.d.ts" to exclude in your source tsconfig.
• Run a separate type validation step in CI: tsc --noEmit -p tsconfig.check-declarations.json where that config has skipLibCheck: false and includes only the dist/ types.
• Use @arethetypeswrong/cli (attw) to validate your published package's types resolve correctly from multiple module resolution modes.

---

Example

Input: "I'm building a date formatting library called tempo-date that I plan to publish to npm. It needs to work in both ESM and CommonJS environments. I'm using TypeScript 5.3 with esbuild for JavaScript compilation and tsc --emitDeclarationOnly for types. The library will be used in Node.js 18+ and browser (via bundlers). No React, no path aliases. How should I configure TypeScript?"

---

Project Assessment

Project type:    Library (npm publish)
Bundler/runtime: esbuild (JS compilation), tsc (declaration only)
Output target:   Dual CJS+ESM -- Node.js 18+ and browser bundlers
JSX required:    No
Path aliases:    No
Monorepo:        No
Key constraints: esbuild requires isolatedModules; dual output requires two tsconfig files;
                 declarations must be correct for both module formats

---

File Structure

tempo-date/
  src/
    index.ts          # Public API entry point
    format.ts         # Core formatting logic
    parse.ts          # Parsing logic
    locale.ts         # Locale handling
    types.ts          # Shared internal types
    declarations.d.ts # (not needed -- pure TS library)
  dist/
    esm/
      index.js        # ESM output (esbuild)
      package.json    # { "type": "module" }
    cjs/
      index.js        # CJS output (esbuild)
      package.json    # { "type": "commonjs" }
    types/
      index.d.ts      # Declaration files (tsc)
      index.d.ts.map  # Declaration maps (tsc)
  tsconfig.json           # Base config for IDE and type checking
  tsconfig.build.json     # Extends base -- used for tsc --emitDeclarationOnly
  package.json
  build.ts                # esbuild build script

---

tsconfig.json (base -- used by IDE and tsc --noEmit)

{
  "compilerOptions": {
    // Language target -- ES2022 for Node.js 18+ native features
    // Object.hasOwn, Array.at, Error.cause available without polyfill
    "target": "ES2022",

    // lib: no DOM -- this is a pure utility library with no browser-specific APIs
    // ES2022 gives us the same built-in types as target
    "lib": ["ES2022"],

    // Module: Node16 matches the resolution mode consumers will use.
    // This also enforces .js extension discipline in our own imports,
    // which catches a common ESM pitfall before it reaches consumers.
    "module": "Node16",
    "moduleResolution": "node16",

    // Strict type checking -- full suite plus the two non-umbrella flags
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,

    // isolatedModules: required because esbuild compiles file-by-file.
    // This ensures we never use const enum, namespace merging,
    // or implicit type re-exports that esbuild cannot handle.
    "isolatedModules": true,

    // verbatimModuleSyntax: stricter version of isolatedModules.
    // Forces explicit "import type" for all type-only imports.
    // esbuild and SWC can then safely strip type imports without
    // needing to analyze whether an import is type-only.
    "verbatimModuleSyntax": true,

    // esModuleInterop: not strictly needed for a pure ESM library,
    // but enables correct default import behavior if we ever import
    // a CommonJS dependency.
    "esModuleInterop": true,

    // skipLibCheck: true for performance during development type checking.
    // We validate our OWN generated declarations separately in CI.
    "skipLibCheck": true,

    // noEmit: true for this base config -- IDE and tsc --noEmit use only.
    // Actual emission handled by tsconfig.build.json and esbuild.
    "noEmit": true,

    // Incremental: cache type checking state for faster subsequent runs.
    "incremental": true,
    "tsBuildInfoFile": "./.tsbuildinfo"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
}

---

tsconfig.build.json (declaration emission only)

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    // Override noEmit -- this config exists to emit declarations
    "noEmit": false,
    "emitDeclarationOnly": true,

    // Declaration output configuration
    "declaration": true,
    "declarationMap": true,
    "declarationDir": "./dist/types",

    // rootDir must be set so declaration file paths mirror source paths.
    // dist/types/index.d.ts corresponds to src/index.ts.
    "rootDir": "./src",

    // composite: true enables project references if we later add this
    // library as a monorepo package. Required with emitDeclarationOnly
    // when referenced by other composite projects.
    "composite": true,

    // Disable incremental cache for build -- use a clean build in CI
    "incremental": false,
    "tsBuildInfoFile": undefined
  },
  "include": ["src/**/*.ts"],
  // Exclude tests from declaration output
  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
}

---

build.ts (esbuild script for JS compilation)

import { build } from 'esbuild'

const sharedConfig = {
  entryPoints: ['src/index.ts'],
  bundle: true,
  platform: 'neutral' as const, // Works in both Node.js and browser bundlers
  target: 'es2022',
  // external: list peer dependencies if any -- prevents bundling them
  external: [],
  // No minification in library output -- consumers handle that
  minify: false,
  sourcemap: true,
}

// ESM output
await build({
  ...sharedConfig,
  format: 'esm',
  outfile: 'dist/esm/index.js',
})

// CJS output
await build({
  ...sharedConfig,
  format: 'cjs',
  outfile: 'dist/cjs/index.js',
})

// Generate package.json shims for each output directory
import { writeFile } from 'node:fs/promises'
await writeFile('dist/esm/package.json', JSON.stringify({ type: 'module' }))
await writeFile('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }))

console.log('Build complete')

---

package.json

{
  "name": "tempo-date",
  "version": "1.0.0",
  "description": "Fast, type-safe date formatting and parsing",
  "license": "MIT",
  "type": "module",
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "import": {
        "types": "./dist/types/index.d.ts",
        "default": "./dist/esm/index.js"
      },
      "require": {
        "types": "./dist/types/index.d.ts",
        "default": "./dist/cjs/index.js"
      }
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsx build.ts && tsc -p tsconfig.build.json",
    "typecheck": "tsc --noEmit",
    "clean": "rm -rf dist .tsbuildinfo"
  },
  "devDependencies": {
    "esbuild": "^0.20.0",
    "tsx": "^4.0.0",
    "typescript": "^5.3.0"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

---

Import Style Required Inside src/ (Node16 resolution)

Because "module": "Node16" is set, TypeScript enforces explicit .js extensions in relative imports. This is non-negotiable with this configuration:

// src/index.ts -- CORRECT
export { format } from './format.js'      // .js extension, even though source is .ts
export { parse } from './parse.js'
export { createLocale } from './locale.js'
export type { FormatOptions, ParseResult } from './types.js'

// src/index.ts -- WRONG -- TypeScript will error under node16 resolution
export { format } from './format'         // Missing .js extension
export { format } from './format.ts'      // .ts extension not valid in output

TypeScript resolves './format.js' to ./format.ts in source -- the .js refers to the compiled output that will exist at runtime. This is the correct mental model.

---

CI Validation Script

#!/bin/sh
set -e

# Step 1: Full type check with zero errors
echo "Running type check..."
npx tsc --noEmit

# Step 2: Build JS (esbuild) + declarations (tsc)
echo "Building..."
npm run build

# Step 3: Verify dist structure
echo "Checking dist structure..."
test -f dist/esm/index.js     || (echo "Missing ESM output" && exit 1)
test -f dist/cjs/index.js     || (echo "Missing CJS output" && exit 1)
test -f dist/types/index.d.ts || (echo "Missing declarations" && exit 1)
test -f dist/types/index.d.ts.map || (echo "Missing declaration maps" && exit 1)

# Step 4: Validate published types resolve correctly from all module modes
# attw (Are The Types Wrong?) checks for common publishing mistakes
echo "Validating type exports..."
npx attw --pack .

echo "All checks passed."

---

Validation Checklist

[x] tsc --noEmit passes with zero errors
[x] tsc -p tsconfig.build.json produces dist/types/index.d.ts and .d.ts.map
[x] esbuild produces dist/esm/index.js and dist/cjs/index.js
[x] dist/esm/package.json contains { "type": "module" }
[x] dist/cjs/package.json contains { "type": "commonjs" }
[x] package.json exports field covers both "import" and "require" conditions
[x] Relative imports in src/ use .js extensions (enforced by node16 resolution)
[x] No import type violations (enforced by verbatimModuleSyntax)
[x] attw reports no type resolution errors for any module format
[x] "Go to Definition" in a consuming project resolves to src/ via declarationMap

The key insight for this library setup: esbuild handles JavaScript compilation at high speed, while tsc --emitDeclarationOnly handles the slower but necessary declaration file generation. These are separate concerns with separate tooling. TypeScript's verbatimModuleSyntax ensures the two tools stay in sync by enforcing explicit import type on type-only imports -- a requirement both tools share. The node16 module resolution mode validates that all imports will resolve correctly in Node.js 18+ ESM environments before any code leaves the developer's machine.