Server Configurations

1. allowedDevOrigins

During development, Next.js does not block cross-origin requests by default, but in a future major release, cross-origin requests will be blocked to prevent unauthorized access to internal assets or endpoints exposed in development mode.

The allowedDevOrigins option lets you specify additional origins allowed to access your Next.js development server beyond the default localhost. This is useful if you develop across multiple local domains or use custom hostnames.

Example: Allow local-origin.dev and all its subdomains in development by adding this to next.config.js:

module.exports = {
  allowedDevOrigins: ['local-origin.dev', '*.local-origin.dev'],
}

With this, requests coming from these origins during development won't be blocked by Next.js.

2. assetPrefix

Note: Deploying to Vercel automatically sets up a global CDN, so manually configuring assetPrefix is usually unnecessary.

assetPrefix lets you specify a prefix URL for serving static assets like JavaScript and CSS from a CDN or external domain.

Typical use case: Serve static files from your own CDN in production, while using local assets in development.

Example next.config.mjs with environment-aware asset prefix:

// @ts-check
import { PHASE_DEVELOPMENT_SERVER } from 'next/constants'

export default (phase) => {
  const isDev = phase === PHASE_DEVELOPMENT_SERVER
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    assetPrefix: isDev ? undefined : 'https://cdn.mydomain.com',
  }
  return nextConfig
}

With this config, the URL for JS chunks like /_next/static/chunks/abcd.js will be rewritten to:https://cdn.mydomain.com/_next/static/chunks/abcd.js

Note: You must upload only the contents of .next/static/ to your CDN under the path _next/static/. The rest of the build output should remain private on your server.

Important: This prefix only affects /_next/static/ assets. Public folder assets (like /favicon.ico) are not automatically prefixed and need manual prefixing if served via CDN.

3. basePath

The basePath option is used when deploying your Next.js app under a sub-path on your domain, for example, https://example.com/docs instead of the root /.

Example: Serve your app at /docs by adding to next.config.js:

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

Important: This must be set at build time and requires rebuilding the app to change.

Links generated by next/link and next/router automatically prepend /docs:


import Link from 'next/link'

export default function HomePage() {
  return <>
    <Link href="/about">About Page</Link>
  </>
}

Outputs to:

<a href="/docs/about">About Page</a>

When using next/image, prepend basePath manually in the src:


import Image from 'next/image'

function Home() {
  return <>
    <Image src="/docs/me.png" alt="Picture of the author" width={500} height={500} />
  </>
}

4. crossOrigin

The crossOrigin option adds a crossOrigin attribute to all <script> tags generated by next/script, controlling how cross-origin requests are handled.

Possible values:

'anonymous': Adds crossOrigin="anonymous", omitting credentials.
'use-credentials': Adds crossOrigin="use-credentials", sending credentials like cookies.

Example to enable anonymous cross-origin loading:

module.exports = {
  crossOrigin: 'anonymous',
}

5. devIndicators

The devIndicators option controls the on-screen route status indicator during development, which shows if a page is static or dynamic.

Settings:

false: Hide the indicator but still show build/runtime errors.
Or configure with position:

module.exports = {
  devIndicators: {
    position: 'top-right', // 'bottom-left' by default
  },
}

Static pages are marked with a circle (○), dynamic pages with an f (ƒ). This helps identify static optimization status during development.

If a route expected to be static shows as dynamic, it might use dynamic APIs or uncacheable data fetching that prevent static prerendering.

6. htmlLimitedBots

htmlLimitedBots allows specifying user agent patterns to serve blocking metadata instead of streaming metadata for bots with limited HTML support.

Example setting in next.config.ts:

import type { NextConfig } from 'next'

const config: NextConfig = {
  htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/,
}

export default config

This overrides Next.js' default list of HTML limited bots, giving full control over which crawlers receive non-streaming metadata. This is an advanced configuration, generally not needed unless you have custom crawlers with special requirements.

7. httpAgentOptions

Node.js versions prior to 18 use undici to polyfill fetch() with HTTP Keep-Alive enabled by default for server-side fetch calls.

You can disable HTTP Keep-Alive globally for all server-side fetch() calls by setting httpAgentOptions.keepAlive to false in next.config.js:

module.exports = {
  httpAgentOptions: {
    keepAlive: false,
  },
}

This might be useful if your server environment or proxies have issues with persistent HTTP connections.

MENU