Typescript

satisfies over type annotations

Use satisfies when you want validation against a type but need to preserve literal inference:

// WRONG: loses literal type information
const config: Config = { theme: "dark", retries: 3 };

// CORRECT: validates against Config but preserves literals
const config = { theme: "dark", retries: 3 } as const satisfies Config;
// config.theme is "dark", not string

Branded types for domain identifiers

For identifying which concepts need branded types (entities vs value objects, aggregate boundaries), see the Domain Design skill (/domain-design §3-4).

Prevent mixing semantically different values that share the same primitive type:

type UserId = string & { readonly __brand: unique symbol };
type OrderId = string & { readonly __brand: unique symbol };

function createUserId(id: string): UserId { return id as UserId; }
function createOrderId(id: string): OrderId { return id as OrderId; }

function getUser(id: UserId): User { /* ... */ }
getUser(orderId); // compile error

Discriminated unions for state machines

Eliminate impossible states:

type FetchState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

No data on error, no error on success. Enables exhaustive switch narrowing.

Anti-patterns

• Never use any — use unknown and narrow, or use generics
• Never use as for type assertions unless you've proven correctness (prefer type guards)
• Never use // @ts-ignore — use // @ts-expect-error with an explanation if truly needed
• Never use enum — use as const objects or string literal unions (enums have runtime footprint and tree-shaking issues)

// WRONG
enum Status { Active, Inactive }

// CORRECT
const Status = { Active: "active", Inactive: "inactive" } as const;
type Status = (typeof Status)[keyof typeof Status];

2. Testing

Layered strategy

1. Unit tests (Vitest): Pure functions, hooks, validation schemas. Fast feedback loop.
2. Component tests (Vitest + Testing Library): User-facing behavior with userEvent.
3. Integration tests (Vitest + MSW): Full component trees with mocked API responses.
4. E2E tests (Playwright): Critical user journeys — keep each spec focused on one journey.

Layer selection

Universal principles for deciding which layer a test belongs in:

• Push tests down — test at the lowest layer that gives confidence. Unit > component > integration > E2E. Higher layers are slower, flakier, and harder to debug
• No duplication across layers — if E2E covers a behavior and a unit test proves the helper, don't add a middle-layer test that re-proves both. Fowler's rule: "higher-level test failure without lower-level failure signals a missing lower-level test"
• Static analysis is the foundation — TypeScript strict mode + ESLint rules catch bugs that unit tests traditionally caught. The testing trophy's base layer
• E2E = journeys, not features — test "user signs in, creates an item, sees the list update" not "name field validates correctly." Feature-level validation belongs in unit/component tests
• Integration tests are highest-ROI — they balance confidence (real dependencies) with speed (no browser). Both the testing trophy (Dodds) and Google testing research confirm this

Test user behavior, not implementation

// WRONG: testing implementation details
expect(component.state.isOpen).toBe(true);

// CORRECT: testing what the user sees
await userEvent.click(screen.getByRole("button", { name: /open menu/i }));
expect(screen.getByRole("menu")).toBeVisible();

Use userEvent over fireEvent

userEvent simulates real user interactions (focus, hover, type individual characters). fireEvent dispatches raw DOM events that skip browser behavior:

// WRONG
fireEvent.change(input, { target: { value: "hello" } });

// CORRECT
await userEvent.type(input, "hello");

MSW for API mocking

Mock at the network layer, not at the module layer. Reuse handlers across Vitest and Playwright:

import { http, HttpResponse } from "msw";

export const handlers = [
  http.get("/api/resources", () => {
    return HttpResponse.json([{ id: "1", name: "Test" }]);
  }),
];

Declare assertion count upfront

Always open every test with expect.assertions(N) where N is the total number of expect() calls in the test body. This prevents tests from silently passing when assertions are inside conditionals that never execute.

// WRONG — passes vacuously if body.intent is never "field_errors"
it("returns field errors on bad input", async () => {
  const { body } = await callAction({ email: "bad" });
  if (body.intent === "field_errors") {
    expect(body.errors.email).toBeTruthy();
  }
});

// CORRECT — fails if the expect() inside the if never ran
it("returns field errors on bad input", async () => {
  expect.assertions(2);
  const { body } = await callAction({ email: "bad" });
  expect(body.intent).toBe("field_errors");
  if (body.intent === "field_errors") {
    expect(body.errors.email).toBeTruthy();
  }
});

Count every expect() call, including those inside if branches, .forEach, and try/catch blocks.

Stop using snapshot tests

Snapshots create noise, break on any DOM change, and discourage TDD:

// WRONG
expect(container).toMatchSnapshot();

// CORRECT: explicit assertions on what matters
expect(screen.getByRole("heading")).toHaveTextContent("Dashboard");
expect(screen.getByTestId("item-count")).toHaveTextContent("42");

Playwright best practices

• Use locators (not CSS selectors): page.getByRole("button", { name: "Submit" })
• Enable retries for flaky-resilient assertions
• Use page.waitForResponse for API-dependent assertions
• Test only critical user flows — unit and component tests cover the rest

3. Performance

React Compiler

React Compiler (stable in React 19) automatically memoizes at build time:

• Remove useMemo, useCallback, and React.memo from new code
• Keep manual memoization only for identity-critical paths (e.g., callbacks passed to non-React libraries that use reference equality)
• Enable via bundler plugin:

// vite.config.ts
import reactCompiler from "babel-plugin-react-compiler";

Code splitting by route

The minimum viable optimization — 40-60% initial bundle reduction:

const ResourceDetail = React.lazy(() => import("./routes/resource-detail"));

Bundle analysis

Mandatory for production applications:

// vite.config.ts
import { visualizer } from "rollup-plugin-visualizer";