Next.js Deployment Optimization

Next.js Deployment Optimization

Reduce bundle size, split code strategically, and optimize runtime performance for production

When to Use

• Reducing JavaScript bundle size to improve Time to Interactive (TTI)
• Lazy loading heavy components (rich text editors, chart libraries, maps) that are not needed on first paint
• Analyzing which modules contribute most to bundle size
• Optimizing for Vercel, Docker, or self-hosted deployments
• Reducing cold start times for serverless functions

Instructions

1. Run ANALYZE=true next build with @next/bundle-analyzer to identify large modules in the bundle.
2. Use next/dynamic to lazy load Client Components that are not needed for initial render.
3. Pass { ssr: false } to next/dynamic for components that use browser-only APIs (window, document, navigator).
4. Use import() directly inside Server Components for code splitting without next/dynamic.
5. Move large libraries (PDF generators, Excel parsers, video processors) to Route Handlers or Server Actions to keep them off the client bundle entirely.
6. Set experimental.optimizePackageImports in next.config.ts for icon and component libraries to tree-shake unused exports.
7. Use next/font to self-host fonts with zero layout shift — fonts are downloaded at build time.
8. Enable compression and set proper cache headers in your deployment infrastructure for static assets.

// next.config.ts — bundle analyzer and package optimization
import type { NextConfig } from 'next';
import bundleAnalyzer from '@next/bundle-analyzer';

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

const config: NextConfig = {
  experimental: {
    optimizePackageImports: ['lucide-react', '@radix-ui/react-icons', 'date-fns'],
  },
};

export default withBundleAnalyzer(config);

// app/editor/page.tsx — lazy load heavy Client Component
import dynamic from 'next/dynamic';

const RichTextEditor = dynamic(() => import('@/components/rich-text-editor'), {
  loading: () => <p>Loading editor...</p>,
  ssr: false, // editor uses window APIs
});

export default function EditorPage() {
  return <RichTextEditor />;
}

// app/fonts.ts — self-hosted fonts
import { Inter, Fira_Code } from 'next/font/google';

export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
export const firaCode = Fira_Code({ subsets: ['latin'], variable: '--font-fira-code' });

Details

Next.js performs automatic code splitting at the route level — each page only loads its own JavaScript. Additional optimization opportunities exist at the component and library level.

Bundle analyzer workflow: Install @next/bundle-analyzer, add it to next.config.ts, run ANALYZE=true next build. Two treemaps open (client and server bundles). Look for unexpectedly large modules, duplicated libraries (two versions of the same package), and server-only code in the client bundle.

next/dynamic vs React.lazy: next/dynamic wraps React.lazy and adds Next.js-specific features: ssr: false, loading components, and named export support. Use next/dynamic in Next.js projects — React.lazy works too but lacks these features.

ssr: false use cases: Components that import browser APIs at module level (not just in event handlers) must use ssr: false. Common examples: maps (Leaflet, Mapbox), rich text editors (Quill, TipTap), WebGL renderers.

optimizePackageImports: Icon libraries like lucide-react export hundreds of icons. Without tree-shaking, importing one icon pulls in the entire library. optimizePackageImports tells Next.js to rewrite imports to their direct module paths, enabling tree-shaking.

Standalone output: For Docker deployments, set output: 'standalone' in next.config.ts. This produces a minimal build artifact with only the production dependencies needed, significantly reducing Docker image size.

Source

https://nextjs.org/docs/app/building-your-application/optimizing

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.