nextjs-check-route-types

Files (1)

• SKILL.md

SKILL.md (first lines)

# Next.js Route Type Checking

> This skill addresses **type-system correctness**, not agent-specific
> security. The patterns here close compile-time blind spots that allow
> runtime bugs and complicate review; they are NOT the load-bearing
> defense against any OWASP ASI / AST threat. The runtime hardening of
> route handlers is the responsibility of
> `skills/stack-specific/nextjs/server-action-safety/SKILL.md` and the
> universal `security/prompt-injection-defense` skill.

**Tradeoff:** Stricter route typing catches a class of integration bugs
at build time rather than at request time. Cost: per-PR friction when
Next.js's generated types (`.next/types/...`) lag behind route file
changes during local development.

---

## Why this matters

Next.js App Router generates route types from the file system shape
during `next dev` and `next build` (and `next typegen` on 15.5+):
`app/posts/[slug]/route.ts` produces a typed
`{ params: Promise<{ slug: string }> }` context argument. When those generated
types are stale (e.g., a new dynamic segment added but `next dev` hasn't
re-generated), the handler signature reverts to a permissive default and
runtime arguments flow through unchecked. Reviewers see "the types pass"
without realizing the types are vacuous.

This is a footgun across the entire surface area:

- `app/api/**/route.ts` handlers with implicit-`any` parameters.
- `app/[slug]/page.tsx` route segments with un-narrowed param types.
- `searchParams` accessed without runtime validation.
- Proxy (`proxy.ts`; `middleware.ts` before Next.js 16) reading headers
  without typing them.

None of these are security failures on their own. They're conditions
under which a separate runtime-validation gap (the actual security
control) hides because the type checker isn't complaining.

---

## Pattern 1 -- Always type route handler signatures explicitly

The compile-time signature for an App Router handler:

```ts
// app/api/posts/[slug]/route.ts
import { NextRequest, NextResponse } from 'next/server';

type RouteContext = {
  params: Promise<{ slug: string }>;
};

export async function GET(
  request: NextRequest,
  context: RouteContext,
): Promise<NextResponse> {
  const { slug } = await context.params;
  // ... handler body ...
  return NextResponse.json({ slug });
}
```

Explicit `NextRequest` (NOT bare `Request`) gives access to Next.js-
specific fields (`request.nextUrl`, `request.cookies`). Explicit
`RouteContext` ties the handler's expected dynamic segments to the file
path; a renamed segment that doesn't match `slug` is a compile error.

Note Next.js 15+ awaits `params` as a Promise. Older code with sync
params won't compile against newer Next.js without migration.

---

## Pattern 2 -- Validate `searchParams` at the route boundary

```ts
import { z } from 'zod';

const SearchSchema = z.object({
  page: z.coerce.number().int().positive().default(1),
  perPage: z.coerce.number().int().min(1).max(100).default(20),
  q: z.string().max(200).optional(),
});

export async function GET(request: NextRequest) {
  const parsed = SearchSchema.safeParse(
    Object.fromEntries(request.nextUrl.searchParams),
  );
  if (!parsed.success) {
    return NextResponse.json({ error: 'invalid query' }, { status: 400 });
  }
  const { page, perPage, q } = parsed.data;
  // ... use typed values, NOT raw searchParams ...
}
```

`searchParams` is `URLSearchParams`. Its `.get()` returns `string | null`;
there's no compile-time guarantee that the query string contains what
the handler assumes. Runtime validation closes the gap.

---

## Pattern 3 -- Regenerate types on dynamic-segment renames

When you rename `app/posts/[slug]/route.ts` to `app/posts/[postId]/route.ts`,
the next `next build` (or `next dev` HMR refresh) regenerates the
RouteContext types with the new param name. UNTIL that happens, the
handler still compiles against the old generated types.

Discipline: after any file-system rename inside `app/`, run
`next typegen && tsc --noEmit` (Next.js 15.5+; on older versions,
`next build`) before committing. Run the same pair in CI: plain
`tsc --noEmit` does not generate route types, so on its own it checks
against stale or missing `.next/types` and can pass.

---

## Anti-patterns

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs