diff --git a/packages/next/README.md b/packages/next/README.md index 64c2b9f3..3b1b6c84 100644 --- a/packages/next/README.md +++ b/packages/next/README.md @@ -1122,11 +1122,39 @@ export default class MyDocument extends Document { All of ``, `
` and `` are required for page to be properly rendered. +__Note: React-components outside of `
` will not be initialised by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the `App` component instead.__ + The `ctx` object is equivalent to the one received in all [`getInitialProps`](#fetching-data-and-component-lifecycle) hooks, with one addition: - `renderPage` (`Function`) a callback that executes the actual React rendering logic (synchronously). It's useful to decorate this function in order to support server-rendering wrappers like Aphrodite's [`renderStatic`](https://github.com/Khan/aphrodite#server-side-rendering) -__Note: React-components outside of `
` will not be initialised by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the `App` component instead.__ +#### Customizing `renderPage` +🚧 It should be noted that the only reason you should be customizing `renderPage` is for usage with css-in-js libraries +that need to wrap the application to properly work with server-rendering. 🚧 + +- It takes as argument an options object for further customization + +```js +import Document from 'next/document' + +export default MyDocument extends Document { + static async getInitialProps(ctx) { + const originalRenderPage = ctx.renderPage + + ctx.renderPage = () => originalRenderPage({ + // useful for wrapping the whole react tree + enhanceApp: App => App, + // userful for wrapping in a per-page basis + enhanceComponent: Component => Component + }) + + // Run the parent `getInitialProps` using `ctx` that now includes our custom `renderPage` + const initialProps = await Document.getInitialProps(ctx) + + return initialProps + } +} +``` ### Custom error handling