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

> Understand the key differences between next export and next build for Next.js deployments. Learn when to use static exports versus full production builds for optimal performance.

- Repository: [Vercel/next.js](https://github.com/vercel/next.js)
- Tags: deep-dive
- Published: 2026-02-16

---

**`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](https://github.com/vercel/next.js) repository. The build pipeline in [`packages/next/src/cli/next-build.ts`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/next.config.js):

```javascript
// 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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/packages/next/src/cli/next-build.ts), which exports the `nextBuild` function:

```typescript
// 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`](https://github.com/vercel/next.js/blob/main/packages/next/src/cli/next-export.ts) now only prints an error message:

```typescript
// 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`](https://github.com/vercel/next.js/blob/main/packages/next/src/build/adapter/build-complete.ts). The `handleBuildComplete` function inspects the configuration:

```typescript
// 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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/next.config.js) and running `next build`. The legacy command in [`packages/next/src/cli/next-export.ts`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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.