Skip to content

Commit ff4d9b3

Browse files
amondnetamondnet
authored
feat(next): add Next.js plugin to marketplace (#139)
* feat(next): add Next.js plugin to marketplace Add Next.js plugin with best practices, caching patterns, and upgrade guidance. Includes skills for RSC boundaries, data patterns, metadata, error handling, and more. - Add plugin.json manifest for next plugin - Register in marketplace.json and release-please-config.json - Add next entry to README plugin list * fix(next): add author field to plugin.json Add Vercel attribution as suggested by Gemini code review. * docs(gemini): add .agents/skills exclusion rule to styleguide Skills installed via skills.sh (bunx skills add) under .agents/skills/ paths are vendor-managed and should not be reviewed or modified.
1 parent ea45c33 commit ff4d9b3

29 files changed

Lines changed: 3940 additions & 1 deletion

‎.claude-plugin/marketplace.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,14 @@
503503
"keywords": ["vinext", "nextjs", "vite", "migration", "cloudflare"],
504504
"tags": ["framework", "migration"],
505505
"source": "./plugins/vinext"
506+
},
507+
{
508+
"name": "next",
509+
"description": "Next.js best practices, caching patterns, and upgrade guidance",
510+
"category": "framework",
511+
"keywords": ["next", "nextjs", "react", "ssr", "rsc"],
512+
"tags": ["framework", "react"],
513+
"source": "./plugins/next"
506514
}
507515
]
508516
}

‎.gemini/styleguide.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,35 @@ plugins/<plugin>/skills/<skill>/
2626
└── SYNC.md ← presence of this file marks it as vendor-synced
2727
```
2828

29+
## Skills.sh Installed Skills (Read-Only)
30+
31+
Skills installed via `bunx skills add` live under `plugins/*/.agents/skills/` and are managed by `skills-lock.json`. These files **must not be modified directly**.
32+
33+
### Rules
34+
35+
- **Do not modify** any file under `plugins/*/.agents/skills/` paths.
36+
- **Do not suggest edits** to these files in code reviews.
37+
- **Skip review comments** targeting files under `.agents/skills/` paths.
38+
- If a skills.sh-installed file needs a fix, update the upstream skill repository instead.
39+
40+
### Identifying Skills.sh-Installed Files
41+
42+
A plugin using skills.sh will have this structure:
43+
44+
```
45+
plugins/<plugin>/
46+
├── .agents/skills/ ← all files here are read-only
47+
│ └── <skill-name>/
48+
│ └── SKILL.md
49+
└── skills-lock.json ← presence of this file marks skills as externally managed
50+
```
51+
2952
### Review Checklist
3053

3154
When reviewing pull requests:
3255

3356
- [ ] Check if changed files are under `plugins/*/skills/*/` paths
3457
- [ ] If `SYNC.md` exists in the same directory, **reject the change** and redirect to the upstream vendor
35-
- [ ] Do not request improvements or style fixes on vendor-synced files
58+
- [ ] Check if changed files are under `plugins/*/.agents/skills/` paths
59+
- [ ] If `skills-lock.json` exists in the plugin root, **reject the change** and redirect to the upstream skill repository
60+
- [ ] Do not request improvements or style fixes on vendor-synced or skills.sh-installed files

‎CLAUDE.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -363,6 +363,9 @@ When integrating an existing MCP server or tool as a Claude Code plugin:
363363
- Use Skills instead for better token efficiency and intelligent activation
364364
- Only use hooks for non-MCP tool automation (validation, formatting, etc.)
365365

366+
**Plugin Naming:**
367+
- Use the canonical short name matching the npm package (e.g. `next` not `nextjs`, `vue` not `vuejs`)
368+
366369
**Directory Structure:**
367370
- `.claude-plugin/plugin.json` must be at this exact path
368371
- `hooks/`, `commands/`, `agents/`, `skills/` directories at plugin root
@@ -411,6 +414,10 @@ cat plugins/<plugin>/skills/<skill>/SYNC.md
411414
```
412415
Skip any code review suggestions targeting vendor-synced skill files.
413416

417+
### Skills.sh Installed Skills (Read-Only)
418+
419+
Skills installed via `bunx skills add` live under `plugins/*/.agents/skills/` and are tracked by `skills-lock.json`. These are also vendor-managed — do not modify directly. Fix upstream instead.
420+
414421
## Development Standards
415422

416423
Read these documents **only when relevant to the current task** — do not load them all upfront:

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -247,6 +247,11 @@ Migrates Next.js projects to vinext (Vite-based Next.js reimplementation) — co
247247

248248
**Install:** `/plugin install vinext@pleaseai` | **Source:** [plugins/vinext](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/vinext)
249249

250+
#### Next.js
251+
Next.js best practices, caching patterns, and upgrade guidance.
252+
253+
**Install:** `/plugin install next@pleaseai` | **Source:** [plugins/next](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/next)
254+
250255
## Quick Start
251256

252257
The fastest way to get started — install the marketplace and let the plugin recommender auto-detect what you need:

‎plugins/next/.agents/skills/next-best-practices/SKILL.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
name: next-best-practices
3+
description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
4+
user-invocable: false
5+
---
6+
7+
# Next.js Best Practices
8+
9+
Apply these rules when writing or reviewing Next.js code.
10+
11+
## File Conventions
12+
13+
See [file-conventions.md](./file-conventions.md) for:
14+
- Project structure and special files
15+
- Route segments (dynamic, catch-all, groups)
16+
- Parallel and intercepting routes
17+
- Middleware rename in v16 (middleware → proxy)
18+
19+
## RSC Boundaries
20+
21+
Detect invalid React Server Component patterns.
22+
23+
See [rsc-boundaries.md](./rsc-boundaries.md) for:
24+
- Async client component detection (invalid)
25+
- Non-serializable props detection
26+
- Server Action exceptions
27+
28+
## Async Patterns
29+
30+
Next.js 15+ async API changes.
31+
32+
See [async-patterns.md](./async-patterns.md) for:
33+
- Async `params` and `searchParams`
34+
- Async `cookies()` and `headers()`
35+
- Migration codemod
36+
37+
## Runtime Selection
38+
39+
See [runtime-selection.md](./runtime-selection.md) for:
40+
- Default to Node.js runtime
41+
- When Edge runtime is appropriate
42+
43+
## Directives
44+
45+
See [directives.md](./directives.md) for:
46+
- `'use client'`, `'use server'` (React)
47+
- `'use cache'` (Next.js)
48+
49+
## Functions
50+
51+
See [functions.md](./functions.md) for:
52+
- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
53+
- Server functions: `cookies`, `headers`, `draftMode`, `after`
54+
- Generate functions: `generateStaticParams`, `generateMetadata`
55+
56+
## Error Handling
57+
58+
See [error-handling.md](./error-handling.md) for:
59+
- `error.tsx`, `global-error.tsx`, `not-found.tsx`
60+
- `redirect`, `permanentRedirect`, `notFound`
61+
- `forbidden`, `unauthorized` (auth errors)
62+
- `unstable_rethrow` for catch blocks
63+
64+
## Data Patterns
65+
66+
See [data-patterns.md](./data-patterns.md) for:
67+
- Server Components vs Server Actions vs Route Handlers
68+
- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
69+
- Client component data fetching
70+
71+
## Route Handlers
72+
73+
See [route-handlers.md](./route-handlers.md) for:
74+
- `route.ts` basics
75+
- GET handler conflicts with `page.tsx`
76+
- Environment behavior (no React DOM)
77+
- When to use vs Server Actions
78+
79+
## Metadata & OG Images
80+
81+
See [metadata.md](./metadata.md) for:
82+
- Static and dynamic metadata
83+
- `generateMetadata` function
84+
- OG image generation with `next/og`
85+
- File-based metadata conventions
86+
87+
## Image Optimization
88+
89+
See [image.md](./image.md) for:
90+
- Always use `next/image` over `<img>`
91+
- Remote images configuration
92+
- Responsive `sizes` attribute
93+
- Blur placeholders
94+
- Priority loading for LCP
95+
96+
## Font Optimization
97+
98+
See [font.md](./font.md) for:
99+
- `next/font` setup
100+
- Google Fonts, local fonts
101+
- Tailwind CSS integration
102+
- Preloading subsets
103+
104+
## Bundling
105+
106+
See [bundling.md](./bundling.md) for:
107+
- Server-incompatible packages
108+
- CSS imports (not link tags)
109+
- Polyfills (already included)
110+
- ESM/CommonJS issues
111+
- Bundle analysis
112+
113+
## Scripts
114+
115+
See [scripts.md](./scripts.md) for:
116+
- `next/script` vs native script tags
117+
- Inline scripts need `id`
118+
- Loading strategies
119+
- Google Analytics with `@next/third-parties`
120+
121+
## Hydration Errors
122+
123+
See [hydration-error.md](./hydration-error.md) for:
124+
- Common causes (browser APIs, dates, invalid HTML)
125+
- Debugging with error overlay
126+
- Fixes for each cause
127+
128+
## Suspense Boundaries
129+
130+
See [suspense-boundaries.md](./suspense-boundaries.md) for:
131+
- CSR bailout with `useSearchParams` and `usePathname`
132+
- Which hooks require Suspense boundaries
133+
134+
## Parallel & Intercepting Routes
135+
136+
See [parallel-routes.md](./parallel-routes.md) for:
137+
- Modal patterns with `@slot` and `(.)` interceptors
138+
- `default.tsx` for fallbacks
139+
- Closing modals correctly with `router.back()`
140+
141+
## Self-Hosting
142+
143+
See [self-hosting.md](./self-hosting.md) for:
144+
- `output: 'standalone'` for Docker
145+
- Cache handlers for multi-instance ISR
146+
- What works vs needs extra setup
147+
148+
## Debug Tricks
149+
150+
See [debug-tricks.md](./debug-tricks.md) for:
151+
- MCP endpoint for AI-assisted debugging
152+
- Rebuild specific routes with `--debug-build-paths`
153+

‎plugins/next/.agents/skills/next-best-practices/async-patterns.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Async Patterns
2+
3+
In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
4+
5+
## Async Params and SearchParams
6+
7+
Always type them as `Promise<...>` and await them.
8+
9+
### Pages and Layouts
10+
11+
```tsx
12+
type Props = { params: Promise<{ slug: string }> }
13+
14+
export default async function Page({ params }: Props) {
15+
const { slug } = await params
16+
}
17+
```
18+
19+
### Route Handlers
20+
21+
```tsx
22+
export async function GET(
23+
request: Request,
24+
{ params }: { params: Promise<{ id: string }> }
25+
) {
26+
const { id } = await params
27+
}
28+
```
29+
30+
### SearchParams
31+
32+
```tsx
33+
type Props = {
34+
params: Promise<{ slug: string }>
35+
searchParams: Promise<{ query?: string }>
36+
}
37+
38+
export default async function Page({ params, searchParams }: Props) {
39+
const { slug } = await params
40+
const { query } = await searchParams
41+
}
42+
```
43+
44+
### Synchronous Components
45+
46+
Use `React.use()` for non-async components:
47+
48+
```tsx
49+
import { use } from 'react'
50+
51+
type Props = { params: Promise<{ slug: string }> }
52+
53+
export default function Page({ params }: Props) {
54+
const { slug } = use(params)
55+
}
56+
```
57+
58+
### generateMetadata
59+
60+
```tsx
61+
type Props = { params: Promise<{ slug: string }> }
62+
63+
export async function generateMetadata({ params }: Props): Promise<Metadata> {
64+
const { slug } = await params
65+
return { title: slug }
66+
}
67+
```
68+
69+
## Async Cookies and Headers
70+
71+
```tsx
72+
import { cookies, headers } from 'next/headers'
73+
74+
export default async function Page() {
75+
const cookieStore = await cookies()
76+
const headersList = await headers()
77+
78+
const theme = cookieStore.get('theme')
79+
const userAgent = headersList.get('user-agent')
80+
}
81+
```
82+
83+
## Migration Codemod
84+
85+
```bash
86+
npx @next/codemod@latest next-async-request-api .
87+
```

0 commit comments

Comments
 (0)