skills/atman36/nextjs-optimization/SKILL.md
Optimize Next.js 15 applications for performance, Core Web Vitals, and production best practices using App Router patterns
npx skillsauth add aiskillstore/marketplace nextjs-optimizationInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Optimize Next.js applications to achieve:
Auto-invoke when:
next in dependencies)Tools: Read, Grep
Verify Next.js version:
# Read package.json
# Check for "next": "^15.0.0" or higher
Detect App Router (Next.js 13+):
app/ directorylayout.tsx, page.tsx filesDetect Pages Router (Legacy):
pages/ directoryGoal: Choose optimal rendering for each page/component
Tools: Read, Grep, Edit
When to use:
Pattern:
// app/dashboard/page.tsx
export default async function DashboardPage() {
const data = await fetchData(); // Runs on server
return <Dashboard data={data} />;
}
Check for violations:
# Search for "use client" in components that don't need it
grep -r "use client" app/ | grep -v "onClick\|useState\|useEffect"
When to use:
Pattern:
// app/components/Counter.tsx
'use client';
export default function Counter() {
const [count, setCount] = useState(0);
return <button onClick={() => setCount(count + 1)}>{count}</button>;
}
Optimization: Keep client components small and leaf nodes
When to use:
Pattern:
export const revalidate = 3600; // Revalidate every hour
export default async function BlogPost({ params }) {
const post = await getPost(params.slug);
return <Article post={post} />;
}
When to use:
Pattern:
export const revalidate = 60; // Revalidate every minute
export async function generateStaticParams() {
const products = await getProducts();
return products.map((p) => ({ slug: p.slug }));
}
Goal: Optimize images for performance and Core Web Vitals
Tools: Grep, Read, Edit
Find unoptimized images:
grep -rn "<img " app/ src/
Replace with:
import Image from 'next/image';
<Image
src="/hero.jpg"
alt="Hero image"
width={1200}
height={600}
priority // For above-the-fold images
placeholder="blur" // Optional blur-up effect
/>
Read next.config.js:
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
},
],
formats: ['image/avif', 'image/webp'], // Modern formats
},
};
Goal: Eliminate FOUT/FOIT and improve font loading
Tools: Read, Edit
Pattern:
// app/layout.tsx
import { Inter } from 'next/font/google';
const inter = Inter({
subsets: ['latin'],
display: 'swap', // Prevent FOIT
variable: '--font-inter',
});
export default function RootLayout({ children }) {
return (
<html lang="en" className={inter.variable}>
<body>{children}</body>
</html>
);
}
import localFont from 'next/font/local';
const customFont = localFont({
src: './fonts/CustomFont.woff2',
display: 'swap',
variable: '--font-custom',
});
Goal: Minimize waterfalls and optimize cache
Tools: Read, Grep, Edit
Anti-pattern (Sequential):
const user = await getUser();
const posts = await getPosts(user.id); // Waits for user
Optimized (Parallel):
const [user, posts] = await Promise.all([
getUser(),
getPosts(),
]);
Pattern:
import { Suspense } from 'react';
export default function Page() {
return (
<>
<Header />
<Suspense fallback={<Skeleton />}>
<SlowComponent />
</Suspense>
<Footer />
</>
);
}
// Aggressive caching
fetch('https://api.example.com/data', {
next: { revalidate: 3600 }, // Cache for 1 hour
});
// No caching
fetch('https://api.example.com/data', {
cache: 'no-store', // Always fresh
});
// Opt out of caching
export const dynamic = 'force-dynamic';
Goal: Reduce JavaScript bundle size
Tools: Bash, Read, Edit
# Add to package.json scripts
npm run build
npx @next/bundle-analyzer
Find large components:
find app -name "*.tsx" -exec wc -l {} \; | sort -rn | head -10
Split with dynamic imports:
import dynamic from 'next/dynamic';
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
loading: () => <Skeleton />,
ssr: false, // Skip SSR if not needed
});
Check for barrel exports:
grep -rn "export \* from" app/
Replace with specific imports:
// Anti-pattern
import { Button, Card, Modal } from '@/components';
// Optimized
import { Button } from '@/components/Button';
Goal: Perfect SEO and social sharing
Tools: Read, Edit
// app/layout.tsx
export const metadata = {
title: {
default: 'My App',
template: '%s | My App',
},
description: 'Description for SEO',
openGraph: {
title: 'My App',
description: 'Description for social sharing',
images: ['/og-image.jpg'],
},
twitter: {
card: 'summary_large_image',
},
};
export async function generateMetadata({ params }) {
const post = await getPost(params.slug);
return {
title: post.title,
description: post.excerpt,
openGraph: {
images: [post.ogImage],
},
};
}
Goal: Optimize next.config.js for production
Tools: Read, Edit
// next.config.js
module.exports = {
reactStrictMode: true,
poweredByHeader: false, // Security
compress: true, // Gzip compression
// Compiler optimizations
compiler: {
removeConsole: process.env.NODE_ENV === 'production',
},
// Image optimization
images: {
formats: ['image/avif', 'image/webp'],
deviceSizes: [640, 750, 828, 1080, 1200, 1920],
},
// React Compiler (Next.js 15)
experimental: {
reactCompiler: true,
},
};
// package.json
{
"scripts": {
"dev": "next dev --turbo"
}
}
Goal: Achieve perfect Lighthouse scores
Tools: Bash, Grep, Edit
Optimize:
priority on hero images// Preload critical resources
<link rel="preload" href="/hero.jpg" as="image" />
Optimize:
import Script from 'next/script';
<Script
src="https://analytics.example.com"
strategy="lazyOnload" // Load after page interactive
/>
Optimize:
font-display: swap/* Reserve space for ads/banners */
.ad-container {
min-height: 250px;
}
Goal: Maximize cache hits and minimize server load
Tools: Read, Edit
// app/dashboard/page.tsx
export const revalidate = 3600; // ISR every hour
export const dynamic = 'auto'; // Automatic optimization
export const fetchCache = 'force-cache'; // Aggressive caching
// Deduplicated and cached automatically
const user = await fetch('https://api.example.com/user');
// Revalidate tag-based
export const revalidate = 60;
export const tags = ['user', 'profile'];
Goal: Track performance over time
Tools: Bash, WebSearch
// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<SpeedInsights />
</body>
</html>
);
}
# Run Lighthouse
npx lighthouse http://localhost:3000 --view
# Check Core Web Vitals
npm run build
npm run start
npx lighthouse http://localhost:3000 --only-categories=performance
Run through this checklist:
next/image with proper dimensionsnext/font with display: swap<Suspense>next.config.js has production optimizations# Next.js Optimization Report
## Current Status
- **Next.js Version**: 15.0.3
- **Rendering**: App Router
- **React Version**: 19.0.0
## Issues Found
### 🔴 Critical (3)
1. **Unoptimized Images**: 12 `<img>` tags found
- Files: `app/page.tsx`, `app/about/page.tsx`
- Fix: Replace with `next/image`
2. **Large Client Bundle**: 342 KB (target: < 200 KB)
- Cause: Heavy chart library loaded synchronously
- Fix: Use dynamic import for `Chart` component
3. **Missing Font Optimization**: Using Google Fonts via <link>
- Fix: Migrate to `next/font/google`
### 🟡 Warnings (2)
1. **Sequential Data Fetching**: Waterfall detected in `app/dashboard/page.tsx`
2. **No Metadata**: Missing OpenGraph tags on 5 pages
## Optimizations Applied
✅ Enabled React Compiler in next.config.js
✅ Added image optimization config
✅ Configured proper cache headers
✅ Added Suspense boundaries to slow routes
## Performance Impact (Estimated)
- **Load Time**: 3.2s → 1.8s (-44%)
- **Bundle Size**: 342 KB → 198 KB (-42%)
- **LCP**: 3.1s → 2.3s (✅ Good)
- **FID**: 85ms → 45ms (✅ Good)
- **CLS**: 0.15 → 0.05 (✅ Good)
## Next Steps
1. Replace 12 `<img>` tags with `next/image`
2. Split Chart component with dynamic import
3. Add metadata to 5 pages
4. Run Lighthouse to verify improvements
codebase-analysis - Detect Next.js project and versionquality-gates - Run build and verify no regressionsreact-patterns - Ensure React 19 best practicestesting-strategy - Add performance tests❌ Using 'use client' at the top level ❌ Not specifying image dimensions ❌ Synchronous data fetching ❌ Loading entire component libraries ❌ No Suspense boundaries ❌ Ignoring Core Web Vitals
development
Apple Human Interface Guidelines for content display components. Use this skill when the user asks about charts component, collection view, image view, web view, color well, image well, activity view, lockup, data visualization, content display, displaying images, rendering web content, color pickers, or presenting collections of items in Apple apps. Also use when the user says how should I display charts, what's the best way to show images, should I use a web view, how do I build a grid of items, what component shows media, or how do I present a share sheet. Cross-references: hig-foundations for color/typography/accessibility, hig-patterns for data visualization patterns, hig-components-layout for structural containers, hig-platforms for platform-specific component behavior.
tools
Automate HelpDesk tasks via Rube MCP (Composio): list tickets, manage views, use canned responses, and configure custom fields. Always search tools first for current schemas.
testing
Expert Haskell engineer specializing in advanced type systems, pure functional design, and high-reliability software. Use PROACTIVELY for type-level programming, concurrency, and architecture guidance.
tools
GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper controls, clients can craft queries that bring down your server. This skill covers schema design, resolvers, DataLoader for N+1 prevention, federation for microservices, and client integration with Apollo/urql. Key insight: GraphQL is a contract. The schema is the API documentation. Design it carefully.