DX
Unpacked

Good DX is a well organised kitchen: every knife has its place, labels say what is in each jar, and the smoke alarm goes off before the food burns, not after the guests arrive.

Optimise for the reader, because code is read far more than written. Pick one convention and automate it rather than debating it. Push feedback left: the editor (types, lint) catches more than CI, and CI catches more than production. Make the right way the easy way with templates, scripts and strict defaults.

Cases are like the dress code for words. The same person wears a suit to court, a uniform at work and pyjamas at home. userAccountId, UserAccount, user_account_id and user-account-id are the same idea dressed for different places.

Cases differ in two things: how words are separated (capital letters, underscore, hyphen, dot or nothing) and whether letters are upper or lower. In a TypeScript backend you meet camelCase for values, PascalCase for types, SCREAMING_SNAKE_CASE for environment variables, snake_case in SQL, kebab-case in files and URLs, dot.case in event names and Train-Case in HTTP headers. Treat acronyms as words: userId, HttpClient, parseJson.

Like a map of a building with every room labelled. You do not decide which door is the kitchen each morning; you read the sign.

Code identifiers follow TypeScript norms: camelCase values, PascalCase types and classes, UPPER_CASE for module level constants. Outside code, follow the host system: SQL is snake_case, URLs and files are kebab-case, env vars are SCREAMING_SNAKE_CASE, HTTP headers are Train-Case, and JSON keys match your API style (camelCase is the common choice for TypeScript APIs). Enforce the code side with @typescript-eslint/naming-convention.

Labels on storage boxes. "Stuff" helps nobody; "Winter jackets, kids, 2025" tells you what is inside without opening it.

Use nouns for values and plurals for collections (orders, orderById for maps). Booleans read as yes or no questions with is, has, can, should or did. Put units in the name when the type cannot (timeoutMs, priceInPaise, sizeBytes). Avoid abbreviations except universal ones (id, url, db), single letters except tiny loops, and noise words such as data, info, temp or obj. Name length should grow with scope.

A to do list item. "Invoice" is vague; "send the invoice to the customer" tells you exactly what will happen when you tick it.

Use verbNoun in camelCase. Pick verbs consistently across the codebase: get for cheap in memory reads, find for queries that may return nothing, fetch or load for network or database calls, create, update, delete or remove for writes, build or to for pure transforms, and is, has or can for predicates. Event handlers are handleX or onX. A name that needs "and" is two functions.

A magic number is a sticky note that just says "42". A constant is the same note saying "maximum seats per table: 42". One you can trust; the other you must investigate.

Name literals with business meaning (MAX_RETRIES, DEFAULT_PAGE_SIZE) in SCREAMING_SNAKE_CASE at module level. For fixed sets, prefer an as const object plus a derived union type, which has no runtime surprises and works with plain strings from JSON; TypeScript enums are fine in NestJS codebases that already use them, but avoid numeric enums. Use a never check in switch statements so adding a value breaks the build where it is not handled.

A type is the shape of a mould. A clear mould (PaymentMethod is either a card or UPI) makes impossible shapes impossible, instead of one blob with every field optional.

Use PascalCase with no I or T prefixes (User, not IUser). interface suits object shapes that classes implement or that may be extended; type suits unions, mapped and utility types; pick one default per team. Suffix boundary types by role: CreateOrderDto, OrderResponse, OrderRow. Model states with discriminated unions on a kind or status field. Generic parameters are T for one, or descriptive with a T prefix such as TItem, TKey when there are several.

A form with labelled boxes beats a row of unlabelled ones. createUser("Asha", true, false, 3) is a row of blanks; createUser({ name: "Asha", isAdmin: true }) is a filled form.

Exported functions get explicit parameter and return types, which documents the contract and stops accidental changes. With more than two parameters, or any boolean flag, take a single named options object with defaults. Mark inputs readonly when you do not mutate them. Use unknown, never any, for truly unknown data and narrow it. Brand ids (type OrderId = string & { readonly __brand: "OrderId" }) so a userId cannot be passed as an orderId.

Organise a house by room, not by object type. All the kitchen things live in the kitchen; you do not keep every spoon in the house in one "spoons" room.

Use feature folders (orders/, payments/) rather than layer folders (controllers/, services/) once a service grows. Files are kebab-case with a role suffix, matching NestJS style: order.controller.ts, order.service.ts, create-order.dto.ts, order.service.test.ts. One main export per file, named like the file. Keep barrel index.ts files to public module boundaries only, since deep barrels slow builds and cause circular imports. Use path aliases for long relative paths.

Compiler flags are the smoke alarms in your house. Each one is cheap to install, slightly annoying when it beeps, and far cheaper than the fire it prevents.

strict enables strictNullChecks, noImplicitAny, useUnknownInCatchVariables and more. Add noUncheckedIndexedAccess so array and record lookups include undefined, exactOptionalPropertyTypes so optional does not secretly accept undefined, noImplicitOverride, noFallthroughCasesInSwitch and verbatimModuleSyntax for clean imports. Use module and moduleResolution NodeNext for Node backends. Run tsc --noEmit in CI.

A security check at the airport entrance. Everyone is checked once at the door, so nobody needs to be checked again at every gate.

Request bodies, query strings, headers, webhooks, queue messages, env vars and third party responses are unknown until parsed. Define a schema once (Zod, or class-validator DTOs in NestJS), parse at the edge, and derive the TypeScript type from the schema with z.infer so they never drift. Return 400 with field level messages. Coerce query strings deliberately, and strip unknown keys.

A goalkeeper should catch the ball only when they can do something with it. Catching every shot and quietly hiding it behind the goal just means nobody knows the score.

Under strict, the catch variable is unknown: narrow with instanceof before reading .message. Catch at a level that can recover, retry, translate or add context; otherwise let it propagate to one global handler. When rethrowing, wrap with new Error(msg, { cause }) so the original stack survives. Use finally for cleanup such as releasing a DB client. Log an error once, where it is handled, not at every layer.

Hospital triage tags. Each problem gets a coloured tag (not found, invalid, conflict) at the source, and the front desk reads the tag to decide what to tell the visitor.

Create a base AppError with a stable code, an HTTP status and safe details, then subclasses such as NotFoundError, ConflictError and ValidationError. Services throw domain errors and never know about HTTP. One exception filter (NestJS) or error middleware (Express) maps them to responses, ideally Problem Details (RFC 9457), and returns a generic 500 for anything unknown while logging it in full. For expected outcomes you prefer not to throw, a Result type works well.

Cooking a meal. Boil the pasta and fry the sauce at the same time (parallel), never walk away from the stove forever (timeouts), and never forget a pot on the burner (floating promises).

A promise that is neither awaited nor handled is a floating promise: its error becomes an unhandled rejection that can crash Node. Turn on @typescript-eslint/no-floating-promises and no-misused-promises. Use Promise.all for independent work that must all succeed, Promise.allSettled when partial results are fine, and AbortSignal.timeout(ms) with fetch. Avoid await inside loops when items are independent; cap concurrency for large batches.

When you visit another country, you drive on their side of the road. URLs, JSON and SQL each have their own road rules; your TypeScript habits stay at home.

Routes are lowercase kebab-case plural nouns with ids in the path (/v1/user-accounts/42/payment-methods); verbs come from HTTP methods, not URLs. Query params and JSON fields are camelCase in TypeScript APIs; pick one style and never mix. SQL tables and columns are snake_case (Postgres folds unquoted identifiers to lowercase); name timestamps created_at and updated_at, foreign keys user_id, and indexes idx_table_columns. Map snake_case rows to camelCase objects in the repository layer.

A pilot's preflight checklist. Every gauge is checked before take off, so you never discover the missing fuel at 30,000 feet.

Env names are SCREAMING_SNAKE_CASE with a clear prefix per concern (DATABASE_URL, REDIS_URL, JWT_SECRET, PAYMENT_API_KEY). Parse process.env once with a schema, coerce types (PORT to a number), apply defaults, and export a typed, frozen config object. Never read process.env elsewhere. Commit .env.example with every key and no secrets; keep real secrets in a secret manager. NestJS ConfigModule supports a validate function for this.

A ship's logbook. Each entry has the time, who wrote it and what happened, in the same format every time, so anyone can reconstruct the voyage after a storm.

Log objects, not sentences, with a fast JSON logger such as pino. Attach a requestId (from X-Request-Id or generated) to every log in a request via a child logger or AsyncLocalStorage, and return it in the response so support can find it. Use levels deliberately: error needs action, warn is unusual but handled, info records business events, debug is for development. Redact tokens, passwords and personal data. Log an error once with its stack and cause.

A spell checker and an autocorrect for code. You stop arguing about commas in review because the tools fix them before anyone sees the draft.

Prettier owns formatting; ESLint owns correctness, using the flat config with typescript-eslint's recommendedTypeChecked rules so it can see types (floating promises, unsafe any). Disable ESLint formatting rules with eslint-config-prettier. husky runs lint-staged on commit (only changed files, fast) and commitlint on the message. CI runs the same checks on everything. An .editorconfig keeps editors consistent.

Comments are the margin notes a good teacher leaves: not repeating the textbook, but explaining the tricky bit and why it matters. Commit messages are diary entries future you will thank you for.

Prefer renaming over commenting. Write comments for intent, constraints and surprises ("Gateway rejects amounts below 100 paise"), plus links to tickets for workarounds. Document exported functions with TSDoc (@param, @returns, @throws, @example) so editors show it on hover. Use Conventional Commits: type(scope): summary, with feat, fix, refactor, perf, test, docs, chore and BREAKING CHANGE footers. Branches follow type/ticket-short-description in kebab-case. Record big decisions in short ADRs.

Tests are a safety net under a trapeze. A good net is close, catches you fast and tells you exactly where you slipped; a tangled one just gets in the way.

Name test files after the unit (order.service.test.ts) and cases as behaviour in plain words: it("rejects refunds for unpaid orders"). Structure each test as Arrange, Act, Assert. Prefer fakes and in memory repositories over deep mocks, and test public behaviour so refactors do not break tests. Keep unit tests in milliseconds; run integration tests against a real database in containers. Vitest and Jest share most APIs; NestJS's Test.createTestingModule wires providers.