- Enable strict mode in `tsconfig.json`. No exceptions. - Use `using` declarations for anything with a cleanup step - TypeScript 5.5 infers type predicates automatically, delete most of your manual guard utilities - `NoInfer` fixes silent type widening in generic functions with fallback parameters - `verbatimModuleSyntax` is required if you're on ESM or deploying to edge runtimes - Use `interface` for public contracts and object shapes. Use `type` for unions, intersections, and mapped types. - Never use `any`. Use `unknown` when the type is genuinely dynamic, then narrow it. - `satisfies` lets you validate a value against a type without widening it - Discriminated unions are the right way to model state

## TypeScript Best Practices in 2026: Who This Is For This guide is for developers already writing TypeScript who want to write it better. Not a syntax overview. Not a "what is TypeScript" intro. These are the TypeScript best practices that actually change what categories of bugs are possible. The ones that matter in a real codebase at 2am when something breaks in production and you need to understand why TypeScript didn't catch it. Most TypeScript projects are underpowered. They have TypeScript installed but `strict: false` in the config, `any` scattered everywhere, and type assertions masking real problems. That's what this guide fixes. All examples target TypeScript 5.5 and above with Next.js 16 where relevant.

## 1. Enable Strict Mode This is the one thing you can't skip. Everything else in this article matters less if your `tsconfig.json` has `strict: false` in it. ```json { "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true, "exactOptionalPropertyTypes": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true } } ``` `strict: true` turns on `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, and a handful of others. `strictNullChecks` alone eliminates an entire class of null pointer crashes at compile time. Two options that are NOT included in `strict` but should be: `noUncheckedIndexedAccess` makes `array[0]` return `T | undefined` instead of `T`. Because that's what it actually is. Without this flag TypeScript lets you write `users[0].email` without checking if `users[0]` exists. `exactOptionalPropertyTypes` means you can't explicitly set an optional property to `undefined`. You can only omit it. Sounds minor. It's not, especially in form handling and API payloads. Inheriting a codebase with strict mode off? Tighten it one module at a time. Start with the files that get imported the most. Run `tsc --noEmit` after each change and fix what breaks before moving on.

## 2. `using` Declarations for Resource Management TypeScript 5.2 added `using` and `await using`. If you manage anything with a cleanup step, database connections, file handles, WebSocket sessions, timers, this is the most useful TypeScript 5.x addition for day to day application code. The old way: ```ts async function processUpload(file: File) { const connection = await db.connect(); try { await connection.insert(file); } finally { await connection.close(); } } ``` `try/finally` works until someone adds a new code path and forgets the cleanup. That's how you get memory leaks from unreleased connections in production. With `using`: ```ts class DatabaseConnection { async insert(data: unknown) { /* ... */ } async [Symbol.asyncDispose](): Promise { await this.close(); } } async function processUpload(file: File) { await using connection = await db.connect(); await connection.insert(file); // cleanup runs here no matter what } ``` Works for timers too: ```ts class Timer { private id: ReturnType; constructor(fn: () => void, ms: number) { this.id = setTimeout(fn, ms); } [Symbol.dispose]() { clearTimeout(this.id); } } function runWithTimeout(task: () => void) { using timer = new Timer(() => console.log("timed out"), 5000); task(); // timer cleared automatically when scope exits } ``` Cleanup is guaranteed at scope exit. Multiple `using` declarations in the same scope dispose in reverse order, which is exactly right when one resource depends on another.

## 3. Inferred Type Predicates (TypeScript 5.5) Before 5.5, getting `.filter()` to narrow types meant writing explicit predicates by hand: ```ts // Before 5.5 function isNonNull(value: T | null | undefined): value is T { return value != null; } const raw: (User | null)[] = await getUsers(); const users = raw.filter(isNonNull); // User[] ``` Most codebases ended up with a whole utils file of these. TypeScript 5.5 just infers them when it can figure out from the function body what's being narrowed: ```ts // After 5.5 const raw: (User | null)[] = await getUsers(); const users = raw.filter(u => u !== null); // User[], not (User | null)[] ``` Simple equality and null checks work reliably. Complex logic with nested property access still needs explicit predicates. But for filtering nulls, checking undefined, narrowing string unions? You can delete most of those utilities.

## 4. `NoInfer` for Generic Functions with Fallbacks `NoInfer` landed in TypeScript 5.4. Small utility, specific problem, but when you hit the issue it solves you'll understand it instantly. When you write a generic function with a fallback parameter, TypeScript infers `T` from every argument including the fallback. The fallback widens the type in ways you don't want. ```ts // Without NoInfer function getConfig( registry: Map, key: string, fallback: T ): T { return registry.get(key) ?? fallback; } // T infers as { timeout: number } instead of ServerConfig // downstream code has no error where it should getConfig(serverRegistry, 'primary', { timeout: 3000 }); ``` ```ts // With NoInfer function getConfig( registry: Map, key: string, fallback: NoInfer ): T { return registry.get(key) ?? fallback; } ``` The fallback is now excluded from `T` inference. TypeScript infers `T` from the registry only and validates the fallback against it. Reach for `NoInfer` whenever you write generic utilities with default or fallback parameters. You'll know you need it when the inferred type keeps coming out wider than expected.

## 5. `verbatimModuleSyntax` for ESM This shipped in TypeScript 5.0 and most teams are still ignoring it. If you're on edge runtimes (Cloudflare Workers, Vercel Edge, Deno) or Node.js native TypeScript support, it's basically required now. Without it, TypeScript can silently rewrite your imports. An `import { SomeInterface }` that's type-only might get emitted as a value import or dropped entirely depending on what the compiler guesses. On edge runtimes doing their own module analysis, that creates subtle bundling bugs that are genuinely hard to trace. ```json { "compilerOptions": { "verbatimModuleSyntax": true } } ``` With it on, type-only imports must be explicit: ```ts // This errors import { User } from "./types"; // This is correct import type { User } from "./types"; // Or inline import { type User, createUser } from "./models"; ``` Enabling this will break files with implicit type imports. VS Code's quick-fix handles most of them in one click. One-time cost, clean ESM output forever. On CommonJS with no edge runtime? You can skip this for now. Otherwise do it today.

## 6. The `satisfies` Operator Added in TypeScript 4.9 and still one of the most underused features in the language. `satisfies` validates a value against a type without widening it to that type. The problem without it: ```ts const config: Record = { apiUrl: "https://api.example.com", timeout: "5000", }; config.apiUrl; // string, loses the literal "https://api.example.com" ``` With `satisfies`: ```ts const config = { apiUrl: "https://api.example.com", timeout: "5000", } satisfies Record; config.apiUrl; // "https://api.example.com", literal type preserved ``` More practical example with a palette: ```ts type Colors = "red" | "green" | "blue"; const palette = { red: [255, 0, 0], green: "#00ff00", blue: [0, 0, 255], } satisfies Record; palette.red.map(x => x * 2); // works, TypeScript knows red is number[] palette.green.toUpperCase(); // works, TypeScript knows green is string ``` Without `satisfies`, you'd have to annotate as `Record` and lose the per-key type information. Then you're casting at every access point. Use `satisfies` when you want shape validation at the definition site but need narrower types downstream.

## 7. `const` Type Parameters (TypeScript 5.0) Before TypeScript 5.0, inferring literal types from generic function arguments meant callers had to remember `as const`: ```ts function createTuple(values: T[]): T[] { return values; } const t = createTuple(["a", "b", "c"]); // string[], not ["a", "b", "c"] const t2 = createTuple(["a", "b", "c"] as const); // readonly ["a", "b", "c"] ``` TypeScript 5.0 lets the function request const inference instead: ```ts function createTuple(values: T[]): T[] { return values; } const t = createTuple(["a", "b", "c"]); // ["a", "b", "c"] inferred ``` Most useful in utility functions building configuration objects or route definitions where the literal values matter downstream: ```ts function defineRoutes>(routes: T): T { return routes; } const routes = defineRoutes({ home: "/", dashboard: "/dashboard", settings: "/settings", }); type HomeRoute = typeof routes.home; // "/" not string ``` Before this, every caller needed `as const`. Now the function handles it.

## 8. Interfaces vs Types Every TypeScript codebase has this debate. Here's the short answer: Use `interface` for object shapes that are part of a public contract. Use `type` for everything else. ```ts // interface for object shapes and class contracts interface User { id: string; email: string; role: "admin" | "member"; } interface Repository { findById(id: string): Promise; findAll(): Promise; save(entity: T): Promise; delete(id: string): Promise; } // type for unions, intersections, mapped types, utility compositions type Status = "active" | "inactive" | "suspended"; type Nullable = { [K in keyof T]: T[K] | null }; type CreateUserInput = Omit & { password: string }; ``` The one practical difference that actually matters: interfaces support declaration merging, types don't. If you're extending a third-party library's types, you need an interface. Pick a convention for each case and stick to it. Mixing both randomly across a codebase is the only real wrong answer here.

## 9. Generics and Utility Types Learn the built-ins before rolling your own. Most custom TypeScript utilities are just reinventions of what's already there. ```ts interface User { id: string; email: string; name: string; role: "admin" | "member"; createdAt: Date; } type UpdateUserInput = Partial; type UserSummary = Pick; type CreateUserInput = Omit; type RequiredUser = Required; type RolePermissions = Record; async function getUser(id: string): Promise { /* ... */ } type GetUserReturn = Awaited>; // User type GetUserParams = Parameters; // [string] ``` For generics, let TypeScript infer where it can and add constraints where it needs to: ```ts // loses type information function first(arr: any[]): any { return arr[0]; } // correct function first(arr: T[]): T | undefined { return arr[0]; } // with a constraint function getProperty(obj: T, key: K): T[K] { return obj[key]; } ``` Built-in utilities first, generic constraints second, custom mapped types only when nothing else works.

## 10. Never Use `any`. Use `unknown`. `any` turns the type checker off for that value. Completely. You can call methods that don't exist, assign it where incompatible types are expected, and TypeScript stays quiet. `unknown` accepts anything but forces you to narrow before you can use it: ```ts // bad async function fetchData(url: string): Promise { const response = await fetch(url); return response.json(); } const data = await fetchData("/api/user"); data.email.toUpperCase(); // no error, crashes at runtime // better async function fetchData(url: string): Promise { const response = await fetch(url); return response.json(); } // must narrow before use if (typeof data === "object" && data !== null && "email" in data) { const email = (data as { email: string }).email; } // best — validate with Zod import { z } from "zod"; const UserSchema = z.object({ id: z.string(), email: z.string().email(), }); const user = UserSchema.parse(await fetchData("/api/user")); // typed User ``` Zod is the right tool for external data in Next.js apps. One schema gives you both runtime validation and compile time types. No duplication, no drift.

## 11. Discriminated Unions for State This is the right way to model state. It makes impossible states unrepresentable at the type level. ```ts // bad — nothing stops { isLoading: true, data: user, error: "something" } interface RequestState { isLoading: boolean; data?: User; error?: string; } // good type RequestState = | { status: "idle" } | { status: "loading" } | { status: "success"; data: User } | { status: "error"; error: string }; ``` TypeScript narrows automatically based on the discriminant: ```ts function renderUser(state: RequestState) { switch (state.status) { case "idle": return null; case "loading": return ; case "success": return ; case "error": return ; } } ``` Add exhaustiveness checking so TypeScript tells you when you've missed a case: ```ts function assertNever(value: never): never { throw new Error(`Unhandled case: ${JSON.stringify(value)}`); } function renderUser(state: RequestState) { switch (state.status) { case "idle": return null; case "loading": return ; case "success": return ; case "error": return ; default: return assertNever(state); } } ``` Add a new status variant and TypeScript errors on the `default` case until you handle it. That's the whole point.

## 12. TypeScript Patterns for Next.js A few TypeScript best practices that come up constantly in Next.js codebases specifically. **Type Server Action return values explicitly:** ```ts // app/actions/auth.ts "use server"; type ActionResult = | { success: true; userId: string } | { success: false; error: string }; export async function login(formData: FormData): Promise { const email = formData.get("email") as string; const password = formData.get("password") as string; try { const user = await validateCredentials(email, password); return { success: true, userId: user.id }; } catch { return { success: false, error: "Invalid credentials" }; } } ``` Your component gets full type safety on the result. No casting needed. **Type page props correctly in Next.js 16:** ```ts // app/posts/[id]/page.tsx interface PageProps { params: Promise<{ id: string }>; searchParams: Promise<{ tab?: string }>; } export default async function PostPage({ params, searchParams }: PageProps) { const { id } = await params; const { tab } = await searchParams; const post = await getPost(id); return ; } ``` **Type your environment variables:** ```ts // lib/env.ts import { z } from "zod"; const envSchema = z.object({ DATABASE_URL: z.string().url(), RESEND_API_KEY: z.string().min(1), STRIPE_SECRET_KEY: z.string().min(1), NEXT_PUBLIC_APP_URL: z.string().url(), }); export const env = envSchema.parse(process.env); ``` `env.DATABASE_URL` is now `string` not `string | undefined`. The parse runs at startup and throws immediately if a variable is missing rather than letting it fail silently three function calls deep.

## 13. Common Mistakes **Casting instead of narrowing:** ```ts // bad const user = data as User; user.email.toUpperCase(); // crashes if data isn't a User // good const user = UserSchema.parse(data); user.email.toUpperCase(); // validated, safe ``` **Typing parameters as `object`:** ```ts // bad function process(data: object) { data.name; // error, object has no properties } // good function process(data: { name: string; email: string }) { data.name; // fine } ``` **Not typing async return values:** ```ts // bad async function getUser(id: string) { const response = await fetch(`/api/users/${id}`); return response.json(); // Promise } // good async function getUser(id: string): Promise { const response = await fetch(`/api/users/${id}`); const data = await response.json(); return UserSchema.parse(data); } ``` **Using enums when a const object works:** ```ts // bad — generates runtime code, has weird behavior enum Status { Active = "active", Inactive = "inactive", } // good — zero runtime overhead const Status = { Active: "active", Inactive: "inactive", } as const; type Status = typeof Status[keyof typeof Status]; // "active" | "inactive" ```

## The tsconfig Worth Starting With ```json { "compilerOptions": { "target": "ES2022", "lib": ["ES2022", "DOM", "DOM.Iterable"], "module": "ESNext", "moduleResolution": "bundler", "verbatimModuleSyntax": true, "strict": true, "noUncheckedIndexedAccess": true, "exactOptionalPropertyTypes": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true, "skipLibCheck": true, "baseUrl": ".", "paths": { "@/*": ["./src/*"] } } } ``` Good starting point for a Next.js or Node.js project in 2026. Check what `moduleResolution` Next.js sets in its generated config before overriding it.

## Wrap Up TypeScript's value scales with how strictly you use it. Strict mode off, `any` everywhere, and loose assertions give you the syntax without any of the safety. The TypeScript best practices in this guide are the ones that actually move the needle, from catching bugs at compile time instead of in production, to making impossible states unrepresentable. Start with strict mode. Everything else follows. If you're building a TypeScript project and want your Kanban board, Vercel deployments, and analytics in one place instead of five separate tabs, check out [AdeptDev](https://adeptdev.io). Free for 7 days.

## What is the difference between `any` and `unknown` in TypeScript? `any` turns the type checker off entirely for that value. You can call methods that don't exist, assign it anywhere, and TypeScript stays silent. `unknown` accepts anything too but forces you to narrow the type before you can actually use it. If you're handling external data like API responses or user input, use `unknown` and validate it with a type guard or Zod. Use `any` only as a temporary escape hatch when migrating a JavaScript codebase to TypeScript. ## Should I use `type` or `interface` in TypeScript? Use `interface` for object shapes and public contracts, especially anything that might be extended or merged across files. Use `type` for unions, intersections, mapped types, and utility type compositions. The one practical difference is that interfaces support declaration merging and types don't. Pick a rule for each case and stay consistent. Mixing both randomly is the only real mistake here. ## What does TypeScript strict mode actually do? `strict: true` in `tsconfig.json` enables a bundle of checks that are off by default. The big ones are `strictNullChecks` (null and undefined are not assignable to other types), `noImplicitAny` (parameters without a type annotation error instead of defaulting to `any`), and `strictFunctionTypes` (function parameter types are checked more carefully). Together they catch an entire category of runtime errors at compile time. There's no good reason to ship a TypeScript project in 2026 without it. ## What does the `satisfies` operator do in TypeScript? `satisfies` validates a value against a type without widening the inferred type to match it. Without it, annotating a value as `Record` loses the specific literal types of each key. With `satisfies`, TypeScript checks the shape is correct but keeps the narrower inferred types available everywhere the value is used. ## How do you handle API response types safely in TypeScript? Don't cast with `as`. Casting tells TypeScript to trust you but does nothing at runtime. If the API returns something unexpected, your cast was wrong and TypeScript had no way to help. The right approach is Zod: define a schema, parse the response through it, and get both runtime validation and a TypeScript type from the same definition. The parse throws immediately if the data doesn't match instead of letting bad data propagate through your app. ## What are TypeScript utility types? Utility types are built-in generics that transform existing types. The most used ones are `Partial`, `Required`, `Pick`, `Omit`, `Record`, `ReturnType`, and `Awaited`. Learn these before writing custom mapped types. Most custom utility types in TypeScript codebases are just reinventions of something that already exists. ## What is a discriminated union in TypeScript? A discriminated union is a union type where every member has a shared literal property TypeScript uses to narrow the type. A `RequestState` type with a `status` field set to `"loading"`, `"success"`, or `"error"` is a discriminated union. TypeScript narrows automatically in a switch statement based on `status`, giving you access to the right properties in each branch. It's the correct way to model state because it makes impossible states unrepresentable. ## Is TypeScript worth it for a small project or solo developer? Yes. Setup takes a few minutes. The payoff starts immediately with autocomplete, inline errors, and safe refactoring. Most developers who skip TypeScript on small projects end up wishing they hadn't when the project grows past what they expected.