TypeScript Project Checklist: 26 Essential Steps

Set `strict: true` in compilerOptions. This enables strictNullChecks, noImplicitAny, strictFunctionTypes, strictBindCallApply, and more. Each flag catches a different class of bugs — strict mode is the single most important TypeScript configuration.

Set `noUncheckedIndexedAccess: true` so array and object index access returns `T | undefined` instead of `T`. Without this, `arr[0]` is typed as the element type even when the array could be empty, leading to runtime crashes.

Set `paths` in tsconfig.json to map `@/*` to `./src/*`. This eliminates fragile relative imports like `../../../../utils/helpers`. Ensure your bundler (Vite, webpack, Next.js) is also configured to resolve these aliases.

Set `target` to your minimum supported environment (es2022 for modern browsers, es2020 for Node 14+). Set `lib` to include DOM types for browser projects or exclude them for Node projects. Mismatched settings cause type errors or missing API types.

Set `incremental: true` and optionally `tsBuildInfoFile` to enable incremental compilation. TypeScript caches type-checking results and only rechecks changed files. This can reduce build times by 50-80% on large projects.

Search for `: any`, `as any`, and `<any>` in your codebase. Replace with proper types, `unknown` (for truly unknown values that need type narrowing), or generic type parameters. Every `any` is a hole in your type safety.

Model complex states with discriminated unions instead of optional properties. For example, `{ status: 'loading' } | { status: 'success', data: T } | { status: 'error', error: Error }` forces handling every state. Optional properties allow impossible states like `{ loading: true, error: Error }`.

Use Zod, Valibot, or io-ts to validate API responses, form inputs, and environment variables at runtime. TypeScript types are erased at runtime — a type assertion on an API response provides zero protection against malformed data.

Prefer `as const` assertions over enums for string literals — they produce zero runtime code and work with type narrowing. Use `satisfies` operator to validate object shapes while preserving literal types. Reserve numeric enums for cases needing reverse mapping.

Type assertions (`value as Type`) bypass the type checker. Each assertion is a promise to the compiler that you know better — and you might be wrong. Use type guards, `instanceof`, or `in` operator for runtime-safe type narrowing instead.

Add return type annotations to exported functions and methods. Inferred return types can change accidentally when implementation changes, silently breaking consumers. Explicit return types act as contracts and improve IDE documentation.

Run `tsc --noEmit` in CI to catch type errors before merging. Many bundlers (Vite, esbuild, SWC) skip type checking for speed — they strip types without verifying them. CI type checking is your safety net.

Install `@typescript-eslint/eslint-plugin` and enable type-aware rules like `no-floating-promises`, `no-misused-promises`, `strict-boolean-expressions`, and `no-unnecessary-condition`. These catch bugs that the TypeScript compiler alone does not flag.

Use Husky + lint-staged to run type checking on staged files before every commit. This catches type errors at commit time instead of in CI, shortening the feedback loop from minutes to seconds.

Add workspace settings to enable `typescript.preferences.importModuleSpecifier: 'non-relative'`, auto-import suggestions, organize imports on save, and inlay hints for parameter names. Share settings via `.vscode/settings.json` in your repo.

Run `tsc` and fix all 'Could not find a declaration file' errors. Install `@types/` packages for dependencies that do not ship their own types. For untyped libraries, create a `declarations.d.ts` with minimal module declarations.

Create `types.ts` or `types/` directories for shared types. Colocate component-specific types with their components. Avoid a single massive `types.ts` file — split by domain (user.types.ts, order.types.ts).

Barrel files (`index.ts` with re-exports) simplify imports but can defeat tree shaking and slow down TypeScript compilation. Use them for public API boundaries, not for every directory. Deep imports are often better for bundler optimization.

Create branded types for IDs, emails, and other domain values: `type UserId = string & { readonly brand: unique symbol }`. This prevents accidentally passing an OrderId where a UserId is expected, catching logic errors at compile time.

Use TypeScript project references with `composite: true` and a root `tsconfig.json` with `references`. This enables incremental builds per package, faster type checking, and proper dependency boundaries in multi-package projects.

Apply generics to utility functions, hooks, and components that work with multiple types. For example, a `useFetch<T>` hook or a `DataTable<T>` component. Generics preserve type information through abstraction layers without requiring `any`.

Run your full build pipeline (bundler + tsc) targeting production. Resolve all errors. Some type errors only appear in production builds due to different tsconfig settings for dev vs prod (e.g., declaration file generation).

Use `import type { MyType }` for types to ensure they are fully erased in the output. This prevents circular dependency issues and can reduce bundle size. Enable `verbatimModuleSyntax: true` in tsconfig to enforce this.

Create a validated env config using Zod or t3-env that parses `process.env` at startup and fails fast with clear error messages if required variables are missing. Export typed env values instead of accessing `process.env` directly throughout your code.

Catch blocks receive `unknown` in strict mode. Always narrow error types with `instanceof Error` or a type guard. Create custom error classes for domain-specific errors so catch blocks can handle them differently based on type.

Check that `@types/` packages are up to date with their corresponding runtime packages. Outdated type definitions can introduce incorrect types that mask bugs. Run `npm outdated` filtered to `@types/` scope.