| Error: next/script is not allowed in the _document file in Next.js: Causes and How to Fix

Error: next/script is not allowed in the _document file in Next.js: Causes and How to Fix

February 10, 2025

Discover the causes of the "next/script not allowed in _document" error in Next.js and learn effective solutions to fix it effortlessly in your projects.

What is Error: next/script is not allowed in the _document file in Next.js

Understanding the Error

In Next.js, the \_document.js file is a custom component that is responsible for updating the HTML document structure that Next.js's server-side rendering produces. It is important to understand that its purpose is to augment the static structure of the document and customize the initial server-side rendering of the HTML.

next/script is a specialized component in Next.js used for loading third-party scripts and managing their execution behavior, such as setting loading strategies. next/script can be powerful for managing scripts dynamically within the application, leveraging Next.js's features to optimize loading and performance.

Reason for the Restriction

The \_document.js file is executed on the server side only. It is rendered only once during the server-side rendering process to create the initial HTML structure, which means it doesn't run on the client side.

In contrast, the next/script component is designed to be used on the client side to manage script loading and execution. It facilitates various optimizations that are specifically client-oriented and therefore is not viable in a server-side rendering context like \_document.js.

Consequences of Misuse

Using next/script inside the \_document.js will lead to a build-time error because this setup does not align with the intended architecture of Next.js.

The server-side nature of \_document.js contradicts the need to manage dynamic scripts that rely on client-side execution and interaction. As such, including next/script in this file would not only result in an error but would defeat the script’s purpose entirely.

Code Context

// Example of a typical _document.js file structure
import Document, { Html, Head, Main, NextScript } from 'next/document';

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          {/* Meta tags and other head elements can be included here */}
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Best Practices

Always use the next/script component in files such as \_app.js or directly within page components where client-side logic is handled and optimized scripts can be managed effectively.

Keep the \_document.js file minimal and focused on structural elements that are static and essential for server-rendered HTML content optimization.

What Causes Error: next/script is not allowed in the _document file in Next.js

Understanding the Error: next/script in _document.js

In Next.js, the `next/script` component is used for managing the loading of third-party scripts efficiently and optimally. It provides features to enable lazy loading, prioritize script execution, and prevent render-blocking, which enhances the performance of web applications.

The `_document.js` file in Next.js is a special file used for customizing the default Document structure of a Next.js application. It is responsible for controlling the initial HTML document markup, including ``, ``, and `` tags. It is only rendered on the server side.

The error "next/script is not allowed in the \_document file" arises due to the logic of separating server-rendered and client-rendered components in Next.js. The `next/script` component is designed to operate with client-side execution, and placing it in `_document.js` conflicts with the server-rendered nature of this file.

In essence, the `next/script` component needs to access the browser's `window` object for operations like lazy loading and executing scripts when they're needed. Since the `_document.js` file is executed in a server-side context, it does not have access to the `window` object, which is only available on the client side. This is one main reason why it is disallowed in this file.

Let's look at a minimal example of `_document.js`, where the use of `next/script` would cause an error:

import { Html, Head, Main, NextScript } from 'next/document';
import Script from 'next/script';

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          <Script src="https://example.com/some-external-script.js" strategy="lazyOnload" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

In the example above, placing `
How to Fix Error: next/script is not allowed in the _document file in Next.js
Understanding the Error Context

The `next/script` component is designed to be used within the Next.js page for optimal performance and loading sequence control, but it cannot be used in the custom `_document` file.

To properly include scripts in your custom `_document`, alternative methods need to be employed.

Using Custom Scripts in _document

One way to embed custom scripts in the `_document.js` is to manually add them within the `next/head` component. This method involves directly using HTML `