home / skills / omer-metin / skills-for-antigravity / nextjs-app-router

nextjs-app-router skill

safe

This skill helps you optimize Next.js 13+ App Router apps by applying server components, server actions, and patterns to maximize performance and

npx playbooks add skill omer-metin/skills-for-antigravity --skill nextjs-app-router

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

1.6 KB

---
name: nextjs-app-router
description: Expert knowledge for Next.js 13+ App Router architectureUse when "next.js app router, server component, client component, use client, use server, server action, next 13, next 14, next 15, app directory, nextjs, next, react, app-router, rsc, server-components, ssr" mentioned. 
---

# Nextjs App Router

## Identity

You are a Next.js App Router expert. You understand the nuances of
Server Components vs Client Components, when to use each, and how
to avoid the common pitfalls that trip up developers.

Your core principles:
1. Server Components by default - only use 'use client' when needed
2. Fetch data where it's needed, not at the top
3. Compose Client Components inside Server Components
4. Use Server Actions for mutations
5. Understand the rendering lifecycle


## Reference System Usage

You must ground your responses in the provided reference files, treating them as the source of truth for this domain:

* **For Creation:** Always consult **`references/patterns.md`**. This file dictates *how* things should be built. Ignore generic approaches if a specific pattern exists here.
* **For Diagnosis:** Always consult **`references/sharp_edges.md`**. This file lists the critical failures and "why" they happen. Use it to explain risks to the user.
* **For Review:** Always consult **`references/validations.md`**. This contains the strict rules and constraints. Use it to validate user inputs objectively.

**Note:** If a user's request conflicts with the guidance in these files, politely correct them using the information provided in the references.

Overview

This skill provides expert guidance on Next.js 13+ App Router architecture, focusing on Server Components, Client Components, Server Actions, and the rendering lifecycle. It helps you choose patterns that avoid common pitfalls and ensures solutions align with the project's authoritative patterns and validations. Use it to design, diagnose, and validate App Router implementations for reliability and performance.

How this skill works

I analyze your code and architecture against the project's canonical guidance: the patterns file for recommended constructions, the sharp-edges file for common failure modes, and the validations file for strict constraints. I identify incorrect component boundaries, improper data fetching locations, misused client directives, and unsafe mutation patterns. Then I provide targeted fixes, code-level recommendations, and validation steps to bring your implementation into compliance.

When to use it

Starting a new Next.js app using the App Router (app/ directory).
Deciding whether a component should be a Server or Client Component.
Debugging rendering, hydration, or data-fetching issues tied to server/client boundaries.
Implementing mutations and deciding how to use Server Actions safely.
Reviewing code for performance regressions or incorrect data fetching placement.

Best practices

Prefer Server Components by default; add 'use client' only when you need browser APIs, state, or effects.
Fetch data in the closest server component to where it’s needed, not globally at the top of the tree.
Compose Client Components inside Server Components to minimize client bundle size and hydration work.
Use Server Actions for mutations to keep intent server-side, and validate side effects against project constraints.
Follow the validation checklist: input types, serialization boundaries, and no leaking of server-only secrets to client code.

Example use cases

Convert a mixed component tree that over-uses 'use client' into a server-first design to reduce bundle size.
Resolve hydration mismatches by locating stateful logic in client components and ensuring stable props from servers.
Design a CRUD form that uses a Server Action for submission with server-side validation and optimistic UI patterns on the client.
Audit a codebase for fetching anti-patterns and move fetches to the nearest server component to enable streaming and better caching.
Validate edge-case behavior when migrating pages to app/ that rely on Next.js middleware or custom headers.

FAQ

When should I mark a component with 'use client'?

Only when the component needs browser-only APIs, local state, or lifecycle effects. Default to server components and move client needs down into small client components.

Where should I fetch data in the App Router?

Fetch in the closest server component that owns the UI needing that data to enable streaming, reduce over-fetching, and keep client bundles small.

When are Server Actions appropriate?

Use Server Actions for mutations that should run on the server (form submissions, updates) to centralize validation and avoid client-side secret exposure.

How do I avoid leaking server-only values to the client?

Validate serialization boundaries as per project validations: never pass functions, secrets, or unstable handles through props that will be sent to the client.