Upload source maps for Next.js

Last updated:

|Edit this page|

On this page

  1. Install the PostHog Next.js config package

    Required
    Terminal
    npm install @posthog/nextjs-config

  2. Add PostHog config to your Next.js app

    Required

    Add the following to your next.config.js file:

    next.config.js
    import { withPostHogConfig } from "@posthog/nextjs-config";
    

    const nextConfig = {
      //...your nextjs config,
    };
    

    export default withPostHogConfig(nextConfig, {
      personalApiKey: process.env.POSTHOG_API_KEY, // Personal API Key
      envId: process.env.POSTHOG_ENV_ID, // Environment ID
      host: process.env.NEXT_PUBLIC_POSTHOG_HOST, // (optional), defaults to https://us.posthog.com
      sourcemaps: { // (optional)
          enabled: true, // (optional) Enable sourcemaps generation and upload, default to true on production builds
          project: "my-application", // (optional) Project name, defaults to repository name
          version: "1.0.0", // (optional) Release version, defaults to current git commit
          deleteAfterUpload: true, // (optional) Delete sourcemaps after upload, defaults to true
      },
    });

    Where you should set the following environment variables:

    Environment VariableDescription
    POSTHOG_API_KEYPersonal API key with at least write access on error tracking
    POSTHOG_ENV_IDProject ID you can find in your project settings
    NEXT_PUBLIC_POSTHOG_HOSTYour PostHog instance URL. Defaults to https://us.posthog.com

  3. Verify source map generation

    Checkpoint

    Before proceeding, confirm that source maps are being generated by checking for .js.map files in your dist directory. These are the symbol sets that will be used to unminify stack traces in PostHog.

  4. Inject and upload source maps

    Required
    The Next.js config package automatically handles source map injection and upload during the build process. No additional configuration is needed.

    Make sure you serve the injected files in production by running the same build and inject process in CI during deployment. PostHog will need access to these injected chunkId comments when building the stack traces.

  5. Verify source map upload and injection

    Checkpoint
    1. Confirm that source maps are successfully uploaded to PostHog.
    Check symbol sets in PostHog
    1. Confirm that the served files are injected with the correct source map comment in production in dev tools:
    JavaScript
    //# chunkId=0197e6db-9a73-7b91-9e80-4e1b7158db5c

Questions? Ask Max AI.

It's easier than reading through 698 pages of documentation

Community questions

Was this page useful?

Next article

Upload source maps for Nuxt

You can hook into the close event to generate and upload source maps for your Nuxt application like this: Build your project for production by running the following command: Post-build scripts should automatically generate and upload sourcemaps to PostHog. Before proceeding, confirm that sourcemaps are being properly uploaded. You can verify the injection is successful by checking your .mjs.map source map files for //# chunkId= comments. Make sure to serve these injected files in…

Read next article