Skip to content

TheGoat395/Codex-Skills / skills/nextjs-app-router-routing

nextjs-app-router-routing

Verified

Implement App Router trees and navigation.

FileKindSize
SKILL.mdskill md701 B
agents/openai.yamlconfig296 B
references/nextjs-app-router-routing-guide.mdmarkdown4.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).
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall