`rewrites (next.config)`

Maps an incoming path to a different destination without changing the URL.

Since Next 9.5+ Spec ↗

Syntax

async rewrites() { return [{ source, destination }] }

Parameters

Name	Type	Required	Description
`rewrites`	`() => Promise<Rewrite[] \| { beforeFiles, afterFiles, fallback }>`	No	Rules with `source`/`destination`, optionally grouped by execution phase.

Returns

Promise<Rewrite[]> — Internal path mappings (URL unchanged).

Examples

const nextConfig = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'https://api.example.com/:path*',
      },
    ]
  },
}
module.exports = nextConfig

const nextConfig = {
  async rewrites() {
    return {
      beforeFiles: [{ source: '/docs', destination: '/help' }],
      afterFiles: [],
      fallback: [],
    }
  },
}
module.exports = nextConfig

Notes

Unlike redirects, rewrites are transparent to the user (URL stays the same) — useful for proxying APIs or masking internal paths. The object form controls ordering relative to filesystem routes (`beforeFiles`, `afterFiles`, `fallback`). Proxying external hosts passes through query/params.