1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
|
# Next.js 15 Claude Code Configuration 🚀
A comprehensive Claude Code configuration for building production-ready Next.js 15 applications with best practices, automated workflows, and intelligent assistance.
## ✨ Features
This configuration provides:
- **11 Specialized AI Agents** for different aspects of Next.js development
- **6 Powerful Commands** for common workflows
- **Intelligent Hooks** for automated validation and formatting
- **Optimized Settings** for Next.js development
- **Comprehensive Memory** with Next.js 15 best practices
## 📦 Installation
1. Copy the `.claude` directory to your Next.js project root:
```bash
cp -r nextjs-15/.claude your-nextjs-project/
cp nextjs-15/CLAUDE.md your-nextjs-project/
```
2. The configuration will be automatically loaded when you start Claude Code in your project.
## 🤖 Specialized Agents
### Core Development Agents
| Agent | Description | Use Cases |
|-------|-------------|-----------|
| `nextjs-app-router` | App Router routing expert | Creating pages, layouts, dynamic routes, parallel routes |
| `nextjs-server-components` | Server/Client component specialist | Optimizing component boundaries, fixing hydration issues |
| `nextjs-server-actions` | Server Actions expert | Forms, mutations, validation, progressive enhancement |
| `nextjs-data-fetching` | Data fetching & caching specialist | Fetch strategies, caching, revalidation, streaming |
| `nextjs-performance` | Performance optimization expert | Bundle analysis, Core Web Vitals, code splitting |
### Infrastructure & Testing Agents
| Agent | Description | Use Cases |
|-------|-------------|-----------|
| `nextjs-testing` | Testing framework specialist | Jest, Vitest, Playwright, Cypress setup |
| `nextjs-deployment` | Deployment & DevOps expert | Docker, Vercel, AWS, CI/CD pipelines |
| `nextjs-migration` | Migration specialist | Pages → App Router, version upgrades |
| `nextjs-security` | Security expert | Authentication, CSP, validation, OWASP |
| `nextjs-debugging` | Debugging specialist | React DevTools, error resolution, troubleshooting |
| `nextjs-typescript` | TypeScript expert | Type setup, fixing errors, type-safe patterns |
## 🛠️ Commands
### Quick Commands Reference
| Command | Description | Example |
|---------|-------------|---------|
| `/create-page` | Create a new page with proper structure | `/create-page products/[id]` |
| `/create-server-action` | Generate type-safe Server Action | `/create-server-action createUser user` |
| `/optimize-components` | Analyze and optimize component boundaries | `/optimize-components` |
| `/setup-testing` | Set up testing framework | `/setup-testing playwright` |
| `/analyze-performance` | Generate performance report | `/analyze-performance` |
| `/migrate-to-app-router` | Migrate from Pages Router | `/migrate-to-app-router /about` |
## 🪝 Intelligent Hooks
### Pre-commit Validation
- Validates Next.js 15 patterns (async params/searchParams)
- Checks for missing 'use client' directives
- Validates environment variable usage
- Runs TypeScript and ESLint checks
### Auto-formatting
- Formats TypeScript/JavaScript files with Prettier
- Validates Server Component patterns
- Suggests missing loading/error boundaries
### Smart Notifications
- Tips for better Next.js practices
- Warnings for common mistakes
- Performance suggestions
## ⚙️ Configuration
### Settings Overview
The configuration includes:
- **Permissions**: Safe defaults for Next.js development
- **Environment**: Optimized for Next.js workflows
- **Hooks**: Automated validation and formatting
- **Status Line**: Shows Next.js version and build status
### Customization
Edit `.claude/settings.json` to customize:
```json
{
"permissions": {
"allow": ["Write(app/**/*)", "Bash(npm run dev*)"],
"deny": ["Read(.env.production)"]
},
"env": {
"NEXT_PUBLIC_API_URL": "http://localhost:3000"
}
}
```
## 🚀 Usage Examples
### Creating a New Feature
```bash
# 1. Create a new page with all necessary files
> /create-page dashboard/analytics
# 2. Claude will create:
# - app/dashboard/analytics/page.tsx
# - app/dashboard/analytics/loading.tsx
# - app/dashboard/analytics/error.tsx
```
### Optimizing Performance
```bash
# Analyze current performance
> /analyze-performance
# Claude will:
# - Run bundle analysis
# - Check Core Web Vitals
# - Identify optimization opportunities
# - Generate detailed report
```
### Setting Up Authentication
```bash
# Use the security agent
> Use the nextjs-security agent to set up authentication with NextAuth.js
# Claude will:
# - Configure NextAuth.js
# - Set up providers
# - Create middleware
# - Implement session management
```
## 📚 Best Practices Enforced
This configuration enforces Next.js 15 best practices:
1. **Server Components by Default** - Minimizes client-side JavaScript
2. **Proper Async Handling** - Handles async params/searchParams correctly
3. **Type Safety** - Full TypeScript support with proper types
4. **Security First** - Input validation, authentication, CSP
5. **Performance Optimized** - Code splitting, caching, streaming
6. **Testing Coverage** - Comprehensive testing setup
7. **Progressive Enhancement** - Forms work without JavaScript
## 🔄 Upgrading
To upgrade the configuration:
```bash
# Pull latest configuration
git pull origin main
# Copy updated files
cp -r nextjs-15/.claude your-project/
```
## 🤝 Contributing
Contributions are welcome! To improve this configuration:
1. Fork the repository
2. Create a feature branch
3. Add your improvements
4. Submit a pull request
### Areas for Contribution
- Additional specialized agents
- More automation commands
- Enhanced hooks
- Testing improvements
- Documentation updates
## 📖 Documentation
Each component is fully documented:
- **Agents**: Detailed prompts and expertise areas
- **Commands**: Clear descriptions and examples
- **Hooks**: Validation logic and automation
- **Settings**: Permission patterns and configuration
## 🐛 Troubleshooting
### Common Issues
**Issue**: Hooks not executing
```bash
# Check hook permissions
chmod +x .claude/hooks/*.sh
```
**Issue**: Agent not responding
```bash
# Verify agent file exists
ls .claude/agents/
```
**Issue**: Commands not found
```bash
# Reload Claude Code configuration
# Exit and restart Claude Code
```
## 📝 License
MIT License - Feel free to use in your projects!
## 🙏 Acknowledgments
Built using:
- Official Next.js 15 documentation
- React 19 best practices
- Community feedback and patterns
- Production experience
---
**Made with ❤️ for the Next.js community**
*This configuration helps developers build better Next.js applications with Claude Code's intelligent assistance.*
|
