Add warning for custom documents

Author: devknoll

errors/custom-document-rsc.md

@@ -0,0 +1,9 @@
+# Custom Document must be a functional Server Component
+
+#### Why This Error Occurred
+
+Your `next.config.js` has `concurrentFeatures: true` and your `pages/_document` page doesn't export a React Server Component.
+
+#### Possible Ways to Fix It
+
+Set `concurrentFeatures: false` or convert `pages/_document` to a React Server Component.

packages/next/build/index.ts

@@ -13,6 +13,7 @@ import formatWebpackMessages from '../client/dev/error-overlay/format-webpack-me
 import {
   STATIC_STATUS_PAGE_GET_INITIAL_PROPS_ERROR,
   PUBLIC_DIR_MIDDLEWARE_CONFLICT,
+  CUSTOM_DOCUMENT_RSC_ERROR,
 } from '../lib/constants'
 import { fileExists } from '../lib/file-exists'
 import { findPagesDir } from '../lib/find-pages-dir'
@@ -85,6 +86,7 @@ import {
   printCustomRoutes,
   printTreeView,
   getCssFilePaths,
+  hasFunctionalComponentExport,
 } from './utils'
 import getBaseWebpackConfig from './webpack-config'
 import { PagesManifest } from './webpack/plugins/pages-manifest-plugin'
@@ -690,6 +692,18 @@ export default async function build(
           )
         }
 
+        if (config.experimental?.concurrentFeatures) {
+          const customDocumentFunctional = await hasFunctionalComponentExport(
+            '/_document',
+            distDir,
+            isLikeServerless,
+            runtimeEnvConfig
+          )
+          if (!customDocumentFunctional) {
+            throw new Error(CUSTOM_DOCUMENT_RSC_ERROR)
+          }
+        }
+
         await Promise.all(
           pageKeys.map(async (page) => {
             const checkPageSpan = staticCheckSpan.traceChild('check-page', {

packages/next/build/utils.ts

@@ -868,6 +868,22 @@ export async function hasCustomGetInitialProps(
   return mod.getInitialProps !== mod.origGetInitialProps
 }
 
+export async function hasFunctionalComponentExport(
+  page: string,
+  distDir: string,
+  isLikeServerless: boolean,
+  runtimeEnvConfig: any
+): Promise<boolean> {
+  require('../next-server/lib/runtime-config').setConfig(runtimeEnvConfig)
+
+  const components = await loadComponents(distDir, page, isLikeServerless)
+  let mod = components.ComponentMod
+  mod = mod.default || mod
+  mod = await mod
+
+  return typeof mod === 'function' && !mod.prototype
+}
+
 export async function getNamedExports(
   page: string,
   distDir: string,

packages/next/lib/constants.ts

@@ -48,3 +48,5 @@ export const GSSP_COMPONENT_MEMBER_ERROR = `can not be attached to a page's comp
 export const NON_STANDARD_NODE_ENV = `You are using a non-standard "NODE_ENV" value in your environment. This creates inconsistencies in the project and is strongly advised against. Read more: https://nextjs.org/docs/messages/non-standard-node-env`
 
 export const SSG_FALLBACK_EXPORT_ERROR = `Pages with \`fallback\` enabled in \`getStaticPaths\` can not be exported. See more info here: https://nextjs.org/docs/messages/ssg-fallback-true-export`
+
+export const CUSTOM_DOCUMENT_RSC_ERROR = `Custom Document must be a functional Server Component. See more info here: https://nextjs.org/docs/messages/custom-document-rsc`

packages/next/next-server/server/render.tsx

@@ -13,6 +13,7 @@ import {
   SERVER_PROPS_SSG_CONFLICT,
   SSG_GET_INITIAL_PROPS_CONFLICT,
   UNSTABLE_REVALIDATE_RENAME_ERROR,
+  CUSTOM_DOCUMENT_RSC_ERROR,
 } from '../../lib/constants'
 import { isSerializableProps } from '../../lib/is-serializable-props'
 import { GetServerSideProps, GetStaticProps, PreviewData } from '../../types'
@@ -459,6 +460,10 @@ export async function renderToHTML(
     !isSSG &&
     !getServerSideProps
 
+  if (process.env.NEXT_CONCURRENT_FEATURES && typeof Document !== 'function') {
+    throw new Error(CUSTOM_DOCUMENT_RSC_ERROR + ` ${pathname}`)
+  }
+
   for (const methodName of [
     'getStaticProps',
     'getServerSideProps',

test/integration/concurrent-document-component-error/next.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  experimental: {
+    concurrentFeatures: true,
+  },
+}

test/integration/concurrent-document-component-error/pages/_document.js

@@ -0,0 +1,17 @@
+import Document, { Html, Head, Main, NextScript } from 'next/document'
+
+class MyDocument extends Document {
+  render() {
+    return (
+      <Html>
+        <Head />
+        <body>
+          <Main />
+          <NextScript />
+        </body>
+      </Html>
+    )
+  }
+}
+
+export default MyDocument

test/integration/concurrent-document-component-error/test/index.test.js

@@ -0,0 +1,15 @@
+/* eslint-env jest */
+
+import { join } from 'path'
+import { nextBuild } from 'next-test-utils'
+import { CUSTOM_DOCUMENT_RSC_ERROR } from 'next/dist/lib/constants'
+
+jest.setTimeout(1000 * 60)
+const appDir = join(__dirname, '..')
+
+describe('Concurrent Document Component Errors', () => {
+  it('should error when exporting a class component', async () => {
+    const { stderr } = await nextBuild(appDir, [], { stderr: true })
+    expect(stderr).toContain(CUSTOM_DOCUMENT_RSC_ERROR)
+  })
+})