Get Started

There are three ways to enable the debugger. Pick whichever fits your workflow.

Method 1: URL Parameter

Append ?debugger=true to any page URL.

https://yoursite.com/checkout?debugger=true

This is the simplest method and works on any environment, including production deploys (which is why you should keep the parameter secret if you ever use it there).

Method 2: Meta Tag

Add a meta tag to a page's <head> to enable the debugger for that page only.

<meta name="next-debug" content="true">

Useful for staging pages where you want the debugger always-on without requiring the URL parameter every time.

Method 3: Config Flag

Set debug: true in window.nextConfig before the SDK loads. This enables the debugger for every page that uses this config file.

<script>
  window.nextConfig = {
    apiKey: 'your-api-key',
    debug: true,
  };
</script>

Best for local development. Strip it out before deploying.

Verify It Is Working

After loading a page with the debugger enabled, you should see:

An overlay docked at the bottom of the page with panel tabs (Cart, Campaign, Config, Checkout, Events, Storage)
Console message: 🐛 Debug overlay loaded! Use nextDebug.overlay to control it.
A global nextDebug object available in the browser console

Try this in the console:

nextDebug.isDebugMode()  // → true
nextDebug.stores.cart.getState().items  // → array of cart items

If nextDebug is undefined, the debugger is not active. Re-check the URL parameter or config flag.

Disable Programmatically

nextDebug.disableDebug()  // strips the URL param and removes the overlay

The change takes effect after the next page load — the overlay will not be re-attached and nextDebug will not be defined.

Toggle the Overlay

const overlay = await nextDebug.overlay();
overlay.toggle();   // hide / show
overlay.show();
overlay.hide();

nextDebug.overlay is a lazy-loaded promise — await it before calling overlay methods.

The debugger exposes API keys, customer data, cart contents, and internal SDK state. Never enable it on a production page that real customers see. Use it on staging environments only, or strip the URL parameter and config flag from production builds.

The debug script is loaded on demand — pages that do not enable the debugger pay zero cost. There is no baseline overhead from the debugger code unless one of the three opt-ins is present.

Next Steps

Use nextDebug.* methods from the console: Console API
Full table of methods and properties: Reference → Methods