next export vs next build: Key Differences for Next.js Deployment

next build creates a full-stack production build with server-side capabilities, while next export (now deprecated in favor of output: 'export') generates only static HTML files suitable for static hosting.

Understanding the distinction between next export vs next build is critical when deploying Next.js applications from the vercel/next.js repository. The build pipeline in packages/next/src/cli/next-build.ts handles both scenarios, but the output differs dramatically based on your configuration.

Architectural Differences Between next build and next export

Full-Stack Production Builds

When you run next build without export configuration, the compiler in packages/next/src/build/index.ts generates a complete runtime environment. The process creates:

• Server bundles in .next/server/ containing API routes, middleware, and SSR logic
• Client bundles in .next/static/ for browser execution
• Image optimization endpoints ready for runtime processing
• Edge function manifests for platforms like Vercel or Cloudflare Workers

The handleBuildComplete function in packages/next/src/build/adapter/build-complete.ts detects the standard build path and preserves all server-side outputs, enabling you to run next start to launch a Node.js server.

Static-Only Export Mode

The next export CLI command has been removed in recent canary releases. The equivalent functionality now requires setting output: 'export' in next.config.js:

// next.config.js
module.exports = {
  output: 'export',
  distDir: 'dist', // optional: defaults to 'out'
}

When next build executes with this configuration, the adapter logic in build-complete.ts checks config.output === 'export' and switches to static-only generation. Instead of creating server bundles, it walks the build output directory and registers every file as a STATIC_FILE output, resulting in a directory of HTML, CSS, and JavaScript files with no Node.js runtime requirement.

How the Build Process Works in Next.js

CLI Entry Points

The build pipeline starts in packages/next/src/cli/next-build.ts, which exports the nextBuild function:

// packages/next/src/cli/next-build.ts
export const nextBuild = async (options, directory?) => {
  // Resolves bundler (Turbopack or Webpack)
  // Triggers the build process
}

For the deprecated export command, packages/next/src/cli/next-export.ts now only prints an error message:

// packages/next/src/cli/next-export.ts
const nextExport = () => {
  error(`\`next export\` has been removed in favor of 'output: export' …`);
};

Adapter Logic and Output Detection

The critical distinction between build modes happens in packages/next/src/build/adapter/build-complete.ts. The handleBuildComplete function inspects the configuration:

// packages/next/src/build/adapter/build-complete.ts (excerpt)
if (config.output === 'export') {
  // Collect only static files and push them into outputs.staticFiles
} else {
  // Regular server-side outputs (pages, APIs, middleware, etc.)
}

When output: 'export' is detected, the adapter skips creating PAGES, PAGES_API, APP_PAGE, APP_ROUTE, and MIDDLEWARE outputs. Instead, it treats every file in the output directory as a static asset suitable for CDN deployment.

What You Lose with Static Export

Using output: 'export' eliminates several dynamic capabilities:

• API Routes (pages/api/*) — These server-side endpoints are not generated because there is no runtime to execute them.
• Middleware (middleware.ts) — Edge middleware is omitted from the output.
• Image Optimization — The default image loader requires a server. The build emits a warning from packages/next/src/shared/lib/get-img-props.ts: "Image Optimization using the default loader is not compatible with { output: 'export' }".
• Incremental Static Regeneration (ISR) — While ISR fallback pages can be generated at build time, the regeneration capability requires a server runtime and is unavailable in pure static mode.

Summary

• next build (default) creates a full-stack production build in .next/ with server bundles, API routes, middleware, and image optimization, requiring next start or a serverless platform to run.
• output: 'export' (replacing the deprecated next export) generates only static HTML/CSS/JS files in out/ (or your configured distDir), suitable for any static host but lacking server-side features.
• The adapter logic in packages/next/src/build/adapter/build-complete.ts detects the output configuration and determines whether to emit server bundles or static files only.

Frequently Asked Questions

Is next export deprecated?

Yes, the next export CLI command has been removed in recent Next.js canary releases. The same functionality is now achieved by setting output: 'export' in next.config.js and running next build. The legacy command in packages/next/src/cli/next-export.ts now only prints a deprecation error.

Can I use API routes with next export?

No, API routes (pages/api/*) are not supported when using output: 'export'. The static export mode generates only client-side assets and HTML files. Since API routes require a server runtime to execute, they are omitted from the build output by the adapter logic in packages/next/src/build/adapter/build-complete.ts.

How do I deploy a static Next.js site?

To deploy a static Next.js site, configure next.config.js with output: 'export', run next build, and deploy the resulting out/ directory (or your configured distDir) to any static hosting provider like GitHub Pages, Netlify, AWS S3, or Cloudflare Pages. The build process will generate only static HTML, CSS, and JavaScript files with no server runtime requirement.

What is the difference between .next and out folders?

The .next folder is generated by standard next build and contains both static assets and server-side code required to run the application with next start. The out folder (or your custom distDir) is generated when using output: 'export' and contains only static HTML, CSS, and JavaScript files suitable for deployment to a static host without any Node.js runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}