Nextjs Architecture

@architecture-rules.md @rules/project-structure.md @rules/services.md @rules/hooks.md @rules/db.md @rules/routes.md @rules/execution-model.md @rules/data-fetching.md @rules/server-actions.md @rules/route-handlers.md @rules/platform.md @rules/validation.md @references/official/nextjs-docs.md @references/official/current-docs-2026-06-02.md @references/official/drizzle-docs.md

Next.js Architecture Enforcement

Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.

Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.

Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example *.ko.md or *.ko.json), prefer it for user-facing artifacts.

• Confirm a repository is a Next.js project and identify App Router, Pages Router, or mixed mode before enforcing architecture rules.
• Enforce official Next.js behavior for file conventions, Server/Client Component boundaries, data/cache behavior, Server Actions, Route Handlers, Proxy, and env/platform safety.
• Apply Hypercore/repo-local conventions for nested shared folders such as src/modules/<domain>/, src/services/<domain>/, src/db/<area>/, src/server/<area>/, src/integrations/<provider>/, and src/config/<area>/ without presenting them as official Next.js law.
• Route Drizzle, DAL/service boundaries, and client hook orchestration to focused rule files instead of bloating this entrypoint.
• Keep version-sensitive official facts in references/official/ so the core skill stays lean and current docs can be refreshed independently.

Use this skill for architecture enforcement, implementation guidance, or review in existing Next.js projects, especially App Router work, App Router migration, Server/Client boundaries, cache/freshness, Server Actions, Route Handlers, Proxy, env/platform safety, service/DAL boundaries, client hook orchestration, Drizzle/DB placement, and nested shared-folder organization.

Do not use this skill for generic React architecture, Remix/TanStack Start projects, docs-only summaries, or copy-only edits that do not touch architectural boundaries beyond a quick safety check. In Pages Router-only projects, apply shared Next.js safety/platform checks but do not force App Router-only file conventions unless migration is requested.

Overview

Enforce official Next.js architecture rules before and after code changes. First prove that the target is a Next.js project and identify whether it uses App Router, Pages Router, or both. Then apply the smallest relevant rule set for routing, Server and Client Component boundaries, data/cache behavior, Server Actions, Route Handlers, Proxy, and platform configuration.

Official-first rule: the current Next.js docs are the source of truth for framework behavior. If a repo-local convention is stricter than Next.js, label it as a local convention instead of framework law.

App Router default: full enforcement applies to app/ and src/app/ work. In Pages Router-only projects, apply shared Next.js platform, env, and boundary checks without forcing App Router-only file conventions unless the user is migrating.

Mutation default: for App Router UI-originated writes, prefer Server Actions. Use Route Handlers for HTTP-native contracts such as webhooks, feeds, CORS endpoints, public machine-readable endpoints, and non-UI responses.

Security default: treat every Server Action as a reachable POST entry point. Validate input, authenticate, authorize, and shape minimal return values inside the action or a delegated server-only layer.

Quick Surface Chooser

Positive examples:

• "Audit this Next.js App Router feature for Server/Client boundaries and cache correctness."
• "Refactor this form to use Server Actions instead of an internal route handler."
• "Add a Route Handler for a webhook and verify it follows the current Next.js docs."
• "Next.js 16 cacheComponents 기준으로 data fetching 규칙을 점검해줘."
• "Next.js App Router에서 src/lib/auth/session.ts와 src/services/billing/mutations.ts처럼 nested shared folders로 정리해줘."
• "Add Drizzle schema and migrations to this Next.js app without leaking DB access into client hooks."
• "Split this Next.js form into client hooks, Server Actions, and a server-only service/DAL."

Negative examples:

• "Create a generic React architecture guide."
• "Review a Remix or TanStack Start app."
• "Write marketing copy for a Next.js landing page without touching architecture."

Boundary examples:

• "Make a tiny copy-only text change in a Next.js page." Direct editing can be enough if no architectural boundary is affected, but touched files still need a quick boundary check.
• "This repo is Pages Router only and I am not migrating to App Router." Apply shared Next.js platform, env, and server/client safety checks; relax App Router-only file conventions.

Step 1: Project Validation

Before architectural work, confirm the project and router mode:

rg -n '"next"' package.json
find . -maxdepth 3 \( -path './app' -o -path './src/app' -o -path './pages' -o -path './src/pages' \)
test -f next.config.ts -o -f next.config.mjs -o -f next.config.js

Interpretation:

• No next dependency: stop; this skill does not apply.
• app/ or src/app/: App Router mode.
• pages/ or src/pages/ without App Router: shared Next.js mode.
• Mixed app/ and pages/: enforce App Router rules for touched app/ code and avoid legacy migration unless requested.

Step 2: Read the Smallest Relevant Rule Set

Required first read: architecture-rules.md.

Then load only the rule files needed for the touched surface:

• rules/routes.md — file conventions, segment rules, route groups, private folders, parallel/intercepted route cautions
• rules/project-structure.md — top-level project shape, src/, shared code placement, nested src/modules, src/services, src/db, src/server, src/integrations, src/config, repo-local organization conventions
• rules/services.md — DAL/service/provider boundaries, DTOs, authorization delegation, server-only helper splits
• rules/hooks.md — client hook orchestration boundaries and where hooks must not cross server/data layers
• rules/db.md — Drizzle schema/config/migrations, connection lifecycle, relations/RQB, validation integrations, server-only DB placement
• rules/execution-model.md — Server/Client Components, 'use client', providers, serializable props, server-only / client-only
• rules/data-fetching.md — server-first reads, streaming, Cache Components, use cache / use cache: remote / use cache: private, cache tags, revalidation, dynamic rendering
• rules/server-actions.md — use server, forms, validation, auth/authz, DAL delegation, updateTag / revalidation / redirect ordering
• rules/route-handlers.md — route.ts, HTTP methods, caching intent, params, non-UI responses, CORS/webhooks
• rules/platform.md — env, next.config.*, typedRoutes, Proxy, route segment config, deployment-sensitive settings

For drift-sensitive Next.js behavior, also read references/official/current-docs-2026-06-02.md first, then references/official/nextjs-docs.md and fetch official pages through https://r.jina.ai/https://nextjs.org/docs/... when browser-readable markdown is needed. For Drizzle-specific behavior, read references/official/drizzle-docs.md.

Step 3: Pre-Change Gates

Brownfield Adoption

• Do not fail untouched legacy deviations by default.
• Safety, secret, auth, and boundary issues block immediately in touched files.
• Bring touched files into compliance unless that requires a broad migration.

Gate 1: Routing, File Conventions, and Project Structure

Gate 2: Server and Client Boundaries

Gate 3: Data Fetching, Cache, and Freshness

Gate 4: Server Actions

Gate 5: Route Handlers and Proxy

Gate 6: Platform and Environment

Step 4: Implementation Policy

Auto-fix local, reversible issues: narrow client boundaries, move server-only code behind a DAL/helper, add server-only, add missing freshness, replace UI-only route.ts mutations with small Server Actions, tighten Proxy matcher, and clarify cache intent.

Do not auto-apply broad migrations: Pages→App Router rewrites, sweeping cache model changes, mass Route Handler→Server Action conversions, or deployment-sensitive origin/encryption changes.

Step 5: Post-Change Verification

Run the smallest project-specific checks that prove the claim, then report evidence:

1. project mode still matches the edited surface
2. special files are in valid segments and no page/route conflict exists
3. shared and segment-local folders follow project-structure rules, with nested src/lib / src/services grouping required for new touched shared code unless an explicit exception is recorded
4. 'use client' boundaries are narrow and safe
5. client code cannot import server-only modules or private env
6. data/cache strategy is explicit and current-docs compatible
7. mutation freshness uses updateTag, revalidateTag, revalidatePath, refresh, redirect flow, or a documented alternative
8. Route Handler and Proxy usage remains justified
9. next.config.*, env loading, route segment config, and deployment settings are coherent

For this skill folder itself, run:

node skills/nextjs-architecture/scripts/validate-nextjs-architecture-skill.mjs

Stop Condition

Finish when the Next.js mode is known, all touched surfaces pass the relevant gates, verification output is fresh, and any remaining repo-local convention or risk is explicitly reported.