| 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):
- Read references/file-structure.md - Where every file goes
- Read references/auth-api-patterns.md - Auth, server/client fetchers, StaleTime
- Read references/templates.md - Query, mutation, and list page templates
- Read references/templates-detail-pages.md - Detail page, error, not-found, and skeleton templates
For skeleton (loading states):
- Read references/templates-detail-pages.md - Layout skeleton pattern
For review and audit-all (auditing):
- Read references/audit-patterns.md - Review checklists and audit workflows
For upgrade (updating skill):
- Read references/audit-patterns.md - Upgrade workflow and sources
Critical Rules (All Sub-Commands)
- Every page.tsx MUST have HydrationBoundary - Without it, streaming breaks and
loading.tsx won't animate. Read references/templates.md for the correct pattern.
- Client components return skeleton, never null - On hard refresh,
!data must show a skeleton, not null (which causes flash).
- 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.
- 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.
- getServerAuth first in every page.tsx - Call before any data prefetches. Read references/auth-api-patterns.md for the full pattern.
- Link directly to tab routes - Use
/products/${id}/overview, not /products/${id} (which causes a redirect).
- @header uses default.tsx, not page.tsx -
default.tsx renders for ALL child routes; page.tsx only matches the exact route.
- 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
- Identify page type using decision table above
- Scan existing queries in
lib/queries/ (if exists) - reuse before creating new
- Scan existing components from your UI package (if exists)
- 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
- Identify the detail page - which
[id] route
- Decide if tab needs a new query or can reuse the existing detail query
- 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
- Read the target
content.tsx to understand the DOM structure to mirror
- Scan existing skeletons in the feature for patterns to follow (if exists)
Skeleton Rules
- Mirror exact DOM structure - skeleton should have same layout as content
- Use pattern skeletons from your UI package - don't rebuild with raw
<Skeleton> elements
- Match grid layouts - if content has 3-column grid, skeleton should too
- 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:
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
