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.