mirror of
https://github.com/hanzoai/next.js.git
synced 2026-10-30 14:46:38 +00:00
Wyatt JohnsonandGitHub
b9edb9175e
### What?
Adds a Claude Code plugin marketplace to the Next.js repository with an
initial `cache-components` plugin that provides expert guidance for
Cache Components and Partial Prerendering (PPR).
### Why?
Cache Components introduces a new programming model that combines
Partial Prerendering, Dynamic I/O, and the `"use cache"` directive. Team
members and contributors need guidance on:
- The `'use cache'` directive and its variants (`private`, `remote`)
- Cache lifetime configuration with `cacheLife()` and predefined
profiles
- Cache tagging and invalidation with `cacheTag()`, `updateTag()`,
`revalidateTag()`
- Parameter permutation rendering and subshell generation with
`generateStaticParams`
- Migration from deprecated `revalidate` and `dynamic` segment configs
- Build-time error resolution (dynamic data outside Suspense, uncached
data, etc.)
A Claude Code plugin allows this knowledge to be distributed directly
from the repo and proactively activated when working in projects with
`cacheComponents: true`.
### How?
Introduces the `.claude-plugin/` directory structure:
```
.claude-plugin/
├── marketplace.json ← Marketplace catalog (name: "nextjs")
└── plugins/
├── README.md ← Documentation for adding plugins
└── cache-components/
├── .claude-plugin/plugin.json ← Plugin manifest
├── README.md ← Plugin documentation
└── skills/cache-components/
├── SKILL.md ← Core concepts, mental model (496 lines)
├── REFERENCE.md ← API reference, migrations (875 lines)
├── PATTERNS.md ← 12 production patterns (781 lines)
└── TROUBLESHOOTING.md ← Build errors, debugging (721 lines)
```
**Installation:**
```bash
/plugin marketplace add vercel/next.js
/plugin install cache-components@nextjs
```
**Key skill features:**
- **Proactive activation** when `cacheComponents: true` is detected in
next.config
- **Mental model decision tree** for thinking through caching decisions
- **Cache scope clarification** explaining what creates new cache
entries
- **updateTag vs revalidateTag guide** with decision table and examples
- **Migration scenarios** from deprecated `revalidate`/`dynamic` segment
configs
- **Quick debugging checklist** for common cache issues
- **Parameter permutation rendering** (how `generateStaticParams`
creates subshells)
- **12 production patterns** including e-commerce, multi-tenant SaaS,
and subshell composition
### Documentation Highlights
| Section | Description |
|---------|-------------|
| Mental Model | Decision tree for when to use `'use cache'`, `'use
cache: private'`, or `<Suspense>` |
| Cache Scope | What creates new cache entries (function identity,
arguments, file path) |
| updateTag vs revalidateTag | Decision guide with e-commerce examples |
| Migration Scenarios | Before/after examples for `revalidate`,
`force-dynamic`, and ISR patterns |
| Quick Debugging Checklist | Copy-paste checklists for common issues |
Cache Components Plugin for Claude Code
Expert guidance for Next.js Cache Components and Partial Prerendering (PPR).
Features
This plugin provides a comprehensive skill that:
- Proactively activates in projects with
cacheComponents: true - Teaches the
'use cache'directive,cacheLife(),cacheTag(), and invalidation APIs - Explains parameter permutation rendering and subshell generation
- Covers migration from deprecated
revalidate/dynamicsegment configs - Provides build-time error solutions and debugging guidance
Installation
Step 1: Add the Next.js Marketplace
/plugin marketplace add vercel/next.js
Step 2: Install the Plugin
/plugin install cache-components@nextjs
Or install via CLI:
claude plugin install cache-components@nextjs
Step 3 (Optional): Enable for Your Team
Add to your project's .claude/settings.json to auto-enable for all team members:
{
"enabledPlugins": {
"cache-components@nextjs": true
}
}
What's Included
| File | Description |
|---|---|
SKILL.md |
Core concepts, APIs, and proactive application guidelines |
REFERENCE.md |
Complete API reference, generateStaticParams, deprecated configs |
PATTERNS.md |
12 production patterns including subshell composition |
TROUBLESHOOTING.md |
Build errors, debugging techniques, common issues |
Usage
Once installed, the skill automatically activates when:
- You're working in a Next.js project with
cacheComponents: true - You ask about caching, PPR, or the
'use cache'directive - You're writing React Server Components or Server Actions
Example Triggers
- "How do I cache this data fetching function?"
- "What's the difference between updateTag and revalidateTag?"
- "I'm getting a build error about uncached data outside Suspense"
- "Help me set up generateStaticParams for my product pages"
Key Concepts Covered
Parameter Permutation Rendering
When you provide generateStaticParams, Next.js renders ALL permutations:
generateStaticParams returns:
[{ category: 'jackets', slug: 'bomber' }]
Next.js renders:
/products/jackets/bomber ← Complete page
/products/jackets/[slug] ← Category subshell (reusable!)
/products/[category]/[slug] ← Fallback shell
Deprecated Segment Configs
| Old (Deprecated) | New (Cache Components) |
|---|---|
export const revalidate = 3600 |
cacheLife('hours') inside 'use cache' |
export const dynamic = 'force-static' |
Use 'use cache' + Suspense |
Contributing
This plugin lives in the Next.js repository at .claude-plugin/plugins/cache-components/.
To contribute improvements:
- Edit files in
.claude-plugin/plugins/cache-components/skills/cache-components/ - Test locally with
claude --plugin-dir .claude-plugin/plugins/cache-components - Submit a PR to the Next.js repository
Version History
1.0.0
- Initial release
- Covers
'use cache',cacheLife(),cacheTag(),updateTag(),revalidateTag() - Parameter permutation rendering and subshell generation
- Migration guide from deprecated segment configs
- Build-time feedback and troubleshooting