`).
```tsx
const renderContent = (_App: AppType, _Component: NextComponentType) => {
const EnhancedApp = _App || App
const EnhancedComponent = _Component || Component
return ctx.err && ErrorDebug ? (
) : (
{renderPageTree(EnhancedApp, EnhancedComponent, {
...props,
router,
})}
)
}
```
Sources: [packages/next/src/server/render.tsx:1351-1369](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/server/render.tsx#L1351-L1369)
The default custom App class exported by Next.js establishes the baseline component rendering behavior by extracting `Component` and `pageProps` from its instance properties and rendering the page component directly.
```tsx
export default class App
extends React.Component<
P & AppProps,
S
> {
static origGetInitialProps = appGetInitialProps
static getInitialProps = appGetInitialProps
render() {
const { Component, pageProps } = this.props as AppProps
return
}
```
Sources: [packages/next/src/pages/_app.tsx:34-45](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/pages/_app.tsx#L34-L45)
> [!WARNING]
> Returning `router` or `Component` properties inside `getInitialProps` from `_app.js` throws an explicit development-time error to prevent corrupting router state and element reconciliation.
```tsx
if (
process.env.__NEXT_DEV_SERVER &&
(props.router || props.Component)
) {
throw new Error(
`'router' and 'Component' can not be returned in getInitialProps from _app.js https://nextjs.org/docs/messages/cant-override-next-props`
)
}
```
Sources: [packages/next/src/server/render.tsx:1315-1322](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/server/render.tsx#L1315-L1322)
## Document Shell and Script Injection
### Document Lifecycle and Initialization
The document serialization pipeline coordinates the custom or built-in `Document` component lifecycle. When rendering pages, the server inspects whether a custom `Document` defines `getInitialProps`. If an edge runtime context is active alongside a customized `Document.getInitialProps`, Next.js throws an error because the Edge Runtime does not support custom document initial props unless a built-in functional document fallback is available.
```tsx
const BuiltinFunctionalDocument: DocumentType | undefined = (
Document as any
)[NEXT_BUILTIN_DOCUMENT]
if (process.env.NEXT_RUNTIME === 'edge' && Document.getInitialProps) {
// In the Edge runtime, `Document.getInitialProps` isn't supported.
// We throw an error here if it's customized.
if (BuiltinFunctionalDocument) {
Document = BuiltinFunctionalDocument
} else {
throw new Error(
'`getInitialProps` in Document component is not supported with the Edge Runtime.'
)
}
}
```
Sources: [packages/next/src/server/render.tsx:1276-1290](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/server/render.tsx#L1276-L1290)
```tsx
const hasDocumentGetInitialProps =
process.env.NEXT_RUNTIME !== 'edge' && !!Document.getInitialProps
```
Sources: [packages/next/src/server/render.tsx:1383-1385](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/server/render.tsx#L1383-L1385)
> [!CAUTION]
> Using `Document.getInitialProps` inside the Edge runtime triggers an immediate execution error, as initial props loading for documents is prohibited in lightweight edge environments.
```tsx
if (process.env.NEXT_RUNTIME === 'edge' && Document.getInitialProps) {
// In the Edge runtime, `Document.getInitialProps` isn't supported.
// We throw an error here if it's customized.
if (BuiltinFunctionalDocument) {
Document = BuiltinFunctionalDocument
} else {
throw new Error(
'`getInitialProps` in Document component is not supported with the Edge Runtime.'
)
}
```
Sources: [packages/next/src/server/render.tsx:1280-1289](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/server/render.tsx#L1280-L1289)
### HtmlContext and Document Component Elements
The document component exposes layout tags (`Html`, `Main`) that consume context via `useHtmlContext`. The `Html` component captures attributes like `lang` and `data-dpl-id` from the deployment identifier while triggering script loader registration items via `handleDocumentScriptLoaderItems`. The `Main` component evaluates to a custom element tag ``, marking the precise insertion boundary where the rendered React component tree gets mounted into the document shell.
```tsx
export function Html(
props: React.DetailedHTMLProps<
React.HtmlHTMLAttributes,
HTMLHtmlElement
>
) {
const {
docComponentsRendered,
locale,
scriptLoader,
deploymentId,
__NEXT_DATA__,
} = useHtmlContext()
docComponentsRendered.Html = true
handleDocumentScriptLoaderItems(scriptLoader, __NEXT_DATA__, props)
return (
)
}
export function Main() {
const { docComponentsRendered } = useHtmlContext()
docComponentsRendered.Main = true
// @ts-ignore
return
}
```
Sources: [packages/next/src/pages/_document.tsx:970-1001](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/pages/_document.tsx#L970-L1001)
### Script Injection and Hydration Tags
Script injection relies on manifest data retrieved via `getDocumentFiles`, which combines shared files (`/_app`) and page-specific files. Polyfill scripts are emitted first with `noModule={true}` and deferred attributes depending on optimized loading flags. Dynamic import chunks and regular page scripts are mapped with cache-busting query strings derived from asset query parameters or immutable chunk paths.
```tsx
function getDocumentFiles(
buildManifest: BuildManifest,
pathname: string
): DocumentFiles {
const sharedFiles: readonly string[] = getPageFiles(buildManifest, '/_app')
const pageFiles: readonly string[] = getPageFiles(buildManifest, pathname)
return {
sharedFiles,
pageFiles,
allFiles: [...new Set([...sharedFiles, ...pageFiles])],
}
}
function getPolyfillScripts(context: HtmlProps, props: OriginProps) {
// polyfills.js has to be rendered as nomodule without async
// It also has to be the first script to load
const {
assetPrefix,
buildManifest,
assetQueryString,
disableOptimizedLoading,
crossOrigin,
} = context
return buildManifest.polyfillFiles
.filter(
(polyfill) => polyfill.endsWith('.js') && !polyfill.endsWith('.module.js')
)
.map((polyfill) => (
))
}
```
Sources: [packages/next/src/pages/_document.tsx:57-98](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/pages/_document.tsx#L57-L98)
```tsx
function getScripts(
context: HtmlProps,
props: OriginProps,
files: DocumentFiles
) {
const {
assetPrefix,
buildManifest,
isDevelopment,
assetQueryString,
mutableAssetQueryString,
disableOptimizedLoading,
crossOrigin,
} = context
const normalScripts = files.allFiles.filter((file) => file.endsWith('.js'))
const lowPriorityScripts = buildManifest.lowPriorityFiles?.filter((file) =>
file.endsWith('.js')
)
const scripts = [...normalScripts, ...lowPriorityScripts].map((file) => {
// static/immutable/chunks/51e975e7b637a580.js should use the immutable id, while
// static/Yj152X97rfGgF7NPcJEZs/_ssgManifest.js should use the deployment id
const query = file.startsWith('static/immutable/chunks')
? assetQueryString
: mutableAssetQueryString
return (
)
})
```
Sources: [packages/next/src/pages/_document.tsx:163-199](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/pages/_document.tsx#L163-L199)
For Turbopack production builds, `getInlineBootstrapScript` seeds the global runtime queue using `getTurbopackChunkGroupBootstrap` before chunk script elements drain the queue.
```tsx
function getInlineBootstrapScript(context: HtmlProps, props: OriginProps) {
const { buildManifest, __NEXT_DATA__, crossOrigin } = context
// Only Turbopack production builds populate these; nothing to inline otherwise.
if (
!buildManifest.pagesChunkGroupBootstrapParams ||
!buildManifest.chunkLoadingGlobal
) {
return null
}
const bootstrap = getTurbopackChunkGroupBootstrap(
buildManifest.pagesChunkGroupBootstrapParams,
buildManifest.chunkLoadingGlobal,
['/_app', __NEXT_DATA__.page]
)
if (!bootstrap) return null
const html = htmlEscapeJsonString(bootstrap)
return (
)
}
```
Sources: [packages/next/src/pages/_document.tsx:136-161](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/pages/_document.tsx#L136-L161)
```typescript
export function getTurbopackChunkGroupBootstrap(
paramsByPage: { [page: string]: object },
chunkLoadingGlobal: string,
pages: readonly string[]
): string | undefined {
const g = JSON.stringify(chunkLoadingGlobal)
const statements = pages
.map((page) => paramsByPage[page])
.filter(Boolean)
.map(
(params) =>
`(globalThis[${g}] || (globalThis[${g}] = [])).push(${JSON.stringify(
params
)});`
)
return statements.length > 0 ? statements.join('\n') : undefined
}
```
Sources: [packages/next/src/server/get-page-files.ts:30-47](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/server/get-page-files.ts#L30-L47)
## Static Page Export Integration
### Pages Export Execution Pipeline
The static export route handler coordinates prerendering for individual pages within the Pages router. When `exportPagesPage` processes a page component, it verifies that the component does not define `getServerSideProps`, throwing an error if server-side props are declared during export. Non-dynamic static pages with `getStaticProps` skip export rendering if build-time exports have already prerendered them, whereas dynamic routes and auto-exported components proceed through the rendering lifecycle.
```typescript
if (components.getServerSideProps) {
throw new Error(`Error for page ${page}: ${SERVER_PROPS_EXPORT_ERROR}`)
}
// for non-dynamic SSG pages we should have already
// prerendered the file
if (!buildExport && components.getStaticProps && !isDynamic) {
return
}
```
Sources: [packages/next/src/export/routes/pages.ts:50-58](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/export/routes/pages.ts#L50-L58)
> [!WARNING]
> Defining `getServerSideProps` on a page during a static export invocation triggers an immediate error, as server-side execution requires a live Node.js origin server.
```typescript
if (components.getServerSideProps) {
throw new Error(`Error for page ${page}: ${SERVER_PROPS_EXPORT_ERROR}`)
}
```
Sources: [packages/next/src/export/routes/pages.ts:50-52](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/export/routes/pages.ts#L50-L52)
Path parameters and search parameters are merged into `searchAndDynamicParams` to satisfy `useRouter().query` requirements. If `optimizeCss` is enabled within render options, `process.env.__NEXT_OPTIMIZE_CSS` is injected as a stringified boolean prior to invoking `lazyRenderPagesPage`.
```typescript
const searchAndDynamicParams = {
...query,
...params,
}
```
Sources: [packages/next/src/export/routes/pages.ts:64-67](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/export/routes/pages.ts#L64-L67)
```typescript
if (renderOpts.optimizeCss) {
process.env.__NEXT_OPTIMIZE_CSS = JSON.stringify(true)
}
```
Sources: [packages/next/src/export/routes/pages.ts:94-96](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/export/routes/pages.ts#L94-L96)
### File Writer Integration and Metadata Handling
Once the render result is obtained, output files are committed to disk via the multi-file writer. If metadata contains page data and the export did not result in a `notFound` status, a companion JSON data file corresponding to `NEXT_DATA_SUFFIX` is appended to the pages data directory.
```typescript
const ssgNotFound = renderResult?.metadata.isNotFound
const html =
renderResult && !renderResult.isNull ? renderResult.toUnchunkedString() : ''
const metadata = renderResult?.metadata || {}
if (metadata.pageData && !ssgNotFound) {
const dataFile = join(
pagesDataDir,
htmlFilename.replace(/\.html$/, NEXT_DATA_SUFFIX)
)
fileWriter.append(dataFile, JSON.stringify(metadata.pageData))
}
```
Sources: [packages/next/src/export/routes/pages.ts:112-125](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/export/routes/pages.ts#L112-L125)
| Metadata Property | Target File Extension | Description |
| :--- | :--- | :--- |
| HTML Content | `.html` | Prerendered page markup string |
| `pageData` | `.json` (`_next/data/...`) | Serialized `getStaticProps` payload |
| `routeCache` | `.meta` | Cached route metadata entries |
Sources: [packages/next/src/export/routes/pages.ts:114-135](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/export/routes/pages.ts#L114-L135)
> [!CAUTION]
> If `getStaticProps` returns `notFound: true`, the exporter skips writing both the HTML markup file and the page data JSON file to disk entirely.
```typescript
if (!ssgNotFound) {
// don't attempt writing to disk if getStaticProps returned not found
fileWriter.append(htmlFilepath, html)
if (routeCache) {
fileWriter.append(
htmlFilepath.replace(/\.html$/, '.meta'),
JSON.stringify({ routeCache })
)
}
}
```
Sources: [packages/next/src/export/routes/pages.ts:127-136](https://github.com/blade47/next.js/blob/d8c1c1b0002db8ccb63b58095f338e8bf423fa99/packages/next/src/export/routes/pages.ts#L127-L136)
## Related
- [App Rendering](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/app-rendering/app-rendering)
- [Client Runtime](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/client-runtime/client-runtime)
## Sitemap
See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.