basePath
Serves the whole application under a sub-path of a domain, such as /docs.
basePath?: string- Added in Next.js v9.5.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$basePathoptional | string= '' (empty string) | A path prefix applied to the whole application, for example '/docs'. Must begin with a slash and have no trailing slash. The value is inlined into the client bundles at build time, so changing it requires a rebuild. |
Changelog
- PHP v9.5.0Customizable basePath added; previously assetPrefix was misused for this.
With basePath: '/docs' the route defined at app/about/page.tsx is served at /docs/about. next/link and the router prefix hrefs for you, so <Link href="/about"> renders <a href="/docs/about"> and application code keeps using unprefixed paths.
When to reach for it
- Hosting docs or a dashboard on a sub-path of a shared domain.
- Sitting behind a reverse proxy that mounts the app at a directory.
- Running several apps on one hostname without subdomains.
What trips people up
The prefixing is not universal. Raw <a href>, fetch() URLs, next/image src values and anything you reference out of public/ are left alone — those you prefix by hand, so /docs/me.png. redirects, rewrites and headers sources are prefixed automatically, and basePath: false opts a single entry out, which is only valid for external destinations. The value is inlined into the client bundle at build time, so it cannot be supplied as a runtime environment variable — a different sub-path means a different build.
Example
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
basePath: '/docs',
}
export default nextConfigWhen to use it
- Serve a documentation app at example.com/docs alongside a separate marketing site
- Mount an internal dashboard under /admin behind an existing reverse proxy
- Host several independent Next.js apps on one hostname by path
Frequently asked questions
Why is my image 404ing after setting basePath?
next/image does not prefix src. With basePath: '/docs' the file at public/me.png is served from /docs/me.png, so write that full path in src. The same applies to plain <a> tags and any fetch URL you build by hand.
Can I set basePath from an environment variable at runtime?
No. The value is inlined into the client-side bundles during next build, so it must be fixed at build time. Deploying the same artifact under a different sub-path requires rebuilding with the new value.
Should I use basePath or assetPrefix for sub-path hosting?
basePath. assetPrefix only moves /_next/ asset URLs to another origin and does not affect routing; the docs explicitly recommend basePath for hosting under a sub-path like /docs.
More examples
What is prefixed and what is not
Link and the router apply the prefix so internal navigation keeps working if the basePath ever changes. Everything that bypasses the router — the src of next/image, a plain anchor, a fetch URL, a file in public/ — is emitted verbatim, so a missing prefix 404s only in the deployed environment, never in a default local build.
// app/page.tsx (served at /docs)
import Link from 'next/link'
import Image from 'next/image'
export default function HomePage() {
return (
<>
{/* renders <a href="/docs/about"> */}
<Link href="/about">About Page</Link>
{/* NOT prefixed: write the basePath yourself */}
<Image
src="/docs/me.png"
alt="Picture of the author"
width={500}
height={500}
/>
{/* NOT prefixed either */}
<a href="/docs/changelog.pdf">Changelog</a>
</>
)
}Opting a redirect out of the prefix
Routing config inherits the prefix on both source and destination, which keeps rules readable as the basePath changes. basePath: false disables that for one entry, and is only meaningful when the destination is external — an internal path with the prefix removed would resolve outside the mounted app.
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
basePath: '/docs',
async redirects() {
return [
{
// becomes /docs/with-basePath -> /docs/another
source: '/with-basePath',
destination: '/another',
permanent: false,
},
{
source: '/without-basePath',
destination: 'https://example.com',
basePath: false,
permanent: false,
},
]
},
}
export default nextConfig
Discussion