Skip to content
Back to search

nextjs-app-architecture-skill

An agent skill for building and auditing Next.js 16+ App Router applications.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aurorascharff--nextjs-app-architecture-skill/badge.svg)](/listings/aurorascharff--nextjs-app-architecture-skill)

HTML

<a href="/listings/aurorascharff--nextjs-app-architecture-skill"><img src="/api/listings/aurorascharff--nextjs-app-architecture-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add aurorascharff/nextjs-app-architecture-skill

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 115 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: nextjs-app-architecture
  3. description: Build or audit Next.js 16 App Router apps using a next-beats-style React Server Components architecture. Use when scaffolding a new app, adding a feature, reviewing an existing app, refactoring route-loader-shaped pages into feature-owned async server components, deciding where queries/actions/components live, keeping pages synchronous with `params.then()`, placing Suspense boundaries, choosing the client/server boundary, designing skeletons, preventing CLS, or enabling Cache Components. Also use when the user asks about RSC composition, components receiving IDs instead of route params, `'use cache'`, `cacheTag`, `updateTag`, static-shell prerendering, or making an app easier for AI agents to modify.
  4. license: MIT
  5. metadata:
  6. author: aurorascharff
  7. version: "1.4.1"
  8. ---
  9. # Next.js App Architecture
  10. A workflow for building and auditing Next.js 16+ App Router apps so they follow one consistent, feature-sliced RSC architecture like `next-beats`.
  11. **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. Links for canary-only Next.js APIs use `preview.nextjs.org`.
  12. ## Prerequisite
  13. 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](https://preview.nextjs.org/docs/app/guides/ai-agents): prefer the project's `AGENTS.md` / bundled docs, and create or refresh them when missing. Then use this skill for architecture decisions.
  14. ## Architecture target
  15. Build pages that describe the loading experience, not pages that act like route loaders:
  16. - `app/**/page.tsx` and `layout.tsx` are synchronous composition surfaces: static chrome, section headings, `<Suspense>` boundaries, error boundaries, and transition wrappers.
  17. - 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`.
  18. - Queries and actions live in the feature folder. Components import queries; client leaves import actions directly.
  19. - When server tags and client query keys describe the same feature data, a pure feature-local cache contract owns those identities.
  20. - Stable chrome, wrappers, and skeletons preserve layout: cards/panels stay outside Suspense, and fallbacks swap only the data-dependent body.
  21. ## Invariants (what every change must satisfy)
  22. The non-negotiables. The workflow produces them; the final check verifies them.
  23. 1. **Pages compose, they never fetch.** A page/layout imports feature components and places `<Suspense>`. No queries or domain logic inline. Tiny route-local control-flow helpers are allowed only when they exist to place a boundary around `connection()`, `redirect()`, or a resolved route prop.
  24. 2. **Pages stay synchronous.** Use `params.then()` / `searchParams.then()` or `Promise.all([params, searchParams]).then(...)`, never `await params` at the top — so chrome paints into the static shell and only data-dependent sections suspend.
  25. 3. **Feature components receive IDs, not route props.** Resolve `params` / `searchParams` at the page boundary and pass plain values (`id`, `slug`, `query`) into features.
  26. 4. **Async server component is the default.** `'use client'` only for hooks, event handlers, or browser APIs — and only on leaves, never on parents of server content.
  27. 5. **The page owns the Suspense boundary; the feature owns the skeleton.** Features never pre-wrap themselves in `<Suspense>`; stable wrappers/cards/chrome wrap the boundary instead of being duplicated in fallback and final content.
  28. 6. **Skeletons live in the same file as the component**, exported alongside it, defined at the end. `Feed` and `FeedSkeleton` are siblings.
  29. 7. **Queries live in `<domain>-queries.ts`** (`import 'server-only'`); **actions live in `<domain>-actions.ts`** (`'use server'`). The file name matches the folder, even for sub-concepts.
  30. 8. **Feature folders follow product ownership.** Entity-owned sub-concepts (favorite, like, vote, bookmark) fold into their parent. A route-level experience that composes multiple domains may own its UI and state in a separate feature while each domain keeps its queries and actions.
  31. 9. **Client components import actions directly** — never receive a server action as a prop just to call it.
  32. 10. **Feature-local cache coordination stays with its domain.** Put pure tags/keys in `<domain>-cache.ts`, client query definitions in `<domain>-query-options.ts`, hook wrappers in `hooks/use-*.ts`, and tiny client leaves in `components/`; promote support code only after real cross-feature reuse.
  33. 11. **Interactive async UI keeps server data on the server and client state local to the interaction.** Use `useOptimistic`, `useTransition`, reducers, URL/search params, and form actions instead of mirrored prop state, derived-state effects, or hand-rolled pending arrays.
  34. ## Workflow
  35. Run these in order for build-from-scratch, feature work, or audits. Each step names the reference to consult and the check it must pass.
  36. 1. **Choose mode.**
  37. - **Build from scratch:** sketch routes, real domain nouns, static shell, and expected loading groups before writing code.
  38. - **Audit/refactor:** scan current `app/` pages first; list every async page, page-level query import, route prop leak, missing Suspense boundary, and feature folder mismatch.
  39. → `references/example.md` for the target shape; `references/feature-folders.md` for placement.
  40. ✓ You know whether you are creating the architecture or converting loader-shaped code into it.
  41. 2. **Place the work.** Decide the feature folder before writing anything.
  42. → `references/feature-folders.md` (decision tree + merge rules).
  43. ✓ A real domain, a cross-domain product experience, or folded into the right parent.
  44. 3. **Write the query and, when a client cache shares its data, the cache contract.** Put server reads in `<domain>-queries.ts` with `import 'server-only'`; keep shared tag/key identities in a pure `<domain>-cache.ts`.
  45. → `references/queries-actions.md`; for SWR/TanStack Query → `references/single-page-applications.md`; with `cacheComponents: true`, also → `references/cache-components.md`.
  46. ✓ Cache identities are defined once; server reads are server-only, cached/tagged/lifetimed under Cache Components, and return domain types rather than ORM rows.
  47. 4. **Write the action** (if there's a mutation). `features/<domain>/<domain>-actions.ts`, `'use server'` at the top.
  48. → `references/queries-actions.md`.
  49. ✓ Re-checks auth, validates input, invalidates matching cache tags under Cache Components (`refresh()` only for justified dynamic reads), returns a discriminated union.
  50. 5. **Build the component + skeleton.** `features/<domain>/components/<name>.tsx`: an async server component that awaits its own query from minimal props; `'use client'` only on interactive leaves.
  51. → `references/components.md`; for a client data library or strict-SPA/CSR feature → `references/single-page-applications.md`.
  52. ✓ Component receives IDs/handles/parsed filters or already-resolved records, not `params`; skeleton is a sibling export at the end; no alias skeleton wrappers.
  53. 6. **Compose the page.** `app/<route>/page.tsx`: synchronous, `params.then()` / `Promise.all(...).then(...)`, place Suspense around data bodies, and wrap the section that can fail independently in an error boundary.
  54. → `references/pages-suspense.md`; with `cacheComponents: true`, also → `references/instant-navigation.md` for which links prefetch and which reads wait for the navigation.
  55. ✓ Route props become plain values; stable cards/sections wrap Suspense when they set layout; boundaries stay visible at the page.
  56. 7. **Add interaction** (if any): optimistic updates, pending state, toasts, confirmation.
  57. → `references/ux-patterns.md`.
  58. ✓ Feedback isn't doubled; optimistic reducers/actions live with the feature; URL/search params own shareable state; client effects synchronize external systems, not derived React state.
  59. 8. **Verify** against the checklist below before declaring done. When the change touches a loading sequence, lock it in with an end-to-end test.
  60. → `references/testing.md`.
  61. ✓ The test asserts which content is available before uncached work resolves, using visibility-aware locators.
  62. ## Verify before done
  63. Inspect the diff against every invariant — each is checkable by reading the changed files:
  64. - [ ] No page/layout imports a `*-queries` file or defines reusable domain UI inline; any inline helper is route-local control flow only.
  65. - [ ] Every page with params is synchronous and uses `params.then()` / `searchParams.then()` / `Promise.all([params, searchParams]).then(...)`.
  66. - [ ] Feature components receive plain IDs/handles/parsed filters or resolved records; no feature prop is named `params` or `searchParams`.
  67. - [ ] Every `<Suspense>` for page data sits in the page; no feature pre-wraps itself.
  68. - [ ] Stable wrappers/cards/chrome sit outside Suspense; fallback and final content do not duplicate the same outer card.
  69. - [ ] Every component has its real `*Skeleton` in the same file, at the end; no tiny skeleton aliases just to pass props.
  70. - [ ] Skeleton and content are the same height (measured), section headings sit outside the boundary, and sections that can be empty reserve their space.
  71. - [ ] Sections below a variable-height section are nested sibling boundaries inside it, not awaited by it and not passed through it as children.
  72. - [ ] `unstable_prefetch()` / `unstable_navigation()` are awaited in the component before its query call; no wrapper query exists just to hold the gate.
  73. - [ ] Every `*-queries.ts` starts with `import 'server-only'`; every `*-actions.ts` with `'use server'`.
  74. - [ ] With `cacheComponents: true`, reusable reads use `'use cache'` / `cacheTag` / `cacheLife`, or `'use cache: private'` / `'use cache: remote'` when appropriate; any dynamic read is intentional and justified.
  75. - [ ] A personalized shared-cache scope receives trusted, normalized identity values from an uncached feature wrapper; it never reads request APIs or trusts a client-provided identity inside the cache scope.
  76. - [ ] Reads whose every write calls `updateTag()` use `cacheLife('max')`; a shorter profile is reserved for data that changes outside the app's actions.
  77. - [ ] Mutations touching cached reads call `updateTag()` / `revalidateTag(..., 'max')` for the matching tags; `refresh()` is not a substitute for tag invalidation.
  78. - [ ] `prefetch={true}` is reserved for links users predictably follow, or for rows whose per-link prefetch was made cheap by gating the heavy part behind `unstable_navigation()`.
  79. - [ ] Action files are named `<folder>-actions.ts`; no entity-owned sub-concept spawned its own folder, and cross-domain product features do not take ownership of entity queries/actions.
  80. - [ ] Features with both server tags and client query keys define them once in a pure `<domain>-cache.ts`; queries, actions, hydration, query options, and hooks import from it.
  81. - [ ] Feature-local client-support files sit in the smallest fitting place: query options at the feature root, `use-*` hook wrappers in `hooks/`, leaf components in `components/`, and shared support only after real cross-feature reuse.
  82. - [ ] `'use client'` components are leaves — they import actions/hooks/providers, not async server components. A client component that needs server data has a server half in the feature (`ComposePanel` → `ComposePanelClient`); no page or layout creates query promises for it.
  83. - [ ] Client leaves use `useOptimistic`, transitions, reducers, URL state, or form actions for interaction; they do not call `setState` in effects for derived React state.
  84. - [ ] Forms whose action can reject input keep what the user typed: the action state returns the submitted values and the fields read them as `defaultValue`.
  85. - [ ] Mutations validate their input and invalidate the affected data.
  86. ## Reference index
  87. - **`references/feature-folders.md`** — where code goes: folder layout, cache contracts, naming, and merging sub-concepts.
  88. - **`references/queries-actions.md`** — query/action rules: server-only, dedup, validation, invalidation, return shape.
  89. - **`references/components.md`** — server/client boundary, skeletons, `use()`, single-use helpers, live data.
  90. - **`references/pages-suspense.md`** — page composition, `params.then()`, Suspense placement, CLS, error boundaries.
  91. - **`references/instant-navigation.md`** — prefetching decisions: `prefetch={true}`, the three render stages and their gates, validating what a navigation shows, hidden routes.
  92. - **`references/cache-components.md`** — the `cacheComponents` decisions: which reads to cache, which directive to use, how to invalidate.
  93. - **`references/single-page-applications.md`** — client cache decisions: placement, server seeding, Cache Components coordination, hydration, and mutations.
  94. - **`references/ux-patterns.md`** — interaction decisions: optimistic vs pending vs inline error, toasts, action-prop, confirmations.
  95. - **`references/testing.md`** — end-to-end tests: asserting the loading sequence with `instant()`, locating content across hidden routes, testing mutations.
  96. - **`references/example.md`** — the next-beats reference app: invariant → file map, for seeing any rule in real code.
README.md · README · 57 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Next.js App Architecture Skill
  2. An agent skill for building or auditing Next.js 16+ App Router apps. It packages the patterns from [Component Architecture for React Server Components](https://aurorascharff.no/posts/component-architecture-for-react-server-components/) and the [next-beats](https://github.com/vercel-labs/next-beats) reference app into a form AI coding agents can load and apply.
  3. ## Install
  4. ```bash
  5. npx skills add aurorascharff/nextjs-app-architecture-skill
  6. ```
  7. ## Rules
  8. - **Pages are synchronous compositors.** They don't fetch, they compose.
  9. - **Async components fetch their own data.** Co-locate the read with the JSX.
  10. - **Route props stop at the page.** Components receive IDs, slugs, parsed filters, or records — not raw `params` / `searchParams`.
  11. - **Skeletons live next to their component.** Same file, exported alongside it.
  12. - **Suspense boundaries go at the page level.** The page designs the loading sequence.
  13. - **Client boundaries are leaf nodes.** Push `'use client'` as deep as it can go.
  14. ## Documentation
  15. The skill preserves the opinionated architecture rules and project-tested edge cases. Framework mechanics come from the project's version-matched Next.js docs, following the [AI Coding Agents guide](https://preview.nextjs.org/docs/app/guides/ai-agents), rather than being redefined here. Canary-only APIs link to `preview.nextjs.org`.
  16. ## References
  17. The `SKILL.md` overview is always loaded; references split into two zones so the agent pulls only what the task needs.
  18. **Core** (any RSC app):
  19. - [`references/feature-folders.md`](references/feature-folders.md) — folder layout, naming, merging sub-concepts, action/query file naming.
  20. - [`references/queries-actions.md`](references/queries-actions.md) — server-only queries, selective same-request dedup, server actions, validation, and cache/tag invalidation.
  21. - [`references/components.md`](references/components.md) — async server components, skeletons without alias wrappers, client boundary, promise + `use()`, single-use helpers, polling.
  22. - [`references/pages-suspense.md`](references/pages-suspense.md) — page composition, `PageProps` / `LayoutProps`, `params.then()`, Suspense placement, CLS prevention, error boundaries.
  23. - [`references/testing.md`](references/testing.md) — end-to-end tests: the loading sequence with `instant()`, hidden routes, mutations.
  24. - [`references/example.md`](references/example.md) — next-beats invariant map and supporting patterns.
  25. **Instant Apps** (opt-in, load only when optimizing for instant-feeling apps):
  26. - [`references/instant-navigation.md`](references/instant-navigation.md) — `prefetch={true}`, the three render stages and their gates, validating navigations, hidden routes.
  27. - [`references/cache-components.md`](references/cache-components.md) — `cacheComponents: true`, the static shell, which reads to cache, `'use cache'` variants, `cacheTag` / `cacheLife`, `updateTag` / `revalidateTag`, and `io()` vs `connection()`.
  28. - [`references/single-page-applications.md`](references/single-page-applications.md) — SPA-style client caching and navigation patterns.
  29. - [`references/ux-patterns.md`](references/ux-patterns.md) — `useOptimistic`, toasts, pending state via `data-pending`, destructive flows, the action-prop pattern, URL pagination, `useFormStatus`.
  30. ## Background reading
  31. - [Component Architecture for React Server Components](https://aurorascharff.no/posts/component-architecture-for-react-server-components/)
  32. - [Server and Client Component Composition in Practice](https://aurorascharff.no/posts/server-client-component-composition-in-practice/)
  33. - [Building Design Components with Action Props using Async React](https://aurorascharff.no/posts/building-design-components-with-action-props-using-async-react/)
  34. - [Error Handling in Next.js with catchError](https://aurorascharff.no/posts/error-handling-in-nextjs-with-catch-error/)
  35. - [Avoiding Server Component Waterfall Fetching with React 19 cache()](https://aurorascharff.no/posts/avoiding-server-component-waterfall-fetching-with-react-19-cache/)
  36. - [next16-social-media](https://github.com/aurorascharff/next16-social-media) — demo app applying these patterns.
  37. **Companion skill:** [React View Transitions](https://github.com/vercel-labs/agent-skills/tree/main/skills/react-view-transitions).
  38. ## License
  39. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.