Next.js 15 Performance Architect for Claude

CLAUDE.md Content

The main content for this claude.md.

nextjs-15-performance-architect.js

javascript

// next.config.mjs
export default {
  // Turbopack is default, but can configure options
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },
    },
  },
};

CLAUDE.md Content (2)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// Revalidate every hour
export const revalidate = 3600;

async function ProductPage({ params }) {
  const product = await fetch(`https://api.example.com/products/${params.id}`, {
    next: { revalidate: 3600 },
  });
  
  return <ProductDetails product={product} />;
}

CLAUDE.md Content (3)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { Suspense } from 'react';

export const experimental_ppr = true;

export default function Page() {
  return (
    <div>
      {/* Static content */}
      <Header />
      <Hero />
      
      {/* Dynamic content streams in */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <PersonalizedRecommendations />
      </Suspense>
      
      {/* Static content */}
      <Footer />
    </div>
  );
}

CLAUDE.md Content (4)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// Cache indefinitely (default)
await fetch('https://api.example.com/data');

// Revalidate every 60 seconds
await fetch('https://api.example.com/data', {
  next: { revalidate: 60 },
});

// No caching
await fetch('https://api.example.com/data', {
  cache: 'no-store',
});

// Tagged caching for on-demand revalidation
await fetch('https://api.example.com/data', {
  next: { tags: ['products'] },
});

CLAUDE.md Content (5)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import Image from 'next/image';

// Optimized images with automatic WebP/AVIF
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1920}
  height={1080}
  priority // Load above-the-fold images first
  placeholder="blur" // Show blur while loading
  blurDataURL="data:image/jpeg;base64,..."
/>

// Responsive images
<Image
  src="/product.jpg"
  alt="Product"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  style={{ objectFit: 'cover' }}
/>

CLAUDE.md Content (6)

Additional code example for this claude.md.

nextjs-15-performance-architect.js

javascript

// next.config.mjs
export default {
  images: {
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    minimumCacheTTL: 60,
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
      },
    ],
  },
};

CLAUDE.md Content (7)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import dynamic from 'next/dynamic';

// Lazy load heavy components
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <ChartSkeleton />,
  ssr: false, // Client-only rendering
});

// Load with named export
const DynamicComponent = dynamic(
  () => import('@/components/Dashboard').then((mod) => mod.Dashboard),
  { loading: () => <Skeleton /> }
);

CLAUDE.md Content (8)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { Inter, Roboto_Mono } from 'next/font/google';

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
});

const robotoMono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
});

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
      <body>{children}</body>
    </html>
  );
}

CLAUDE.md Content (9)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <Header />
      
      <Suspense fallback={<PostsSkeleton />}>
        <Posts />
      </Suspense>
      
      <Suspense fallback={<CommentsSkeleton />}>
        <Comments />
      </Suspense>
    </div>
  );
}

// Parallel data fetching with streaming
async function Dashboard() {
  return (
    <div>
      <Suspense fallback={<UserSkeleton />}>
        <UserProfile />
      </Suspense>
      
      <Suspense fallback={<AnalyticsSkeleton />}>
        <Analytics />
      </Suspense>
    </div>
  );
}

CLAUDE.md Content (10)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Run only on specific paths
  if (!request.nextUrl.pathname.startsWith('/api')) {
    return NextResponse.next();
  }
  
  // Lightweight checks only
  const token = request.cookies.get('token');
  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  
  return NextResponse.next();
}

export const config = {
  matcher: ['/api/:path*', '/dashboard/:path*'],
};

CLAUDE.md Content (11)

Additional code example for this claude.md.

nextjs-15-performance-architect.js

javascript

// next.config.mjs
import bundleAnalyzer from '@next/bundle-analyzer';

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
});

export default withBundleAnalyzer({
  // your config
});

CLAUDE.md Content (12)

Additional code example for this claude.md.

nextjs-15-performance-architect.sh

bash

ANALYZE=true npm run build

CLAUDE.md Content (13)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

async function UserDashboard({ userId }) {
  // Parallel queries
  const [user, posts, analytics] = await Promise.all([
    db.user.findUnique({ where: { id: userId } }),
    db.post.findMany({ where: { authorId: userId }, take: 10 }),
    db.analytics.aggregate({ where: { userId } }),
  ]);
  
  return <Dashboard user={user} posts={posts} analytics={analytics} />;
}

CLAUDE.md Content (14)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

export const runtime = 'edge';

export async function GET(request: Request) {
  // Runs on edge, closer to users
  const data = await fetch('https://api.example.com/data', {
    next: { revalidate: 60 },
  });
  
  return Response.json(data);
}

CLAUDE.md Content (15)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

export async function GET() {
  const encoder = new TextEncoder();
  
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 100; i++) {
        const data = await fetchChunk(i);
        controller.enqueue(encoder.encode(JSON.stringify(data) + '\n'));
      }
      controller.close();
    },
  });
  
  return new Response(stream);
}

CLAUDE.md Content (16)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next';
import { Analytics } from '@vercel/analytics/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
        <Analytics />
      </body>
    </html>
  );
}

CLAUDE.md Content (17)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// app/web-vitals.tsx
'use client'

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitals() {
  useReportWebVitals((metric) => {
    // Send to analytics
    console.log(metric);
  });
  
  return null;
}

Features

Key capabilities and functionality

Turbopack build optimization with default bundler in Next.js 15, 10x faster than Webpack, incremental compilation, native TypeScript/JSX compilation, automatic code splitting and tree shaking
Advanced rendering strategies including Static Generation (default), Incremental Static Regeneration (ISR), Partial Prerendering (PPR) for mixing static and dynamic content, and streaming with Suspense
Comprehensive caching strategies including request memoization (automatic deduplication), Data Cache (with revalidation and tags), Full Route Cache (build-time caching), and Router Cache (client-side route caching)
Image optimization with Next.js Image component supporting automatic WebP/AVIF conversion, responsive images, priority loading, blur placeholders, and remote pattern configuration
Code splitting and lazy loading with dynamic imports, route-based code splitting, shared chunk extraction, and route groups for logical splitting
Font optimization with next/font system supporting Google Fonts, local fonts, font display strategies, variable fonts, and automatic font subsetting
Core Web Vitals optimization including Largest Contentful Paint (LCP), First Input Delay (FID) / Interaction to Next Paint (INP), Cumulative Layout Shift (CLS), and comprehensive performance monitoring

Use Cases

Common scenarios and applications

Building high-performance Next.js 15 applications with Turbopack for lightning-fast builds and optimal bundle sizes
Implementing advanced caching strategies for optimal performance including ISR, PPR, tagged caching, and on-demand revalidation
Optimizing Core Web Vitals for superior user experience and SEO rankings through LCP, INP, and CLS improvements
Creating production-ready applications with comprehensive image optimization, font optimization, and code splitting strategies
Implementing streaming and progressive rendering with Suspense for optimal perceived performance and user experience
Building performant API routes with Edge Runtime, response streaming, and efficient middleware for minimal latency
Monitoring and optimizing application performance with Web Vitals tracking, bundle analysis, and performance budgets

Requirements

Prerequisites and dependencies

Create CLAUDE.md file in project root (./CLAUDE.md) or .claude/ directory (./.claude/CLAUDE.md)
Claude Code 1.0+ or Claude Desktop required for CLAUDE.md memory support and Next.js 15 performance guidance
Write access to project root or .claude/ directory for rule file creation
Next.js 15+ project with App Router (required for PPR, advanced caching, and Turbopack features)
Node.js 18.17+ runtime (required for Next.js 15 and Turbopack)
Understanding of Next.js App Router, React Server Components, and modern React patterns (Suspense, streaming)
Familiarity with performance optimization concepts (Core Web Vitals, caching strategies, code splitting, image optimization)
Text editor with Next.js support (VS Code with Next.js extensions, or preferred IDE) for editing code and CLAUDE.md rule file

Usage Examples

Practical code examples demonstrating common use cases and implementation patterns

Partial Prerendering (PPR) with Static and Dynamic Content

Next.js 15 PPR combining static shell with streaming dynamic content for optimal performance

partial-prerendering-ppr-with-static-and-dynamic-content.ts

typescript

import { Suspense } from 'react';

export const experimental_ppr = true;

export default function Page() {
  return (
    <div>
      {/* Static content - prerendered at build time */}
      <Header />
      <Hero />
      
      {/* Dynamic content streams in at request time */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <PersonalizedRecommendations />
      </Suspense>
      
      {/* Static content */}
      <Footer />
    </div>
  );
}

async function PersonalizedRecommendations() {
  // This streams in after static shell loads
  const recommendations = await fetch('https://api.example.com/recommendations', {
    next: { revalidate: 60 },
  });
  
  return <RecommendationsList items={await recommendations.json()} />;
}

Advanced Caching with Tags and On-Demand Revalidation

Tagged caching with on-demand revalidation for instant content updates

advanced-caching-with-tags-and-on-demand-revalidation.ts

typescript

// app/products/[id]/page.tsx
import { revalidateTag } from 'next/cache';

export default async function ProductPage({ params }) {
  const { id } = await params;
  
  // Fetch with cache tag for on-demand revalidation
  const product = await fetch(`https://api.example.com/products/${id}`, {
    next: { 
      revalidate: 3600, // Revalidate every hour
      tags: ['products', `product-${id}`],
    },
  });
  
  return <ProductDetails product={await product.json()} />;
}

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { tag } = await request.json();
  
  // Revalidate specific cache tag
  revalidateTag(tag);
  
  return NextResponse.json({ revalidated: true, tag });
}

Turbopack Configuration with Custom Rules

Turbopack configuration with custom loaders and rules for optimal build performance

turbopack-configuration-with-custom-rules.js

javascript

// next.config.mjs
export default {
  // Turbopack is default in Next.js 15
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        '*.mdx': {
          loaders: ['@next/mdx'],
          options: {
            remarkPlugins: [],
            rehypePlugins: [],
          },
        },
      },
    },
  },
};

Streaming with Parallel Data Fetching

Parallel data fetching with Suspense for optimal streaming performance

streaming-with-parallel-data-fetching.ts

typescript

import { Suspense } from 'react';

export default async function Dashboard() {
  return (
    <div>
      <Header />
      
      {/* Parallel data fetching with streaming */}
      <Suspense fallback={<UserSkeleton />}>
        <UserProfile />
      </Suspense>
      
      <Suspense fallback={<AnalyticsSkeleton />}>
        <Analytics />
      </Suspense>
      
      <Suspense fallback={<PostsSkeleton />}>
        <RecentPosts />
      </Suspense>
    </div>
  );
}

async function UserProfile() {
  const user = await fetch('https://api.example.com/user', {
    next: { revalidate: 60 },
  });
  return <UserCard user={await user.json()} />;
}

async function Analytics() {
  const analytics = await fetch('https://api.example.com/analytics', {
    next: { revalidate: 300 },
  });
  return <AnalyticsChart data={await analytics.json()} />;
}

async function RecentPosts() {
  const posts = await fetch('https://api.example.com/posts', {
    next: { revalidate: 60 },
  });
  return <PostsList posts={await posts.json()} />;
}

Image Optimization with Priority and Blur Placeholder

Optimized images with priority loading and blur placeholders for optimal LCP

image-optimization-with-priority-and-blur-placeholder.ts

typescript

import Image from 'next/image';

// Above-the-fold hero image with priority
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1920}
  height={1080}
  priority // Load immediately
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAAIAAoDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAhEAACAQMDBQAAAAAAAAAAAAABAgMABAUGIWGRkqGx0f/EABUBAQEAAAAAAAAAAAAAAAAAAAMF/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAECEgMRkf/aAAwDAQACEQMRAD8AltJagyeH0AthI5xdrLcNM91BF5pX2HaH9bcfaSXWGaRmknyJckliyjqTzSlT54b6bk+h0R//2Q=="
/>

// Responsive product image
<Image
  src="/product.jpg"
  alt="Product"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  style={{ objectFit: 'cover' }}
/>

Dynamic Import with Loading States

Code splitting with dynamic imports and loading states for optimal bundle size

dynamic-import-with-loading-states.ts

typescript

import dynamic from 'next/dynamic';

// Lazy load heavy chart component
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <ChartSkeleton />,
  ssr: false, // Client-only rendering
});

// Load with named export
const Dashboard = dynamic(
  () => import('@/components/Dashboard').then((mod) => mod.Dashboard),
  { 
    loading: () => <Skeleton />,
    ssr: true, // Server-side rendering enabled
  }
);

export default function Page() {
  return (
    <div>
      <Dashboard />
      <HeavyChart />
    </div>
  );
}

Web Vitals Monitoring and Reporting

Comprehensive Web Vitals tracking and reporting for performance monitoring

web-vitals-monitoring-and-reporting.ts

typescript

// app/layout.tsx
'use client';

import { SpeedInsights } from '@vercel/speed-insights/next';
import { Analytics } from '@vercel/analytics/react';
import { WebVitals } from '@/components/web-vitals';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
        <Analytics />
        <WebVitals />
      </body>
    </html>
  );
}

// components/web-vitals.tsx
'use client';

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitals() {
  useReportWebVitals((metric) => {
    // Send to analytics
    if (typeof window !== 'undefined' && window.gtag) {
      window.gtag('event', metric.name, {
        value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value),
        event_label: metric.id,
        non_interaction: true,
      });
    }
  });
  
  return null;
}

Installation

Setup instructions and requirements

Configuration

Configuration settings and parameters

nextjs-15-performance-architect.json

json

{
  "maxTokens": 8000,
  "temperature": 0.3,
  "systemPrompt": "You are a Next.js 15 performance architect focused on building extremely fast web applications",
  "compatibleWith": [
    "Claude Code",
    "Claude Desktop",
    "Claude Web"
  ]
}

Security Best Practices

Important security considerations

Next.js 15 performance optimization configurations and caching strategies may expose API endpoints, data fetching patterns, or internal application structure - review performance configurations before sharing externally if they reveal sensitive infrastructure
Turbopack build configurations and custom loader rules may expose build-time dependencies, asset processing strategies, or compilation optimizations - ensure build configurations are kept private if they contain sensitive information
Cache tags and revalidation strategies may reveal content update patterns, data refresh frequencies, or cache invalidation workflows - review caching strategies for sensitive business logic
Performance monitoring and Web Vitals tracking may expose user behavior patterns, page load times, or application performance metrics - ensure analytics data is properly anonymized and aggregated
Image optimization configurations and remote patterns may expose CDN endpoints, asset storage locations, or image processing strategies - review image configurations for sensitive infrastructure details
API route optimizations and Edge Runtime configurations may expose serverless function locations, edge network strategies, or API endpoint structures - sanitize API route examples before sharing
CLAUDE.md rule content for Next.js 15 performance may expose team-specific optimization strategies, caching patterns, or deployment workflows - ensure rule files are kept private if they contain sensitive organizational information

Troubleshooting

Common issues and solutions

Rule applies performance patterns to non-Next.js apps
This rule is Next.js 15-specific with Turbopack, PPR, and App Router patterns. For vanilla React or other frameworks, use react-expert or framework-specific rules instead.
Conflicts with React Server Components expert rule
Both rules complement each other. Performance architect focuses on caching/optimization; RSC expert covers component patterns. Use together for full Next.js 15 expertise - no override needed.
Not getting Turbopack-specific optimizations
Mention 'Turbopack' or 'build performance' explicitly. Rule assumes Turbopack by default in Next.js 15 but can provide webpack configs if you specify legacy bundler usage.
PPR patterns suggested when I'm not using experimental
Partial Prerendering requires experimental_ppr flag. Ask 'Is PPR enabled in my config?' - rule checks context and suggests stable alternatives if PPR isn't configured in your setup.
How to verify performance optimizations are applied?
Request 'Audit current caching strategy and Web Vitals setup' to see active optimizations. Rule analyzes fetch calls, image usage, and Suspense boundaries for performance verification.

CLAUDE.md Content

The main content for this claude.md.

nextjs-15-performance-architect.js

javascript

// next.config.mjs
export default {
  // Turbopack is default, but can configure options
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },
    },
  },
};

CLAUDE.md Content (2)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// Revalidate every hour
export const revalidate = 3600;

async function ProductPage({ params }) {
  const product = await fetch(`https://api.example.com/products/${params.id}`, {
    next: { revalidate: 3600 },
  });
  
  return <ProductDetails product={product} />;
}

CLAUDE.md Content (3)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { Suspense } from 'react';

export const experimental_ppr = true;

export default function Page() {
  return (
    <div>
      {/* Static content */}
      <Header />
      <Hero />
      
      {/* Dynamic content streams in */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <PersonalizedRecommendations />
      </Suspense>
      
      {/* Static content */}
      <Footer />
    </div>
  );
}

CLAUDE.md Content (4)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// Cache indefinitely (default)
await fetch('https://api.example.com/data');

// Revalidate every 60 seconds
await fetch('https://api.example.com/data', {
  next: { revalidate: 60 },
});

// No caching
await fetch('https://api.example.com/data', {
  cache: 'no-store',
});

// Tagged caching for on-demand revalidation
await fetch('https://api.example.com/data', {
  next: { tags: ['products'] },
});

CLAUDE.md Content (5)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import Image from 'next/image';

// Optimized images with automatic WebP/AVIF
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1920}
  height={1080}
  priority // Load above-the-fold images first
  placeholder="blur" // Show blur while loading
  blurDataURL="data:image/jpeg;base64,..."
/>

// Responsive images
<Image
  src="/product.jpg"
  alt="Product"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  style={{ objectFit: 'cover' }}
/>

CLAUDE.md Content (6)

Additional code example for this claude.md.

nextjs-15-performance-architect.js

javascript

// next.config.mjs
export default {
  images: {
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
    minimumCacheTTL: 60,
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
      },
    ],
  },
};

CLAUDE.md Content (7)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import dynamic from 'next/dynamic';

// Lazy load heavy components
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <ChartSkeleton />,
  ssr: false, // Client-only rendering
});

// Load with named export
const DynamicComponent = dynamic(
  () => import('@/components/Dashboard').then((mod) => mod.Dashboard),
  { loading: () => <Skeleton /> }
);

CLAUDE.md Content (8)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { Inter, Roboto_Mono } from 'next/font/google';

const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
});

const robotoMono = Roboto_Mono({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-roboto-mono',
});

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
      <body>{children}</body>
    </html>
  );
}

CLAUDE.md Content (9)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { Suspense } from 'react';

export default function Page() {
  return (
    <div>
      <Header />
      
      <Suspense fallback={<PostsSkeleton />}>
        <Posts />
      </Suspense>
      
      <Suspense fallback={<CommentsSkeleton />}>
        <Comments />
      </Suspense>
    </div>
  );
}

// Parallel data fetching with streaming
async function Dashboard() {
  return (
    <div>
      <Suspense fallback={<UserSkeleton />}>
        <UserProfile />
      </Suspense>
      
      <Suspense fallback={<AnalyticsSkeleton />}>
        <Analytics />
      </Suspense>
    </div>
  );
}

CLAUDE.md Content (10)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  // Run only on specific paths
  if (!request.nextUrl.pathname.startsWith('/api')) {
    return NextResponse.next();
  }
  
  // Lightweight checks only
  const token = request.cookies.get('token');
  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  
  return NextResponse.next();
}

export const config = {
  matcher: ['/api/:path*', '/dashboard/:path*'],
};

CLAUDE.md Content (11)

Additional code example for this claude.md.

nextjs-15-performance-architect.js

javascript

// next.config.mjs
import bundleAnalyzer from '@next/bundle-analyzer';

const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
});

export default withBundleAnalyzer({
  // your config
});

CLAUDE.md Content (12)

Additional code example for this claude.md.

nextjs-15-performance-architect.sh

bash

ANALYZE=true npm run build

CLAUDE.md Content (13)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

async function UserDashboard({ userId }) {
  // Parallel queries
  const [user, posts, analytics] = await Promise.all([
    db.user.findUnique({ where: { id: userId } }),
    db.post.findMany({ where: { authorId: userId }, take: 10 }),
    db.analytics.aggregate({ where: { userId } }),
  ]);
  
  return <Dashboard user={user} posts={posts} analytics={analytics} />;
}

CLAUDE.md Content (14)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

export const runtime = 'edge';

export async function GET(request: Request) {
  // Runs on edge, closer to users
  const data = await fetch('https://api.example.com/data', {
    next: { revalidate: 60 },
  });
  
  return Response.json(data);
}

CLAUDE.md Content (15)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

export async function GET() {
  const encoder = new TextEncoder();
  
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 100; i++) {
        const data = await fetchChunk(i);
        controller.enqueue(encoder.encode(JSON.stringify(data) + '\n'));
      }
      controller.close();
    },
  });
  
  return new Response(stream);
}

CLAUDE.md Content (16)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next';
import { Analytics } from '@vercel/analytics/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
        <Analytics />
      </body>
    </html>
  );
}

CLAUDE.md Content (17)

Additional code example for this claude.md.

nextjs-15-performance-architect.ts

typescript

// app/web-vitals.tsx
'use client'

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitals() {
  useReportWebVitals((metric) => {
    // Send to analytics
    console.log(metric);
  });
  
  return null;
}

Features

Key capabilities and functionality

Turbopack build optimization with default bundler in Next.js 15, 10x faster than Webpack, incremental compilation, native TypeScript/JSX compilation, automatic code splitting and tree shaking
Advanced rendering strategies including Static Generation (default), Incremental Static Regeneration (ISR), Partial Prerendering (PPR) for mixing static and dynamic content, and streaming with Suspense
Comprehensive caching strategies including request memoization (automatic deduplication), Data Cache (with revalidation and tags), Full Route Cache (build-time caching), and Router Cache (client-side route caching)
Image optimization with Next.js Image component supporting automatic WebP/AVIF conversion, responsive images, priority loading, blur placeholders, and remote pattern configuration
Code splitting and lazy loading with dynamic imports, route-based code splitting, shared chunk extraction, and route groups for logical splitting
Font optimization with next/font system supporting Google Fonts, local fonts, font display strategies, variable fonts, and automatic font subsetting
Core Web Vitals optimization including Largest Contentful Paint (LCP), First Input Delay (FID) / Interaction to Next Paint (INP), Cumulative Layout Shift (CLS), and comprehensive performance monitoring

Use Cases

Common scenarios and applications

Building high-performance Next.js 15 applications with Turbopack for lightning-fast builds and optimal bundle sizes
Implementing advanced caching strategies for optimal performance including ISR, PPR, tagged caching, and on-demand revalidation
Optimizing Core Web Vitals for superior user experience and SEO rankings through LCP, INP, and CLS improvements
Creating production-ready applications with comprehensive image optimization, font optimization, and code splitting strategies
Implementing streaming and progressive rendering with Suspense for optimal perceived performance and user experience
Building performant API routes with Edge Runtime, response streaming, and efficient middleware for minimal latency
Monitoring and optimizing application performance with Web Vitals tracking, bundle analysis, and performance budgets

Requirements

Prerequisites and dependencies

Create CLAUDE.md file in project root (./CLAUDE.md) or .claude/ directory (./.claude/CLAUDE.md)
Claude Code 1.0+ or Claude Desktop required for CLAUDE.md memory support and Next.js 15 performance guidance
Write access to project root or .claude/ directory for rule file creation
Next.js 15+ project with App Router (required for PPR, advanced caching, and Turbopack features)
Node.js 18.17+ runtime (required for Next.js 15 and Turbopack)
Understanding of Next.js App Router, React Server Components, and modern React patterns (Suspense, streaming)
Familiarity with performance optimization concepts (Core Web Vitals, caching strategies, code splitting, image optimization)
Text editor with Next.js support (VS Code with Next.js extensions, or preferred IDE) for editing code and CLAUDE.md rule file

Usage Examples

Practical code examples demonstrating common use cases and implementation patterns

Partial Prerendering (PPR) with Static and Dynamic Content

Next.js 15 PPR combining static shell with streaming dynamic content for optimal performance

partial-prerendering-ppr-with-static-and-dynamic-content.ts

typescript

import { Suspense } from 'react';

export const experimental_ppr = true;

export default function Page() {
  return (
    <div>
      {/* Static content - prerendered at build time */}
      <Header />
      <Hero />
      
      {/* Dynamic content streams in at request time */}
      <Suspense fallback={<RecommendationsSkeleton />}>
        <PersonalizedRecommendations />
      </Suspense>
      
      {/* Static content */}
      <Footer />
    </div>
  );
}

async function PersonalizedRecommendations() {
  // This streams in after static shell loads
  const recommendations = await fetch('https://api.example.com/recommendations', {
    next: { revalidate: 60 },
  });
  
  return <RecommendationsList items={await recommendations.json()} />;
}

Advanced Caching with Tags and On-Demand Revalidation

Tagged caching with on-demand revalidation for instant content updates

advanced-caching-with-tags-and-on-demand-revalidation.ts

typescript

// app/products/[id]/page.tsx
import { revalidateTag } from 'next/cache';

export default async function ProductPage({ params }) {
  const { id } = await params;
  
  // Fetch with cache tag for on-demand revalidation
  const product = await fetch(`https://api.example.com/products/${id}`, {
    next: { 
      revalidate: 3600, // Revalidate every hour
      tags: ['products', `product-${id}`],
    },
  });
  
  return <ProductDetails product={await product.json()} />;
}

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { tag } = await request.json();
  
  // Revalidate specific cache tag
  revalidateTag(tag);
  
  return NextResponse.json({ revalidated: true, tag });
}

Turbopack Configuration with Custom Rules

Turbopack configuration with custom loaders and rules for optimal build performance

turbopack-configuration-with-custom-rules.js

javascript

// next.config.mjs
export default {
  // Turbopack is default in Next.js 15
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        '*.mdx': {
          loaders: ['@next/mdx'],
          options: {
            remarkPlugins: [],
            rehypePlugins: [],
          },
        },
      },
    },
  },
};

Streaming with Parallel Data Fetching

Parallel data fetching with Suspense for optimal streaming performance

streaming-with-parallel-data-fetching.ts

typescript

import { Suspense } from 'react';

export default async function Dashboard() {
  return (
    <div>
      <Header />
      
      {/* Parallel data fetching with streaming */}
      <Suspense fallback={<UserSkeleton />}>
        <UserProfile />
      </Suspense>
      
      <Suspense fallback={<AnalyticsSkeleton />}>
        <Analytics />
      </Suspense>
      
      <Suspense fallback={<PostsSkeleton />}>
        <RecentPosts />
      </Suspense>
    </div>
  );
}

async function UserProfile() {
  const user = await fetch('https://api.example.com/user', {
    next: { revalidate: 60 },
  });
  return <UserCard user={await user.json()} />;
}

async function Analytics() {
  const analytics = await fetch('https://api.example.com/analytics', {
    next: { revalidate: 300 },
  });
  return <AnalyticsChart data={await analytics.json()} />;
}

async function RecentPosts() {
  const posts = await fetch('https://api.example.com/posts', {
    next: { revalidate: 60 },
  });
  return <PostsList posts={await posts.json()} />;
}

Image Optimization with Priority and Blur Placeholder

Optimized images with priority loading and blur placeholders for optimal LCP

image-optimization-with-priority-and-blur-placeholder.ts

typescript

import Image from 'next/image';

// Above-the-fold hero image with priority
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1920}
  height={1080}
  priority // Load immediately
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAAIAAoDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAhEAACAQMDBQAAAAAAAAAAAAABAgMABAUGIWGRkqGx0f/EABUBAQEAAAAAAAAAAAAAAAAAAAMF/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAECEgMRkf/aAAwDAQACEQMRAD8AltJagyeH0AthI5xdrLcNM91BF5pX2HaH9bcfaSXWGaRmknyJckliyjqTzSlT54b6bk+h0R//2Q=="
/>

// Responsive product image
<Image
  src="/product.jpg"
  alt="Product"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  style={{ objectFit: 'cover' }}
/>

Dynamic Import with Loading States

Code splitting with dynamic imports and loading states for optimal bundle size

dynamic-import-with-loading-states.ts

typescript

import dynamic from 'next/dynamic';

// Lazy load heavy chart component
const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
  loading: () => <ChartSkeleton />,
  ssr: false, // Client-only rendering
});

// Load with named export
const Dashboard = dynamic(
  () => import('@/components/Dashboard').then((mod) => mod.Dashboard),
  { 
    loading: () => <Skeleton />,
    ssr: true, // Server-side rendering enabled
  }
);

export default function Page() {
  return (
    <div>
      <Dashboard />
      <HeavyChart />
    </div>
  );
}

Web Vitals Monitoring and Reporting

Comprehensive Web Vitals tracking and reporting for performance monitoring

web-vitals-monitoring-and-reporting.ts

typescript

// app/layout.tsx
'use client';

import { SpeedInsights } from '@vercel/speed-insights/next';
import { Analytics } from '@vercel/analytics/react';
import { WebVitals } from '@/components/web-vitals';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
        <Analytics />
        <WebVitals />
      </body>
    </html>
  );
}

// components/web-vitals.tsx
'use client';

import { useReportWebVitals } from 'next/web-vitals';

export function WebVitals() {
  useReportWebVitals((metric) => {
    // Send to analytics
    if (typeof window !== 'undefined' && window.gtag) {
      window.gtag('event', metric.name, {
        value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value),
        event_label: metric.id,
        non_interaction: true,
      });
    }
  });
  
  return null;
}

Installation

Setup instructions and requirements

Configuration

Configuration settings and parameters

nextjs-15-performance-architect.json

json

{
  "maxTokens": 8000,
  "temperature": 0.3,
  "systemPrompt": "You are a Next.js 15 performance architect focused on building extremely fast web applications",
  "compatibleWith": [
    "Claude Code",
    "Claude Desktop",
    "Claude Web"
  ]
}

Security Best Practices

Important security considerations

Next.js 15 performance optimization configurations and caching strategies may expose API endpoints, data fetching patterns, or internal application structure - review performance configurations before sharing externally if they reveal sensitive infrastructure
Turbopack build configurations and custom loader rules may expose build-time dependencies, asset processing strategies, or compilation optimizations - ensure build configurations are kept private if they contain sensitive information
Cache tags and revalidation strategies may reveal content update patterns, data refresh frequencies, or cache invalidation workflows - review caching strategies for sensitive business logic
Performance monitoring and Web Vitals tracking may expose user behavior patterns, page load times, or application performance metrics - ensure analytics data is properly anonymized and aggregated
Image optimization configurations and remote patterns may expose CDN endpoints, asset storage locations, or image processing strategies - review image configurations for sensitive infrastructure details
API route optimizations and Edge Runtime configurations may expose serverless function locations, edge network strategies, or API endpoint structures - sanitize API route examples before sharing
CLAUDE.md rule content for Next.js 15 performance may expose team-specific optimization strategies, caching patterns, or deployment workflows - ensure rule files are kept private if they contain sensitive organizational information

Troubleshooting

Common issues and solutions

Rule applies performance patterns to non-Next.js apps
This rule is Next.js 15-specific with Turbopack, PPR, and App Router patterns. For vanilla React or other frameworks, use react-expert or framework-specific rules instead.
Conflicts with React Server Components expert rule
Both rules complement each other. Performance architect focuses on caching/optimization; RSC expert covers component patterns. Use together for full Next.js 15 expertise - no override needed.
Not getting Turbopack-specific optimizations
Mention 'Turbopack' or 'build performance' explicitly. Rule assumes Turbopack by default in Next.js 15 but can provide webpack configs if you specify legacy bundler usage.
PPR patterns suggested when I'm not using experimental
Partial Prerendering requires experimental_ppr flag. Ask 'Is PPR enabled in my config?' - rule checks context and suggests stable alternatives if PPR isn't configured in your setup.
How to verify performance optimizations are applied?
Request 'Audit current caching strategy and Web Vitals setup' to see active optimizations. Rule analyzes fetch calls, image usage, and Suspense boundaries for performance verification.

Resources

View on GitHub Documentation

CLAUDE.md Details

Temperature

0.3

Source

claudepro

Quick Actions

Related CLAUDE.mds

React Next Js Expert

Transform Claude into a React and Next.js specialist with deep knowledge of modern patterns, performance optimization, and best practices

React 19 Concurrent Features Specialist

React 19 concurrent features specialist with useTransition, useDeferredValue, Suspense boundaries, streaming SSR, and selective hydration patterns

React Expert

Transform Claude into a React and Next.js specialist with deep knowledge of modern patterns, performance optimization, and best practices

Hire Claude Developers

Growing community of AI engineers actively building with Claude

Active community1,700/month

Growth rateMonth 2

Specialized AI talent pool

30-day featured visibility

Early-stage pricing advantage

View Pricing & Post Job

Live in 5 minutes • Growing community

Resources

View on GitHub Documentation

CLAUDE.md Details

Temperature

0.3

Source

claudepro

Quick Actions

Hire Claude Developers

Growing community of AI engineers actively building with Claude

Active community1,700/month

Growth rateMonth 2

Specialized AI talent pool

30-day featured visibility

Early-stage pricing advantage

View Pricing & Post Job

Live in 5 minutes • Growing community

Nextjs 15 Performance Architect

Partial Prerendering (PPR) with Static and Dynamic Content

Advanced Caching with Tags and On-Demand Revalidation

Turbopack Configuration with Custom Rules

Streaming with Parallel Data Fetching

Image Optimization with Priority and Blur Placeholder

Dynamic Import with Loading States

Web Vitals Monitoring and Reporting

Reviews (0)

Nextjs 15 Performance Architect

Partial Prerendering (PPR) with Static and Dynamic Content

Advanced Caching with Tags and On-Demand Revalidation

Turbopack Configuration with Custom Rules

Streaming with Parallel Data Fetching

Image Optimization with Priority and Blur Placeholder

Dynamic Import with Loading States

Web Vitals Monitoring and Reporting

Reviews (0)

Category

Temperature

Source

React Next Js Expert

React 19 Concurrent Features Specialist

React Expert

Hire Claude Developers