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:

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.

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

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

Version History