TheGoat395/Codex-Skills / skills/nextjs-app-router-routing
nextjs-app-router-routing
VerifiedImplement App Router trees and navigation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 701 B |
| agents/openai.yaml | config | 296 B |
| references/nextjs-app-router-routing-guide.md | markdown | 4.2 KB |
references/nextjs-app-router-routing-guide.md
View on GitHub# Next.js App Router Routing Guide
## Purpose
Keep routing clear, idiomatic, and visually useful instead of turning every page into one giant component.
## Use When
- A Next.js project uses or should use the `app/` directory.
- The user asks for a new page, homepage, route, route group, landing page, portfolio route, product route, blog route, or nested layout.
- Navigation state, loading boundaries, route-level errors, or shared UI need to be shaped deliberately.
## Do Not Use When
- The project is plain React, Vite, Astro, static HTML, or another framework without Next.js.
- The app uses the legacy `pages/` router and the user did not ask to migrate.
- The change is only visual styling inside an existing component with no route implications.
## Discovery Questions
- Is the project using `app/`, `pages/`, or both?
- What route should be the homepage or primary entry?
- Which UI should persist across navigation: header, product shell, sidebar, filters, audio/video, or cart?
- Does the route need dynamic params, route groups, loading, error, or not-found states?
## Decision Tree
- If `app/` exists, map route folders before editing.
- If shared UI should persist, place it in the closest stable layout.
- If a segment needs route-level feedback, add scoped `loading`, `error`, or `not-found` files.
- If route organization is for code clarity only, use route groups rather than URL-changing folders.
- If a component only navigates, prefer `Link`; use router hooks only inside Client Components for imperative behavior.
## Implementation Rules
- Keep route files small enough to reveal page intent at a glance.
- Use `page` files for route UI and `layout` files for shared chrome.
- Use route-specific loading and error states that match the visual system, not default text.
- Do not mark layouts as client components just to make one small nav/search/menu interactive.
- Make navigation labels concrete and brand/site-specific.
## Useful Patterns
- `app/(marketing)/page.tsx` for a polished marketing homepage without exposing `(marketing)` in the URL.
- `app/work/[slug]/page.tsx` for case studies or portfolio detail pages.
- `app/dashboard/layout.tsx` for persistent operational chrome and nested dashboard pages.
- Route-level `not-found.tsx` for editorial or commerce detail pages with a designed recovery path.
## Anti-Patterns
- One monster homepage file that contains all routing, layout, data, content, and animation.
- Using Client Components for the whole app because one menu opens.
- Adding folders that accidentally change public URLs.
- Leaving route loading/error/not-found states as raw framework defaults on a premium site.
## QA Checklist
- Check direct URL loads and client-side navigation.
- Confirm shared layouts preserve intended UI state.
- Inspect loading, error, and not-found screens where changed.
- Verify mobile nav and skip/focus behavior across routes.
## Acceptance Criteria
- The route tree matches the product or content model.
- Navigation feels intentional and does not require excess client JavaScript.
- Every touched route has a polished success, loading, and failure path when relevant.
## Shared scope
For applicable substantial web work, reuse the [shared scoped web contract](../../website-operating-rules/references/scoped-web-contract.md) when available. Preserve current authorization, stack and requested scope; this optional reference does not require another planning or approval cycle.
## Official Source Anchors
- Next.js docs overview: https://nextjs.org/docs
- App Router layouts and pages: https://nextjs.org/docs/app/getting-started/layouts-and-pages
- Server and Client Components: https://nextjs.org/docs/app/getting-started/server-and-client-components
## Version-aware route inputs
Check the installed Next.js version before typing route props. Current App Router page conventions provide `params` and `searchParams` as promises: unwrap with `await` in an async Server Component or React `use` in a Client Component. Do not copy older synchronous examples into a current project or migrate a legacy router merely to match this guide. Verify direct loads and query-driven navigation after changing these inputs. [Page conventions](https://nextjs.org/docs/app/api-reference/file-conventions/page).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |