Imported from prowler-cloud/prowler (
skills/nextjs-16/SKILL.md). Install upstream withnpx skills add prowler-cloud/prowler --skill nextjs-16. Copyright stays with the author (Apache-2.0).
App Router File Conventions
app/
├── layout.tsx # Root layout (required)
├── page.tsx # Home page (/)
├── loading.tsx # Loading UI (Suspense)
├── error.tsx # Error boundary
├── not-found.tsx # 404 page
├── (auth)/ # Route group (no URL impact)
│ ├── login/page.tsx # /login
│ └── signup/page.tsx # /signup
├── api/
│ └── route.ts # API handler
└── _components/ # Private folder (not routed)
Next.js 16 Notes
- Next.js ships docs for the installed version in
ui/node_modules/next/dist/docs/(01-app/,03-architecture/...). Read the relevant page before version-sensitive work; it beats training data and this summary. - Prowler UI runs Next.js 16.4 with
reactCompiler: trueand Turbopack (ui/next.config.js). Cache Components (cacheComponents) is NOT enabled. - Never pass functions from a Server Component to a Client Component (for example a
labelFormatterin filter config). TypeScript and jsdom tests accept it; the real page throws. - Request APIs are async:
await cookies(),await headers(), andparams/searchParamsarePromises in pages, layouts and route handlers. - Use
proxy.tsfor request-boundary logic.middleware.tsis deprecated in Next.js 16. Prowler'sui/proxy.tsisexport default auth(async (req) => ...)(NextAuth v5 wrapper). proxy.tsruns on the Node.js runtime and cannot be configured for Edge.- Keep
proxy.tsmatchers narrow. Excludeapi, static files, and image assets unless the route explicitly needs proxy logic. - Route Handlers in
app/api/**/route.tsare the right fit for health checks, webhooks, backend-for-frontend endpoints, and server-only proxy calls.
Server Components (Default)
// No directive needed - async by default
export default async function Page() {
const data = await db.query();
return <Component data={data} />;
}
Server Actions
"use server";
import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
export async function createUser(formData: FormData) {
const name = formData.get("name") as string;
await db.users.create({ data: { name } });
revalidatePath("/users");
redirect("/users");
}
Async params / searchParams
export default async function Page({
params,
searchParams,
}: {
params: Promise<{ id: string }>;
searchParams: Promise<Record<string, string | string[] | undefined>>;
}) {
const { id } = await params;
const query = await searchParams;
return <Detail id={id} query={query} />;
}
Data Fetching
async function Page() {
const [users, posts] = await Promise.all([getUsers(), getPosts()]);
return <Dashboard users={users} posts={posts} />;
}
<Suspense fallback={<Loading />}>
<SlowComponent />
</Suspense>;
Caching and Revalidation
import { revalidatePath, revalidateTag } from "next/cache";
export async function refreshDashboard() {
"use server";
revalidatePath("/");
revalidateTag("dashboard", "max"); // Next 16: second arg (cacheLife profile) is required
}
- Use
revalidatePathfor route-level invalidation after mutations. - Use
revalidateTag(tag, profile)when data fetches share a cache tag across routes. The single-argument form is deprecated in Next.js 16 (seeui/actions/api-keys/api-keys.ts). - With Cache Components enabled, put
"use cache"only in pure server-side cached functions. Do not cache auth, tenant-scoped, or per-user responses unless the cache key explicitly isolates them.
Route Handlers (API)
// app/api/users/[id]/route.ts
import { NextResponse } from "next/server";
export async function GET(
_req: Request,
{ params }: { params: Promise<{ id: string }> },
) {
const { id } = await params;
return NextResponse.json(await db.users.find(id));
}
export async function PATCH(
request: Request,
{ params }: { params: Promise<{ id: string }> },
) {
const { id } = await params;
const user = await db.users.update(id, await request.json());
return NextResponse.json(user);
}
Proxy
// proxy.ts (root level)
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
export function proxy(request: NextRequest) {
const token = request.cookies.get("token");
if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
return NextResponse.redirect(new URL("/login", request.url));
}
return NextResponse.next();
}
export const config = {
matcher: ["/dashboard/:path*"],
};
Metadata
export const metadata = {
title: "My App",
description: "Description",
};
export async function generateMetadata() {
const product = await getProduct();
return { title: product.name };
}
server-only Package
import "server-only";
export async function getSecretData() {
return db.secrets.findMany();
}