next-best-practices
Skill3.1k starsChanged 9 months agoMITView on GitHub
Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
51 other projects use a version of this, 17 of them edited; 1 new project in the last 4 weeks, against 2 the 4 before.
How people change it
All 17 edited versions we compared keep every one of its 4 rules.
Of the 17 edited versions we compared: 17 keep every rule.
We split this file and each edited version into the rules they give an agent and match them by wording. A version that adds no rule of its own and has not changed since this file last did reads as an older text, so what it lacks is not counted as dropped. We keep no past texts of a file, so that is inferred, and an edited version that started from an older text still counts its gaps as drops.
Adopted by
Cooling: 1 new project took it in the last 4 weeks, 0.5× the 4 weeks before.thin data
Most recently taken up by
- imMamdouhaboammar/openreviewword for word, first seen Nov 15, 2026
- laguagu/claude-code-nextjs-skillstheir own version, first seen Nov 14, 2026
- compozy/compozyword for word, first seen Nov 13, 2026
- figueroaignacio/ignaciofigueroa.devedited, first seen Nov 8, 2026
- ftzi/livespecword for word, first seen Nov 8, 2026
- ever-co/ever-worksedited, first seen Nov 8, 2026
Who's talking about TheEdoRan/next-safe-action
- vercel/next.js“"Server Actions must be async functions." being reported incorrectly”GitHub · Nov 5, 2024 · 13 reactions
- next-safe-action/next-safe-action“[BUG] `onError` called on redirects if it was called previously”GitHub · Dec 1, 2024 · 7 reactions
- next-safe-action/next-safe-action“[BUG] TypeScript issue with parsedInput in useAction Hook”GitHub · Jun 16, 2024 · 3 reactions
- next-safe-action/next-safe-action“[BUG] Not possible to handle errors that are not instance of Error”GitHub · Jan 10, 2025 · 2 reactions
- airjp73/rvf“Fix zod-form-data schema output type that are using `stripEmpty`”GitHub · Jun 10, 2025 · 1 reactions
The biggest 5 of 50 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 50
Talked about on GitHub (50 times).
On GitHub · 50
- Nov 5, 2024"Server Actions must be async functions." being reported incorrectly — vercel/next.js13 reactions · 5 comments
- Dec 1, 2024[BUG] `onError` called on redirects if it was called previously — next-safe-action/next-safe-action7 reactions · 4 comments
- Jun 16, 2024[BUG] TypeScript issue with parsedInput in useAction Hook — next-safe-action/next-safe-action3 reactions · 8 comments
- Jan 10, 2025[BUG] Not possible to handle errors that are not instance of Error — next-safe-action/next-safe-action2 reactions · 3 comments
- Jun 10, 2025Fix zod-form-data schema output type that are using `stripEmpty` — airjp73/rvf1 reaction · 4 comments
45 more on GitHub
- May 20, 2025Zod v4 support — next-safe-action/next-safe-action1 reaction · 1 comment
- Feb 19, 2025Fix `zfd.formData` input type — airjp73/rvf1 reaction · 3 comments
- Mar 8, 2024[ASK] Error: Cannot access 'action' before initialization — next-safe-action/next-safe-action1 reaction · 3 comments
- Oct 11, 2023Dist files contain incorrect types — next-safe-action/next-safe-action1 reaction · 2 comments
- Mar 25, 2026Bump next-safe-action from 7.10.8 to 8.1.8 — ChazWyllie/kairofit0 reactions · 1 comment
- Mar 15, 2026chore(deps): bump the npm-dependencies group across 1 directory with 14 updates — startberlin/cockpit0 reactions · 2 comments
- Mar 4, 2026[BUG] `returnValidationErrors` called from middleware catch block throws instead of returning `validationErrors` — next-safe-action/next-safe-action0 reactions
- Mar 1, 2026build(deps): bump next-safe-action from 8.0.11 to 8.1.4 — wuyuan1992/react-components0 reactions · 2 comments
- Mar 1, 2026chore(deps): bump the npm-dependencies group across 1 directory with 12 updates — startberlin/cockpit0 reactions · 2 comments
- Feb 28, 2026Bump next-safe-action from 8.0.11 to 8.1.4 — rifandani/feature-flag0 reactions
- Feb 27, 2026Bump next-safe-action from 8.0.11 to 8.1.4 — joehentges/pendulem0 reactions
- Feb 11, 2026[Module Listing Request]: `nuxt-safe-action` — nuxt/modules0 reactions · 2 comments
- Dec 16, 2025Bump next-safe-action from 7.10.8 to 8.0.11 — hiteshhJ/ticketing-app0 reactions
- Oct 29, 2025Bump next-safe-action from 7.10.2 to 8.0.11 — akunpbhanz-lgtm/starter0 reactions · 1 comment
- Sep 30, 2025Bump next-safe-action from 7.10.8 to 8.0.11 — eersnington/diff00 reactions · 2 comments
- Sep 8, 2025Bump next-safe-action from 8.0.10 to 8.0.11 — joehentges/skyline0 reactions
- Sep 1, 2025[npm dependencies]: Bump next-safe-action from 7.10.8 to 8.0.11 in /src — Smegfi/papago0 reactions
- Sep 1, 2025chore(deps): bump next-safe-action from 8.0.8 to 8.0.11 — Shironex/portfolio0 reactions · 1 comment
- Sep 1, 2025chore: bump the dependencies group with 20 updates — alex289/NextJs-Boilerplate0 reactions · 2 comments
- Aug 25, 2025chore(deps): bump the all group across 1 directory with 94 updates — jaqubowsky/create-nextjs-app0 reactions · 1 comment
- Aug 23, 2025chore: bump the dependencies group with 19 updates — alex289/NextJs-Boilerplate0 reactions · 3 comments
- Aug 18, 2025[npm dependencies]: Bump next-safe-action from 7.10.8 to 8.0.10 in /src — Smegfi/papago0 reactions · 1 comment
- Aug 18, 2025chore(deps): bump the all group with 71 updates — jaqubowsky/create-nextjs-app0 reactions · 2 comments
- Aug 18, 2025chore(deps): bump next-safe-action from 8.0.8 to 8.0.10 — Shironex/portfolio0 reactions · 1 comment
- Aug 1, 2025chore(deps): bump next-safe-action from 8.0.2 to 8.0.8 — rifandani/ai-monorepo0 reactions · 1 comment
- Aug 1, 2025⬆️ Bump next-safe-action from 7.10.4 to 8.0.8 — quantified-uncertainty/squiggle0 reactions · 4 comments
- Jul 28, 2025[npm dependencies]: Bump next-safe-action from 7.10.8 to 8.0.8 in /src — Smegfi/papago0 reactions · 1 comment
- Jul 15, 2025chore(deps): bump next-safe-action from 7.10.4 to 8.0.8 — santosmarco/github-jtgc5e-20 reactions
- Jul 15, 2025Bump the dependencies group with 6 updates — RasengunShotaro/pdcxa0 reactions · 1 comment
- Jun 30, 2025[npm dependencies]: Bump next-safe-action from 7.10.8 to 8.0.7 in /src — Smegfi/papago0 reactions · 1 comment
- Jun 26, 2025Bump the dependencies group with 5 updates — RasengunShotaro/pdcxa0 reactions
- Jun 23, 2025[npm dependencies]: Bump next-safe-action from 7.10.8 to 8.0.4 in /src — Smegfi/papago0 reactions · 1 comment
- Jun 17, 2025chore(deps): bump next-safe-action from 7.10.4 to 8.0.3 — santosmarco/github-jtgc5e-20 reactions · 1 comment
- Jun 16, 2025Bump next-safe-action from 7.10.8 to 8.0.3 — joehentges/skyline0 reactions · 1 comment
- Jun 12, 2025[BUG] throwValidationErrors with overrideErrorMessage not working in v7.10.5 — next-safe-action/next-safe-action0 reactions · 1 comment
- Jun 9, 2025Bump next-safe-action from 7.10.8 to 8.0.2 — joehentges/skyline0 reactions · 1 comment
- Jun 9, 2025chore(deps): bump next-safe-action from 7.10.4 to 8.0.2 — santosmarco/github-jtgc5e-20 reactions · 1 comment
- Jun 9, 2025[npm dependencies]: Bump next-safe-action from 7.10.8 to 8.0.2 in /src — Smegfi/papago0 reactions · 1 comment
- Jun 4, 2025chore(deps): bump next-safe-action from 7.10.4 to 8.0.1 — santosmarco/github-jtgc5e-20 reactions · 1 comment
- Jun 3, 2025chore(deps): bump next-safe-action from 7.10.4 to 8.0.0 — santosmarco/github-jtgc5e-20 reactions · 1 comment
- Jun 3, 2025Bump the dependencies group with 5 updates — RasengunShotaro/pdcxa0 reactions · 1 comment
- Jun 2, 2025Bump next-safe-action from 7.10.8 to 8.0.0 — joehentges/skyline0 reactions · 1 comment
- May 13, 2025chore(deps): bump next-safe-action from 7.10.4 to 7.10.8 — santosmarco/github-jtgc5e-20 reactions · 1 comment
- May 1, 2025chore(deps): bump next-safe-action from 7.10.5 to 7.10.8 — rifandani/ai-monorepo0 reactions · 1 comment
- May 1, 2025⬆️ Bump next-safe-action from 7.10.4 to 7.10.8 — quantified-uncertainty/squiggle0 reactions · 3 comments
Used with
Projects with it also use app-renderer-systems, refactoring-analysis and 8 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
pedronauckSkillapp-renderer-systems
Create, extend, or debug frontend domain modules organized under systems/. Covers adapters, Query hooks, local state, and public exports; excludes generic components and backend implementation.
Also in 3 projects that use this
pedronauckSkillrefactoring-analysis
Audit code quality and architectural health or plan refactoring using Fowler code smells and techniques; write prioritized findings to docs/_refacs/. Excludes formatting, performance, and security audits.
Also in 3 projects that use this
jander99Skilltypescript-advanced
Design, implement, refactor, and debug advanced TypeScript patterns including generics, utility types, mapped types, conditional types, type guards, discriminated unions, and strict mode configuration. Use when writing type-safe code, fixing type errors, or improving type inference.
Also in 3 projects that use this
midudevSkilltailwind-css-patterns
Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.
Also in 5 projects that use this
barisariburnuSkilltanstack
Expert assistance for TanStack Router, Query (v5), and Table (v8). Use when users need help with file-based routing, type-safe navigation, data loading, search params, queries, mutations, optimistic updates, infinite queries, table state management, or debugging TanStack libraries.
Also in 3 projects that use this
crafter-stationSkilltech-logos
Install official tech brand logos from the Elements registry. Use when user needs logos for tech companies (Clerk, Vercel, GitHub, etc.), AI providers (OpenAI, Anthropic, Claude), social platforms, or any brand assets. Triggers on "logo", "brand", "icon for [company]", "add [company] logo", placeholder logo detection, or when building landing pages, auth UIs, or integrations showcases.
Also in 3 projects that use this
Other versions51 projects use a version of this.
Word for word · 28
- midudev/preguntas-entrevista-react★ 7.8k100% same
- compozy/compozy★ 2.9k100% same
- kokonut-labs/kokonutui★ 2.3k100% same
- vercel-labs/openreview★ 1.7k100% same
- subhadeeproy3902/mvpblocks★ 834100% same
- pedronauck/skills★ 655100% same
- robotostudio/turbo-start-sanity★ 186100% same
- happycapy-ai/Happycapy-skills★ 137100% same
- r2hu1/openbots★ 15100% same
- getsentry/webvitals.com★ 12100% same
18 more not listed
Edited · 17
- Kiranism/next-shadcn-dashboard-starter★ 7.2k100% same
- JimmyLv/BibiGPT-v1★ 6.3k100% same
- openstatusHQ/data-table-filters★ 2.3k100% same
- legions-developer/invoicely★ 923100% same
- notum-cz/strapi-next-monorepo-starter★ 316100% same
- ever-co/ever-works★ 199100% same
- ever-works/ever-works★ 199100% same
- yamcodes/arkenv★ 15196% same
- LeonardoTrapani/better-skills★ 11100% same
- PIXARTSeu/Synapse★ 993% same
7 more not listed
Wrote their own version · 6
- laguagu/claude-code-nextjs-skills★ 72same name
- trancethehuman/template-next-agent★ 6same name
- kimtth/agent-skill-100-lines-or-less★ 2same name
- revealui-studio/revskills★ 2same name
- RevealUIStudio/revskills★ 2same name
- jahongashtamc/hallwright★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/vercel-react-best-practices/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- frontend-designSkill
- next-cache-componentsSkill
- next-upgradeSkill
- pnpmSkill
- skill-creatorSkill
- tsdownSkill
- turborepoSkill
- vercel-react-best-practicesSkill
- vitestSkill
The file
We split this skill into the rules it gives an agent
4 rules. 2 are common, 0 are distinctive, and 2 are very specific to this project.
2
Common
Most of the 23 edited versions we read keep these.
0
Distinctive
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
- Very specific: line 40
Default to Node.js runtime
- Common: line 41
When Edge runtime is appropriate
- Common: line 77
When to use vs Server Actions
- Very specific: line 90
Always use next/image over <img>
“Common” is measured: kept by at least 6 in 10 of the 23 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Next.js Best Practices
Apply these rules when writing or reviewing Next.js code.
File Conventions
See file-conventions.md for:
- Project structure and special files
- Route segments (dynamic, catch-all, groups)
- Parallel and intercepting routes
- Middleware rename in v16 (middleware → proxy)
RSC Boundaries
Detect invalid React Server Component patterns.
See rsc-boundaries.md for:
- Async client component detection (invalid)
- Non-serializable props detection
- Server Action exceptions
Async Patterns
Next.js 15+ async API changes.
See async-patterns.md for:
- Async
paramsandsearchParams - Async
cookies()andheaders() - Migration codemod
Runtime Selection
See runtime-selection.md for:
- Default to Node.js runtime
- When Edge runtime is appropriate
Directives
See directives.md for:
'use client','use server'(React)'use cache'(Next.js)
Functions
See functions.md for:
- Navigation hooks:
useRouter,usePathname,useSearchParams,useParams - Server functions:
cookies,headers,draftMode,after - Generate functions:
generateStaticParams,generateMetadata
Error Handling
See error-handling.md for:
error.tsx,global-error.tsx,not-found.tsxredirect,permanentRedirect,notFoundforbidden,unauthorized(auth errors)unstable_rethrowfor catch blocks
Data Patterns
See data-patterns.md for:
- Server Components vs Server Actions vs Route Handlers
- Avoiding data waterfalls (
Promise.all, Suspense, preload) - Client component data fetching
Route Handlers
See route-handlers.md for:
route.tsbasics- GET handler conflicts with
page.tsx - Environment behavior (no React DOM)
- When to use vs Server Actions
Metadata & OG Images
See metadata.md for:
- Static and dynamic metadata
generateMetadatafunction- OG image generation with
next/og - File-based metadata conventions
Image Optimization
See image.md for:
- Always use
next/imageover<img> - Remote images configuration
- Responsive
sizesattribute - Blur placeholders
- Priority loading for LCP
Font Optimization
See font.md for:
next/fontsetup- Google Fonts, local fonts
- Tailwind CSS integration
- Preloading subsets
Bundling
See bundling.md for:
- Server-incompatible packages
- CSS imports (not link tags)
- Polyfills (already included)
- ESM/CommonJS issues
- Bundle analysis
Scripts
See scripts.md for:
next/scriptvs native script tags- Inline scripts need
id - Loading strategies
- Google Analytics with
@next/third-parties
Hydration Errors
See hydration-error.md for:
- Common causes (browser APIs, dates, invalid HTML)
- Debugging with error overlay
- Fixes for each cause
Suspense Boundaries
See suspense-boundaries.md for:
- CSR bailout with
useSearchParamsandusePathname - Which hooks require Suspense boundaries
Parallel & Intercepting Routes
See parallel-routes.md for:
- Modal patterns with
@slotand(.)interceptors default.tsxfor fallbacks- Closing modals correctly with
router.back()
Self-Hosting
See self-hosting.md for:
output: 'standalone'for Docker- Cache handlers for multi-instance ISR
- What works vs needs extra setup
Debug Tricks
See debug-tricks.md for:
- MCP endpoint for AI-assisted debugging
- Rebuild specific routes with
--debug-build-paths
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
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.

