This feature is currently experimental and subject to change, it’s not recommended for production. Try it out and share your feedback on GitHub.

exposeTestingApiInProductionBuild

Use experimental.exposeTestingApiInProductionBuild to include the Instant Navigation testing API in a production build. The instant() helper from @next/playwright uses this API to pause request-time content while an end-to-end test asserts on the UI available immediately.

Enable the option only for a dedicated test build:

next.config.ts
import type { NextConfig } from 'next'

const exposeTestingApi = process.env.EXPOSE_TESTING_API === '1'

const nextConfig: NextConfig = {
  cacheComponents: true,
  experimental: {
    exposeTestingApiInProductionBuild: exposeTestingApi,
  },
}

export default nextConfig

Set EXPOSE_TESTING_API=1 when you build and start the test server.

Terminal
EXPOSE_TESTING_API=1 pnpm build
EXPOSE_TESTING_API=1 pnpm start

The server reloads next.config at startup, so keep the option enabled when you run next start. If you disable the option at startup, instant() allows initial page loads to render request-time content while continuing to pause client navigations.

Setting the condition only for next start does not add the testing API to an existing build.

Reference

ValueBehavior
false or unsetExcludes the testing API from production builds. This is the default.
trueIncludes the testing API in the production build.

The option requires cacheComponents. Development builds expose the testing API automatically when Cache Components is enabled.

Good to know

Do not enable this option for a user-facing production deployment. Restrict it to local production builds, preview deployments, or other environments used for end-to-end tests.

Version History

VersionChanges
v16.2.0experimental.exposeTestingApiInProductionBuild introduced.

Learn how to inspect and test instant navigation.

Last updated