TypeScript kontrakty Next.js App Router

TypeScript jako systém kontraktů v Next.js App Router

V Next.js App Router funguje TypeScript jako systém kontraktů mezi vrstvami: server-klient, externí vstup-doména, vstup-entita, mutace-UI. Místo anotací nad kódem typy vylučují nepřípustné stavy na hranicích. To zvyšuje odolnost projektu bez zbytečného kódu.

Klíčové oblasti kontraktů:

• Přenos payload ze Server Component do Client Component
• Parsování params a searchParams na vstupu
• Normalizace doménových entit
• Výsledky mutací s předvídatelnými stavy

Kontrakt server-to-client přes payload

Přenos dat ze serveru do klienta je kritická hranice. Bez typizovaného payload se klient spoléhá na dohady o struktuře, server posílá libovolné objekty.

Definujeme typ payload:

// src/demo/contracts.ts
export type HelloPayload = {
  appName: string;
  renderedAt: string;
  mode: "server-to-client";
  initialNotes: DemoNote[];
};

Serverová stránka sbírá data striktně podle kontraktu:

// src/app/(demo)/demo-contract/page.tsx
import type { HelloPayload } from "@/demo/contracts";
import { getNotes } from "@/demo/notesStore";
import HelloClient from "./HelloClient";

export default function DemoContractPage() {
  const payload: HelloPayload = {
    appName: "Workbench Notes",
    renderedAt: new Date().toISOString(),
    mode: "server-to-client",
    initialNotes: getNotes(),
  };

  return <HelloClient payload={payload} />;
}

Tento přístup zaručuje serializovatelnost a konzistenci. Hranice server/client v App Router určuje renderování, závislosti a tok dat.

Normalizace externího vstupu na hranici

Params a searchParams přicházejí jako string | string[] | undefined. Protahování surového vstupu do domény vede k type assertion a kontrolám v celém stromu.

Správný přístup je parsování na hranici:

// src/demo/noteId.ts
export function parseNoteId(value: unknown): DemoNoteId | null {
  if (typeof value !== "string") return null;

  const v = value.trim();

  if (!/^n\\d+$/.test(v)) return null;

  return v;
}

Utility pro searchParams:

// src/lib/searchParams.ts
export type StringParamValue = string | string[] | undefined | null;

export function getStringParam(value: StringParamValue): string | undefined {
  if (typeof value === "string") return value;
  if (Array.isArray(value)) return value[0];
  return undefined;
}

Po normalizaci kód pracuje s platnými hodnotami, TypeScript nezasahuje do vnitřní logiky.

Nevyjádřitelné stavy v doménových entitách

Typy vylučují logicky nemožné kombinace. Entita je vždy úplná a konzistentní:

type DemoNoteStatus = "draft" | "published" | "archived";
type DemoNotePriority = 1 | 2 | 3;

type DemoNote = {
  id: DemoNoteId;
  title: string;
  status: DemoNoteStatus;
  priority: DemoNotePriority;
  tags: string[];
  description: string;
  createdAt: IsoDateString;
  updatedAt: IsoDateString;
};

Vstupní typ připouští neúplná data:

type DemoNoteCreateInput = {
  title: string;
  status?: DemoNoteStatus;
  priority?: DemoNotePriority;
  tags?: string[];
  description?: string;
};

Sestavení s výchozími hodnotami:

// src/demo/notesStore.ts
export function createNote(input: DemoNoteCreateInput): DemoNote {
  const id: DemoNoteId = `n${Date.now()}`;
  const t = new Date().toISOString();

  const note: DemoNote = {
    id,
    title: input.title.trim(),
    status: input.status ?? "draft",
    priority: input.priority ?? 2,
    tags: input.tags ?? ["new"],
    description: input.description ?? "",
    createdAt: t,
    updatedAt: t,
  };

  notes = [note, ...notes];
  return note;
}

UI pracuje s předvídatelnými objekty bez kontrol.

Zpracování chyb TypeScript jako signálů kontraktů

Type is not assignable signalizuje porušený kontrakt, ne lokální chybu:

// Správně
export function demo_id_barrier(raw: string) {
  const noteId = parseNoteId(raw);
  if (!noteId) return null;

  return getNoteById(noteId);
}

// Nesprávně
export function demo_bad_fix(raw: string) {
  const unsafeId = raw as any;
  return getNoteById(unsafeId);
}

Possibly undefined řeší guardy:

export function demo_parseNoteId(raw: string) {
  const noteId = parseNoteId(raw);

  if (!noteId) return null;

  return getNoteById(noteId);
}

Ranný return zužuje typ pro TypeScript.

Union-typy pro stavy operací

Místo příznaků isLoading/hasError použijte discriminated union:

export type ActionResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: string };

export function ok<T>(data: T): ActionResult<T> {
  return { ok: true, data };
}

export function fail(error: string): ActionResult<never> {
  return { ok: false, error };
}

Automatické zužování typu:

export function demo_narrowing() {
  const state = createResult(Math.random() > 0.5);

  if (!state.ok) {
    return state.error;
  }

  return state.data.title;
}

Nelogické stavy jsou nemožné.

Co je důležité:

• TypeScript fixuje kontrakty na hranicích server/client, params/doména, vstup/entita
• Nevyjádřitelné stavy vylučují runtime-chyby v UI
• Chyby TS jsou signály porušených kontraktů, ne lokální problémy
• Union-typy nahrazují příznaky stavy operací
• Normalizace externího vstupu na hranici zjednodušuje vnitřní kód

— Editorial Team