mirror of https://github.com/vercel/next.js.git synced 2026-09-20 02:25:18 +08:00

Files

T

Wyatt Johnson b9edb9175e feat: add Claude Code plugin marketplace with Cache Components skill (#87993 )

### 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 |

2026-01-08 22:37:28 +00:00

cache-components

feat: add Claude Code plugin marketplace with Cache Components skill (#87993 )

2026-01-08 22:37:28 +00:00

README.md

feat: add Claude Code plugin marketplace with Cache Components skill (#87993 )

2026-01-08 22:37:28 +00:00

README.md

Next.js Claude Code Plugins

This directory contains Claude Code plugins for Next.js development.

Using the Next.js Plugin Marketplace

The Next.js repository serves as a Claude Code plugin marketplace. Team members and contributors can install plugins directly from this repo.

Quick Start

# Add the Next.js marketplace
/plugin marketplace add vercel/next.js

# List available plugins
/plugin list

# Install a plugin
/plugin install cache-components@nextjs

Available Plugins

Plugin	Description
`cache-components`	Expert guidance for Cache Components and PPR

For Team Members

To auto-enable plugins for everyone working in a Next.js project, add to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "nextjs": {
      "source": {
        "source": "github",
        "repo": "vercel/next.js"
      }
    }
  },
  "enabledPlugins": {
    "cache-components@nextjs": true
  }
}

Creating New Plugins

To add a new plugin to the marketplace:

1. Create Plugin Directory

mkdir -p .claude-plugin/plugins/my-plugin/.claude-plugin
mkdir -p .claude-plugin/plugins/my-plugin/skills/my-skill

2. Create Plugin Manifest

File: .claude-plugin/plugins/my-plugin/.claude-plugin/plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What the plugin does",
  "author": {
    "name": "Next.js Team"
  }
}

3. Create Skill

File: .claude-plugin/plugins/my-plugin/skills/my-skill/SKILL.md

---
name: my-skill
description: When to use this skill
---

# My Skill

Instructions for Claude...

4. Register in Marketplace

Add to .claude-plugin/marketplace.json:

{
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "What it does"
    }
  ]
}

5. Test Locally

claude --plugin-dir .claude-plugin/plugins/my-plugin

Plugin Structure

.claude-plugin/
├── marketplace.json                       ← Marketplace catalog
└── plugins/
    ├── README.md                          ← This file
    └── cache-components/
        ├── .claude-plugin/
        │   └── plugin.json                ← Plugin manifest
        ├── skills/
        │   └── cache-components/
        │       ├── SKILL.md               ← Main skill file
        │       ├── REFERENCE.md           ← API reference
        │       ├── PATTERNS.md            ← Usage patterns
        │       └── TROUBLESHOOTING.md     ← Debugging guide
        └── README.md                      ← Plugin documentation