agentleFS
pabloirracionalpabloirracional/claude-skills/skills/using-nextjs-best-practices/SKILL.md

using-nextjs-best-practices

Skill0 starsChanged 4 months agoMITView on GitHub

Writes and reviews Next.js App Router code using patterns verified against a real build - Server/Client Component boundaries, explicit fetch caching, and loading/error conventions. Use whenever the user is building, reviewing, or debugging a Next.js app, or asks about server components, routing, caching, or performance in a Next.js context.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use loading.tsx and error.tsx file conventions: instead of manual loading/error state - Next.js wires these in automatically at the …

    line 16
  2. Very specific:

    Don't recommend getServerSideProps/getStaticProps for App Router projects - those are Pages Router only and will confuse the setup.

    line 88

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Using Next.js best practices

Writes App Router code using patterns confirmed to actually build cleanly (Next.js 16.2, verified below) - not assumed-correct advice.

Workflow

  1. Confirm App Router vs Pages Router first (app/ vs pages/) - recommendations differ completely. Never mix patterns.
  2. Default to Server Components; push "use client" down as far as possible. Only the component that genuinely needs interactivity gets the directive - see the verified pattern below, where the data-fetching page stays a Server Component and only the interactive panel is client-side.
  3. Be explicit about fetch caching - pass { next: { revalidate: N } } (or cache: "no-store") rather than relying on unstated defaults, which have changed across Next.js versions.
  4. Mark routes force-dynamic when they depend on runtime data that can't be resolved at build time - without this, next build will try to prerender the route statically and fail if the fetch target isn't reachable at build time (confirmed below - this exact failure was reproduced and fixed).
  5. Use loading.tsx and error.tsx file conventions instead of manual loading/error state - Next.js wires these in automatically at the route segment level.

Verified pattern (real next build output)

Structure used, actually built with Next.js 16.2 + Turbopack:

app/
├── layout.tsx
├── page.tsx                  (static - "/")
└── dashboard/
    ├── page.tsx               (Server Component, force-dynamic)
    ├── stats-panel.tsx         (Client Component - "use client")
    ├── loading.tsx
    └── error.tsx               ("use client", receives error + reset)

app/dashboard/page.tsx - Server Component, fetches data, delegates interactivity:

export const dynamic = "force-dynamic";

async function getStats() {
  const res = await fetch("https://api.example.com/stats", { next: { revalidate: 60 } });
  if (!res.ok) throw new Error("Failed to load stats");
  return res.json();
}

export default async function DashboardPage() {
  const stats = await getStats();
  return (
    <main>
      <h1>Dashboard</h1>
      <StatsPanel initialStats={stats} />
    </main>
  );
}

app/dashboard/stats-panel.tsx - the only file that needs "use client":

"use client";
import { useState } from "react";

export default function StatsPanel({ initialStats }: { initialStats: unknown }) {
  const [expanded, setExpanded] = useState(false);
  return (
    <div>
      <button onClick={() => setExpanded(!expanded)}>
        {expanded ? "Collapse" : "Expand"}
      </button>
      {expanded && <pre>{JSON.stringify(initialStats, null, 2)}</pre>}
    </div>
  );
}

Confirmed build output:

Route (app)
┌ ○ /
├ ○ /_not-found
└ ƒ /dashboard

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

Note what actually happened during testing: the first build attempt failed without force-dynamic, because Next.js tried to statically prerender /dashboard at build time and the fetch target wasn't reachable in the build environment. Adding export const dynamic = "force-dynamic"; fixed it. This is a real, reproducible failure mode - flag it whenever a page fetches from a runtime-only data source without that line.

Notes

  • Caching and use cache directive behavior differs meaningfully across Next.js 13/14/15/16 - check package.json before giving version-specific advice instead of assuming the latest behavior applies.
  • Don't recommend getServerSideProps/getStaticProps for App Router projects - those are Pages Router only and will confuse the setup.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.