{"id":"3d196c54-3fc7-445d-b4c8-a01d4e983298","shortId":"B8rMqt","kind":"skill","title":"next-best-practices","tagline":"Next.js 15+ best practices: file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling. Use when working on a Next.js project, debugging RSC hydration errors, setting up App Router, optimizing performan","description":"# Next.js Best Practices\n\nApply these rules when writing or reviewing Next.js code.\n\n## File Conventions\n\nSee [file-conventions.md](./file-conventions.md) for:\n- Project structure and special files\n- Route segments (dynamic, catch-all, groups)\n- Parallel and intercepting routes\n- Middleware rename in v16 (middleware → proxy)\n\n## RSC Boundaries\n\nDetect invalid React Server Component patterns.\n\nSee [rsc-boundaries.md](./rsc-boundaries.md) for:\n- Async client component detection (invalid)\n- Non-serializable props detection\n- Server Action exceptions\n\n## Async Patterns\n\nNext.js 15+ async API changes.\n\nSee [async-patterns.md](./async-patterns.md) for:\n- Async `params` and `searchParams`\n- Async `cookies()` and `headers()`\n- Migration codemod\n\n## Runtime Selection\n\nSee [runtime-selection.md](./runtime-selection.md) for:\n- Default to Node.js runtime\n- When Edge runtime is appropriate\n\n## Directives\n\nSee [directives.md](./directives.md) for:\n- `'use client'`, `'use server'` (React)\n- `'use cache'` (Next.js)\n\n## Functions\n\nSee [functions.md](./functions.md) for:\n- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`\n- Server functions: `cookies`, `headers`, `draftMode`, `after`\n- Generate functions: `generateStaticParams`, `generateMetadata`\n\n## Error Handling\n\nSee [error-handling.md](./error-handling.md) for:\n- `error.tsx`, `global-error.tsx`, `not-found.tsx`\n- `redirect`, `permanentRedirect`, `notFound`\n- `forbidden`, `unauthorized` (auth errors)\n- `unstable_rethrow` for catch blocks\n\n## Data Patterns\n\nSee [data-patterns.md](./data-patterns.md) for:\n- Server Components vs Server Actions vs Route Handlers\n- Avoiding data waterfalls (`Promise.all`, Suspense, preload)\n- Client component data fetching\n\n## Route Handlers\n\nSee [route-handlers.md](./route-handlers.md) for:\n- `route.ts` basics\n- GET handler conflicts with `page.tsx`\n- Environment behavior (no React DOM)\n- When to use vs Server Actions\n\n## Metadata & OG Images\n\nSee [metadata.md](./metadata.md) for:\n- Static and dynamic metadata\n- `generateMetadata` function\n- OG image generation with `next/og`\n- File-based metadata conventions\n\n## Image Optimization\n\nSee [image.md](./image.md) for:\n- Always use `next/image` over `<img>`\n- Remote images configuration\n- Responsive `sizes` attribute\n- Blur placeholders\n- Priority loading for LCP\n\n## Font Optimization\n\nSee [font.md](./font.md) for:\n- `next/font` setup\n- Google Fonts, local fonts\n- Tailwind CSS integration\n- Preloading subsets\n\n## Bundling\n\nSee [bundling.md](./bundling.md) for:\n- Server-incompatible packages\n- CSS imports (not link tags)\n- Polyfills (already included)\n- ESM/CommonJS issues\n- Bundle analysis\n\n## Scripts\n\nSee [scripts.md](./scripts.md) for:\n- `next/script` vs native script tags\n- Inline scripts need `id`\n- Loading strategies\n- Google Analytics with `@next/third-parties`\n\n## Hydration Errors\n\nSee [hydration-error.md](./hydration-error.md) for:\n- Common causes (browser APIs, dates, invalid HTML)\n- Debugging with error overlay\n- Fixes for each cause\n\n## Suspense Boundaries\n\nSee [suspense-boundaries.md](./suspense-boundaries.md) for:\n- CSR bailout with `useSearchParams` and `usePathname`\n- Which hooks require Suspense boundaries\n\n## Parallel & Intercepting Routes\n\nSee [parallel-routes.md](./parallel-routes.md) for:\n- Modal patterns with `@slot` and `(.)` interceptors\n- `default.tsx` for fallbacks\n- Closing modals correctly with `router.back()`\n\n## Self-Hosting\n\nSee [self-hosting.md](./self-hosting.md) for:\n- `output: 'standalone'` for Docker\n- Cache handlers for multi-instance ISR\n- What works vs needs extra setup\n\n## Debug Tricks\n\nSee [debug-tricks.md](./debug-tricks.md) for:\n- MCP endpoint for AI-assisted debugging\n- Rebuild specific routes with `--debug-build-paths`","tags":["next","best","practices","synapse","deve1993","agent-skills","ai-agents","ai-coding","ai-workspace","anti-poisoning","auto-learning-ai","automation"],"capabilities":["skill","source-deve1993","skill-next-best-practices","topic-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workspace","topic-anti-poisoning","topic-auto-learning-ai","topic-automation","topic-claude-code","topic-code-quality","topic-cursor","topic-developer-tools","topic-devops"],"categories":["Synapse"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/deve1993/Synapse/next-best-practices","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add deve1993/Synapse","source_repo":"https://github.com/deve1993/Synapse","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (3,768 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:13.915Z","embedding":null,"createdAt":"2026-05-18T13:21:46.983Z","updatedAt":"2026-05-18T19:14:13.915Z","lastSeenAt":"2026-05-18T19:14:13.915Z","tsv":"'/async-patterns.md':116 '/bundling.md':311 '/data-patterns.md':202 '/debug-tricks.md':436 '/directives.md':146 '/error-handling.md':181 '/file-conventions.md':58 '/font.md':295 '/functions.md':159 '/hydration-error.md':353 '/image.md':273 '/metadata.md':251 '/parallel-routes.md':392 '/route-handlers.md':226 '/rsc-boundaries.md':92 '/runtime-selection.md':132 '/scripts.md':332 '/self-hosting.md':413 '/suspense-boundaries.md':374 '15':6,110 'action':105,208,245 'ai':442 'ai-assist':441 'alreadi':323 'alway':275 'analysi':328 'analyt':346 'api':16,112,358 'app':38 'appli':45 'appropri':142 'assist':443 'async':15,94,107,111,118,122 'async-patterns.md':115 'attribut':284 'auth':191 'avoid':212 'bailout':377 'base':266 'basic':229 'behavior':236 'best':3,7,43 'block':197 'blur':285 'boundari':12,83,371,386 'browser':357 'build':451 'bundl':24,308,327 'bundling.md':310 'cach':154,419 'catch':69,196 'catch-al':68 'caus':356,369 'chang':113 'client':95,149,218 'close':403 'code':53 'codemod':127 'common':355 'compon':88,96,205,219 'configur':281 'conflict':232 'convent':10,55,268 'cooki':123,169 'correct':405 'csr':376 'css':304,317 'data':13,198,213,220 'data-patterns.md':201 'date':359 'debug':32,362,432,444,450 'debug-build-path':449 'debug-tricks.md':435 'default':134 'default.tsx':400 'detect':84,97,103 'direct':143 'directives.md':145 'docker':418 'dom':239 'draftmod':171 'dynam':67,255 'edg':139 'endpoint':439 'environ':235 'error':18,35,177,192,350,364 'error-handling.md':180 'error.tsx':183 'esm/commonjs':325 'except':106 'extra':430 'fallback':402 'fetch':221 'file':9,54,64,265 'file-bas':264 'file-conventions.md':57 'fix':366 'font':291,300,302 'font.md':294 'forbidden':189 'function':156,168,174,258 'functions.md':158 'generat':173,261 'generatemetadata':176,257 'generatestaticparam':175 'get':230 'global-error.tsx':184 'googl':299,345 'group':71 'handl':19,178 'handler':21,211,223,231,420 'header':125,170 'hook':162,383 'host':410 'html':361 'hydrat':34,349 'hydration-error.md':352 'id':342 'imag':248,260,269,280 'image.md':272 'image/font':22 'import':318 'includ':324 'incompat':315 'inlin':339 'instanc':424 'integr':305 'intercept':74,388 'interceptor':399 'invalid':85,98,360 'isr':425 'issu':326 'lcp':290 'link':320 'load':288,343 'local':301 'mcp':438 'metadata':17,246,256,267 'metadata.md':250 'middlewar':76,80 'migrat':126 'modal':394,404 'multi':423 'multi-inst':422 'nativ':336 'navig':161 'need':341,429 'next':2 'next-best-practic':1 'next.js':5,30,42,52,109,155 'next/font':297 'next/image':277 'next/og':263 'next/script':334 'next/third-parties':348 'node.js':136 'non':100 'non-serializ':99 'not-found.tsx':185 'notfound':188 'og':247,259 'optim':23,40,270,292 'output':415 'overlay':365 'packag':316 'page.tsx':234 'parallel':72,387 'parallel-routes.md':391 'param':119 'path':452 'pattern':14,89,108,199,395 'performan':41 'permanentredirect':187 'placehold':286 'polyfil':322 'practic':4,8,44 'preload':217,306 'prioriti':287 'project':31,60 'promise.all':215 'prop':102 'proxi':81 'react':86,152,238 'rebuild':445 'redirect':186 'remot':279 'renam':77 'requir':384 'respons':282 'rethrow':194 'review':51 'rout':20,65,75,210,222,389,447 'route-handlers.md':225 'route.ts':228 'router':39 'router.back':407 'rsc':11,33,82 'rsc-boundaries.md':91 'rule':47 'runtim':128,137,140 'runtime-selection.md':131 'script':329,337,340 'scripts.md':331 'searchparam':121 'see':56,90,114,130,144,157,179,200,224,249,271,293,309,330,351,372,390,411,434 'segment':66 'select':129 'self':409 'self-host':408 'self-hosting.md':412 'serializ':101 'server':87,104,151,167,204,207,244,314 'server-incompat':313 'set':36 'setup':298,431 'size':283 'skill' 'skill-next-best-practices' 'slot':397 'source-deve1993' 'special':63 'specif':446 'standalon':416 'static':253 'strategi':344 'structur':61 'subset':307 'suspens':216,370,385 'suspense-boundaries.md':373 'tag':321,338 'tailwind':303 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workspace' 'topic-anti-poisoning' 'topic-auto-learning-ai' 'topic-automation' 'topic-claude-code' 'topic-code-quality' 'topic-cursor' 'topic-developer-tools' 'topic-devops' 'trick':433 'unauthor':190 'unstabl':193 'use':25,148,150,153,242,276 'useparam':166 'usepathnam':164,381 'userout':163 'usesearchparam':165,379 'v16':79 'vs':206,209,243,335,428 'waterfal':214 'work':27,427 'write':49","prices":[{"id":"99917427-1344-4f0f-a750-ec99662a28ab","listingId":"3d196c54-3fc7-445d-b4c8-a01d4e983298","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"deve1993","category":"Synapse","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:46.983Z"}],"sources":[{"listingId":"3d196c54-3fc7-445d-b4c8-a01d4e983298","source":"github","sourceId":"deve1993/Synapse/next-best-practices","sourceUrl":"https://github.com/deve1993/Synapse/tree/main/skills/next-best-practices","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:46.983Z","lastSeenAt":"2026-05-18T19:14:13.915Z"}],"details":{"listingId":"3d196c54-3fc7-445d-b4c8-a01d4e983298","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"deve1993","slug":"next-best-practices","github":{"repo":"deve1993/Synapse","stars":7,"topics":["agent-skills","ai-agents","ai-coding","ai-workspace","anti-poisoning","auto-learning-ai","automation","claude-code","code-quality","cursor","developer-tools","devops","fullstack-development","multi-agent-systems","nextjs","opencode","persistent-memory","self-improving","telegram-bot"],"license":"other","html_url":"https://github.com/deve1993/Synapse","pushed_at":"2026-05-15T21:34:01Z","description":"Self-improving AI brain for Claude Code & Desktop — 28 MCP tools, 253 skills, collective memory, project tracking, work logs. One server, all your sessions share the same knowledge. Deploy on Coolify in 2 minutes.","skill_md_sha":"8869a680ba450da6173a3b085a11437e85aa25ae","skill_md_path":"skills/next-best-practices/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/deve1993/Synapse/tree/main/skills/next-best-practices"},"layout":"multi","source":"github","category":"Synapse","frontmatter":{"name":"next-best-practices","description":"Next.js 15+ best practices: file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling. Use when working on a Next.js project, debugging RSC hydration errors, setting up App Router, optimizing performance, or configuring metadata and OG images."},"skills_sh_url":"https://skills.sh/deve1993/Synapse/next-best-practices"},"updatedAt":"2026-05-18T19:14:13.915Z"}}