Next.js App Architecture

A workflow for building and auditing Next.js 16+ App Router apps so they follow one consistent, feature-sliced RSC architecture like next-beats.

Follow the workflow below step by step — it produces the invariants by construction. Load the reference a step names for the decision it depends on. Get framework mechanics (API signatures, config options, hook contracts) from the linked docs — don't restate or improvise them.

Prerequisite

Before changing a Next.js app, make sure the project is set up for AI agents to read version-matched docs. Follow the AI Coding Agents guide: prefer the project's AGENTS.md / bundled docs, and create or refresh them when missing. Then use this skill for architecture decisions.

Architecture target

Build pages that describe the loading experience, not pages that act like route loaders:

• app/**/page.tsx and layout.tsx are synchronous composition surfaces: static chrome, section headings, <Suspense> boundaries, error boundaries, and transition wrappers.
• Feature components own their reads on the server. They receive minimal stable inputs (id, slug, handle, parsed filter values) or already-fetched records, never raw params / searchParams.
• Queries and actions live in the feature folder. Components import queries; client leaves import actions directly.
• When server tags and client query keys describe the same feature data, a pure feature-local cache contract owns those identities.
• Stable chrome, wrappers, and skeletons preserve layout: cards/panels stay outside Suspense, and fallbacks swap only the data-dependent body.