Next.js API Routes

Route handler basics

// app/api/feedback/route.ts
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  return NextResponse.json({ ok: true });
}

export const runtime = "nodejs"; // when Playwright/sharp/fs needed

Zod validation

const schema = z.object({
  email: z.string().email(),
  message: z.string().min(1).max(5000),
});

export async function POST(req: Request) {
  const body = await req.json().catch(() => null);
  const parsed = schema.safeParse(body);
  if (!parsed.success) {
    return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
  }
  // use parsed.data
}

Colocate schemas in lib/schemas/*.schema.ts + unit tests.

Reusable POST factory (optional)

export function createPostRoute<T>(opts: {
  schema: z.ZodType<T>;
  handler: (data: T, req: Request) => Promise<void>;
  rateLimitKey?: string;
}) {
  return async function POST(req: Request) {
    if (opts.rateLimitKey && !(await checkRateLimit(req, opts.rateLimitKey))) {
      return NextResponse.json({ error: "Too many requests" }, { status: 429 });
    }
    const parsed = opts.schema.safeParse(await req.json());
    if (!parsed.success) return NextResponse.json({ error: "Invalid input" }, { status: 400 });
    try {
      await opts.handler(parsed.data, req);
      return NextResponse.json({ ok: true });
    } catch (e) {
      return NextResponse.json({ error: "Server error" }, { status: 500 });
    }
  };
}

Rate limiting

In-memory for dev; Upstash Redis for production:

export async function checkRateLimit(req: Request, bucket: string, limit = 10, windowSec = 60) {
  const ip = req.headers.get("x-forwarded-for") ?? "anonymous";
  // increment counter for `${bucket}:${ip}` in Redis or Map
}

Return 429 with Retry-After when exceeded.

Feature flags (503 when disabled)

if (!isEmailConfigured()) {
  return NextResponse.json({ error: "Feature not configured" }, { status: 503 });
}

Never leak stack traces to client in production.

Security checklist

- [ ] Validate all input with Zod
- [ ] Rate-limit public POST routes
- [ ] Secrets only in server env (no NEXT_PUBLIC_)
- [ ] Escape user content in HTML emails
- [ ] CSRF: same-site cookies or nonce for sensitive actions
- [ ] Cap payload/attachment size

Anti-patterns

• Trusting client-only validation
• Returning 200 with { error: "..." } instead of proper status codes
• Constructing Resend/DB clients at module top level without env check
• Logging PII in error handlers

Pair with: resend-email-nextjs, vitest-unit-testing.