Next.js

Next.js is a full-stack framework for JavaScript and TypeScript web applications. This guide covers setting up client-side Crash Reporting for an existing Next.js application using the Raygun4JS provider.

In order to include Raygun4JS on each page in your application, we'll need to use the Custom Document system from Next.js.

If you do not already have a custom document located at pages/_document.js, save the following as pages/_document.js.

Please note: If you're using TypeScript, the Custom Document path will instead be pages/_document.ts.

import Document, { Html, Head, Main, NextScript } from "next/document";

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx);
    return { ...initialProps };
  }

  render() {
    return (
      <Html>
        <script
          type="text/javascript"
          dangerouslySetInnerHTML={{
            __html: `
              !function(a,b,c,d,e,f,g,h){a.RaygunObject=e,a[e]=a[e]||function(){
              (a[e].o=a[e].o||[]).push(arguments)},f=b.createElement(c),g=b.getElementsByTagName(c)[0],
              f.async=1,f.src=d,g.parentNode.insertBefore(f,g),h=a.onerror,a.onerror=function(b,c,d,f,g){
              h&&h(b,c,d,f,g),g||(g=new Error(b)),a[e].q=a[e].q||[],a[e].q.push({
              e:g})}}(window,document,"script","//cdn.raygun.io/raygun4js/raygun.min.js","rg4js");

              rg4js('apiKey', 'YOUR-RAYGUN-API-KEY');
              rg4js('enableCrashReporting', true);`,
          }}
        />
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

If you already have an existing pages/_document.js or pages/_document.ts, then add this code snippet immediately below the opening <Html> tag.

<script
  type="text/javascript"
  dangerouslySetInnerHTML={{
    __html: `
      !function(a,b,c,d,e,f,g,h){a.RaygunObject=e,a[e]=a[e]||function(){
      (a[e].o=a[e].o||[]).push(arguments)},f=b.createElement(c),g=b.getElementsByTagName(c)[0],
      f.async=1,f.src=d,g.parentNode.insertBefore(f,g),h=a.onerror,a.onerror=function(b,c,d,f,g){
      h&&h(b,c,d,f,g),g||(g=new Error(b)),a[e].q=a[e].q||[],a[e].q.push({
      e:g})}}(window,document,"script","//cdn.raygun.io/raygun4js/raygun.min.js","rg4js");

      rg4js('apiKey', 'YOUR-RAYGUN-API-KEY');
      rg4js('enableCrashReporting', true);`,
  }}
/>

Now, replace 'YOUR-RAYGUN-API-KEY' with your Raygun API key (available under "Application Settings" in your Raygun Account).

You can now track and fix any errors once you deploy your app.


If you're using Next.js v9.4 or later, you can also store your Raygun API key in the next.config.js file and load it as an environment variable. This can provide greater flexibility over which API key is used in different environments.

First, add your Raygun API key to your next.config.js file.

module.exports = {
  reactStrictMode: true,
  env: {
    RAYGUN_API_KEY: 'YOUR-RAYGUN-API-KEY'
  }
}

Once again, replace 'YOUR-RAYGUN-API-KEY' with your Raygun API key (available under "Application Settings" in your Raygun Account).

After that, add this snippet to your pages/_document.js or pages/_document.ts, immediately below the opening <Html> tag, replacing any existing Raygun <script> tag.

<script
  type="text/javascript"
  dangerouslySetInnerHTML={{
    __html: `
      !function(a,b,c,d,e,f,g,h){a.RaygunObject=e,a[e]=a[e]||function(){
      (a[e].o=a[e].o||[]).push(arguments)},f=b.createElement(c),g=b.getElementsByTagName(c)[0],
      f.async=1,f.src=d,g.parentNode.insertBefore(f,g),h=a.onerror,a.onerror=function(b,c,d,f,g){
      h&&h(b,c,d,f,g),g||(g=new Error(b)),a[e].q=a[e].q||[],a[e].q.push({
      e:g})}}(window,document,"script","//cdn.raygun.io/raygun4js/raygun.min.js","rg4js");

      rg4js('apiKey', '${process.env.RAYGUN_API_KEY}');
      rg4js('enableCrashReporting', true);`,
  }}
/>

The Raygun API key will now be loaded from the next.config.js file and included in the script tag that's sent to the browser.


It's necessary to use dangerouslySetInnerHTML to create an <script> tag with Next.js. The primary risk from dangerouslySetInnerHTML occurs when including untrusted data in HTML. All of the provided examples are either static strings, or interpolate data directly from the process's environment variables. As such, there is no risk of these issues when using the examples as provided.