nextjs-data

name	nextjs-data
description	Next.js App Router data layer: SSR hydration, React Query, auth patterns. Use when creating pages, adding tabs, or auditing data fetching.

Next.js Data Layer

Create and maintain Next.js App Router pages following the SSR + HydrationBoundary + React Query pattern with deterministic file structure.

Sub-Commands Overview

Command	Purpose	Modifies Code?
/nextjs-data create	Create new pages with queries (list, detail)	Yes (approval)
/nextjs-data add-tab	Add a new tab to existing detail page	Yes (approval)
/nextjs-data skeleton	Create/update loading.tsx skeletons	Yes (approval)
/nextjs-data review	Audit a specific feature for pattern issues	No
/nextjs-data audit-all	Scan entire app for compliance issues	No
/nextjs-data upgrade	Fetch latest docs and update skill patterns	Yes (approval)

All sub-commands ask before making changes.

---

Before Any Sub-Command

Load references based on the sub-command:

For create and add-tab (building pages):

1. Read references/file-structure.md - Where every file goes
2. Read references/auth-api-patterns.md - Auth, server/client fetchers, StaleTime
3. Read references/templates.md - Query, mutation, and list page templates
4. Read references/templates-detail-pages.md - Detail page, error, not-found, and skeleton templates

For skeleton (loading states):

1. Read references/templates-detail-pages.md - Layout skeleton pattern

For review and audit-all (auditing):

1. Read references/audit-patterns.md - Review checklists and audit workflows

For upgrade (updating skill):

1. Read references/audit-patterns.md - Upgrade workflow and sources

Critical Rules (All Sub-Commands)

1. Every page.tsx MUST have HydrationBoundary - Without it, streaming breaks and loading.tsx won't animate. Read references/templates.md for the correct pattern.
2. Client components return skeleton, never null - On hard refresh, !data must show a skeleton, not null (which causes flash).
3. Query pattern: keys.ts + server.ts + client.ts - Same keys, different fetchers. This enables SSR prefetch to client hydration. Read references/file-structure.md for the full query layer structure.
4. App router folders are for routing only - Only page.tsx, content.tsx, loading.tsx, layout.tsx, default.tsx, error.tsx, not-found.tsx belong in app/ folders. Read references/file-structure.md for all placement rules.
5. getServerAuth first in every page.tsx - Call before any data prefetches. Read references/auth-api-patterns.md for the full pattern.
6. Link directly to tab routes - Use /products/${id}/overview, not /products/${id} (which causes a redirect).
7. @header uses default.tsx, not page.tsx - default.tsx renders for ALL child routes; page.tsx only matches the exact route.
8. Defensive error handling - Always handle error, isLoading, and !data states before rendering content.

Read references/advanced-patterns.md for anti-patterns to avoid.

---

Page Type Decision Table

Need	Page Type	Structure
List of items	List Page	page.tsx + content.tsx + loading.tsx
Simple detail (no tabs)	Single-Page Detail	[id]/page.tsx + content.tsx + loading.tsx
Detail with tabs	Detail Page	@header/ slot + tab routes (parallel routes)

Always use parallel routes for detail pages with tabs. Benefits: correct loading skeleton during list-to-detail navigation, independent loading states, tab navigation doesn't reload the header.

---

/nextjs-data create

Create new pages with complete query layer and SSR hydration.

Before Starting

1. Identify page type using decision table above
2. Scan existing queries in lib/queries/ (if exists) - reuse before creating new
3. Scan existing components from your UI package (if exists)
4. Identify the target app if working in a monorepo

Creation Flow

1. Gather requirements (page type, data source, which app)
2. Check/Create query layer (keys.ts + server.ts + client.ts)
3. Present plan to user (all files to create with locations)
4. After approval: create query, page.tsx, content.tsx, loading.tsx
   For detail pages: layout.tsx, default.tsx, @header/, tabs

Read references/templates.md for complete code templates. Read references/file-structure.md for where every file goes.

---

/nextjs-data add-tab

Add a new tab to an existing detail page.

Before Starting

1. Identify the detail page - which [id] route
2. Decide if tab needs a new query or can reuse the existing detail query
3. Scan existing tabs in the detail page for naming convention and structure (if exists)

Add Tab Flow

1. Locate existing detail page (layout.tsx, tabs array)
2. Determine data needs (reuse parent query or new sub-resource?)
3. Present plan (new tab folder, query additions, tab array update)
4. After approval: create {tab}/page.tsx, content.tsx, loading.tsx
   Add query if needed, update tabs array in @header/content.tsx

Tab pages in parallel routes MUST have their own HydrationBoundary.

Read references/templates-detail-pages.md for tab page templates.

---

/nextjs-data skeleton

Create or update loading.tsx skeletons to match page structure.

When: After creating or modifying a page's content.tsx, or when loading states are missing or don't match the content layout.

Before Starting

1. Read the target content.tsx to understand the DOM structure to mirror
2. Scan existing skeletons in the feature for patterns to follow (if exists)

Skeleton Rules

1. Mirror exact DOM structure - skeleton should have same layout as content
2. Use pattern skeletons from your UI package - don't rebuild with raw <Skeleton> elements
3. Match grid layouts - if content has 3-column grid, skeleton should too
4. Shared layout skeletons go in lib/domain/{feature}/layout-skeleton.tsx

Read references/templates-detail-pages.md for the layout skeleton pattern.

---

/nextjs-data review

Audit pages and queries for SSR hydration and pattern issues. Reports problems without modifying code.

When: Reviewing a specific feature's pages before or after changes, during code review, or when investigating SSR issues.

Read references/audit-patterns.md for the full review checklist and output format.

---

/nextjs-data audit-all

Scan an entire app for page pattern compliance. Generates a comprehensive report.

Use when: periodic health checks, before releases, after upgrading Next.js/React Query, onboarding.

Read references/audit-patterns.md for severity levels, audit flow, and discovery commands.

---

/nextjs-data upgrade

Fetch latest documentation and update skill patterns to stay current with framework evolution.

Read references/audit-patterns.md for the upgrade workflow and sources to check.

---

Related Skills

• /react-ui - React component creation, extraction, patterns, review. Use for UI concerns (shadcn, forms, themes).
• /js-monorepo - Monorepo infrastructure (pnpm, Turborepo, shared packages). Use when setting up the repo structure.
• Cross-skill initialization order: /js-monorepo init first, then shadcn setup, then /react-ui create, then /nextjs-data create. Read the js-monorepo skill's shadcn-setup.md for the full sequence.

---

Checklist

Before completing any sub-command:

• Every page.tsx uses getQueryClient() + getServerAuth + prefetchQuery + HydrationBoundary
• Every content.tsx has 'use client' + useQuery from client fetcher
• Client components return skeleton (not null) when loading
• Query layer has keys.ts + server.ts + client.ts in lib/queries/{domain}/
• Mutations in mutations.ts use client API with invalidateQueries on success
• loading.tsx exists and mirrors content structure
• error.tsx exists for error boundaries; detail pages have not-found.tsx
• Detail pages call notFound() when entity doesn't exist
• Links point to tab routes, not parent routes
• No custom components in app router folders
• Types from shared contracts package, UI from shared UI package
• Auth/API clients follow dual fetcher pattern

---

Reference Files

• references/file-structure.md - Deterministic file placement rules
• references/auth-api-patterns.md - Auth, server/client fetchers, StaleTime, defense-in-depth
• references/templates.md - Query, mutation, and list page templates
• references/templates-detail-pages.md - Detail page, error, not-found, and skeleton templates
• references/advanced-patterns.md - Navigation transitions, streaming prefetch, anti-patterns
• references/audit-patterns.md - Review checklists and audit workflows