#next config options

1 messages · Page 1 of 1 (latest)

worn karma Nov 25, 2025, 11:54 AM

Explain to me what each option of the next.config.ts does, the available values that can be configured and watch each does:

output
distDir
images.unoptimized
basePath: ""
assetPrefix: "./",
trailingSlash

carmine bobcatBOT Nov 25, 2025, 11:54 AM

Hi @worn karma. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

Below is what the knowledge sources explicitly say about each option. Where something is not covered, I’ll call that out.

`output`

Used to enable static export (no server) when set to "export".

In next.config:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',

  // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
  // trailingSlash: true,

  // Optional: Prevent automatic `/me` -> `/me/`, instead preserve `href`
  // skipTrailingSlashRedirect: true,

  // Optional: Change the output directory `out` -> `dist`
  // distDir: 'dist',
}
module.exports = nextConfig
``` [[Static export (App)](<https://nextjs.org/docs/app/guides/static-exports>); [Static export (Pages)](<https://nextjs.org/docs/pages/guides/static-exports>)]

Behavior when `output: "export"`:

- `next build` creates a static `out` folder with HTML/CSS/JS assets, which can be hosted on any static web server. [[Static export (App)](<https://nextjs.org/docs/app/guides/static-exports>)]
- With `trailingSlash: true`, pages like `/about` output to `/about/index.html` instead of `/about.html`. [[trailingSlash (App)](<https://nextjs.org/docs/app/api-reference/config/next-config-js/trailingSlash>); [trailingSlash (Pages)](<https://nextjs.org/docs/pages/api-reference/config/next-config-js/trailingSlash>)]

The docs only show `"export"` as a documented value in these sources.

---

### `distDir`

Controls the directory where the build output is written when using `next build`.

In the static export docs it appears as:

```js
const nextConfig = {
  output: 'export',
  // Optional: Change the output directory `out` -> `dist`
  // distDir: 'dist',
}
``` [[Static export (App)](<https://nextjs.org/docs/app/guides/static-exports>); [Static export (Pages)](<https://nextjs.org/docs/pages/guides/static-exports>)]

Default: out (when using output: 'export').
If you set distDir: 'dist', static assets will be emitted into dist instead of out. [Static export (App)]

The sources do not list all possible values beyond “a folder name string”.

`images.unoptimized`

Controls whether images handled by next/image are optimized or served as‑is.

From the Image component docs: [Image unoptimized (App); Image unoptimized (Pages)]

Per‑image prop:

import Image from 'next/image'
 
const UnoptimizedImage = (props) => {
  // Default is false
  return <Image {...props} unoptimized />
}

Configuring globally in next.config.js:

module.exports = {
  images: {
    unoptimized: true,
  },
}
``` [[Image unoptimized (App)](<https://nextjs.org/docs/app/api-reference/components/image#unoptimized>)]

Semantics:

- `unoptimized: false` (default):  
  - Images are optimized (quality/size/format).
- `unoptimized: true`:  
  - Source images are served as‑is from `src` (no quality/size/format changes). [[Image unoptimized (App)](<https://nextjs.org/docs/app/api-reference/components/image#unoptimized>)]

This is recommended for images that don’t benefit from optimization (small, SVG, GIF). [[Image unoptimized (App)](<https://nextjs.org/docs/app/api-reference/components/image#unoptimized>)]

When using static export (`output: 'export'`), making images unoptimized (or using a custom loader) is one documented pattern. [[Static export (Pages)](<https://nextjs.org/docs/pages/guides/static-exports>); [GitHub issue 81259](<https://github.com/vercel/next.js/issues/81259>)]

---

### `basePath: ""`

basePath lets you serve the app under a sub‑path (e.g. /docs) instead of the domain root. [basePath (App); basePath (Pages)]

Example:

module.exports = {
  basePath: '/docs',
}

Key points:

Must be set at build time; changing it requires rebuilding because it is inlined into client bundles. [basePath (App)]
When using next/link (and next/router in the Pages Router), basePath is automatically prefixed in generated URLs:
- href="/about" → rendered as <a href="/docs/about"> when basePath: '/docs'. [basePath (App); basePath (Pages)]
For next/image, you must include the basePath in the src:
```
<Image src="/docs/me.png" ... />
```
when basePath: '/docs'. [basePath (App)]

Your specific value basePath: "" is just the default (no sub‑path). The docs only show examples with "/docs"; they don’t explicitly describe behavior for the empty string, but the implied default is “no prefix”. [basePath (App)]

`assetPrefix: "./"`

The provided sources show assetPrefix being used in examples, but do not document its semantics in detail.

Examples:

In a next.config.ts snippet: [GitHub issue 80163]

const nextConfig: NextConfig = {
  assetPrefix: process.env.BASE_PATH,
  // ...
}

In a GitHub Actions build config: [GitHub issue 74792]

const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
    domains: [],
  },
  trailingSlash: true,
  assetPrefix: process.env.NODE_ENV === 'production' ? './' : '',
  reactStrictMode: true,
}

From these, we can say:

assetPrefix accepts a string (e.g. environment‑dependent or "./").
The knowledge sources here do not explicitly describe what it changes (such as how it affects static asset URLs), so I cannot confidently detail its behavior based only on these docs.

`trailingSlash`

Controls whether routes use trailing slashes and how Next.js redirects between the two forms.

Baseline behavior (no config):

Default: URLs with a trailing slash redirect to the version without a trailing slash (e.g. /about/ → /about). [trailingSlash (App); trailingSlash (Pages)]

Configuring in next.config.js:

module.exports = {
  trailingSlash: true,
}
``` [[trailingSlash (App)](<https://nextjs.org/docs/app/api-reference/config/next-config-js/trailingSlash>)]

Behavior:

trailingSlash: true
- URLs without a trailing slash redirect to the version with a trailing slash. Example: /about → /about/. [trailingSlash (App)]
- Exceptions (no trailing slash added):
  - Static file URLs (paths with file extensions).
  - Any paths under .well-known/.
  - Examples that remain unchanged: /file.txt, /images/photos/picture.png, .well-known/subfolder/config.json. [trailingSlash (App); trailingSlash (Pages)]
- With output: "export", a page /about is emitted as /about/index.html (instead of /about.html). [trailingSlash (App); trailingSlash (Pages)]
trailingSlash: false
- Not directly documented in the Next.js config docs, but the Vercel project configuration docs show the analogous behavior:
  - Paths with a trailing slash redirect to the same path without the trailing slash (e.g. /about/ → /about), via an HTTP 308 redirect. [Vercel trailingSlash]
- There is no separate statement in the Next.js docs page listing false as a value, but this is implied by the default behavior description.

Version history:

Added in Next.js v9.5.0. [trailingSlash (App); trailingSlash (Pages)]

If you want, I can suggest combinations of these options for specific deployment targets (e.g. GitHub Pages, subdirectory on a custom server) using only what’s documented in these sources.

#next config options

output

images.unoptimized

assetPrefix: "./"

trailingSlash

If you want, I can suggest combinations of these options for specific deployment targets (e.g. GitHub Pages, subdirectory on a custom server) using only what’s documented in these sources.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

`output`

`images.unoptimized`

`assetPrefix: "./"`

`trailingSlash`