Commit 616c3d7a authored by Kenneth Luján Rosas's avatar Kenneth Luján Rosas Committed by Tim Neutkens

docs(readme): add documentation for `renderPage` customization on _document.js (#5723)

Per @timneutkens suggestion [here](https://github.com/zeit/next.js/pull/5631#issuecomment-440588455) I went ahead and gave a shot at trying to document `renderPage` usage.

This PR:
- Documents `renderPage` legacy and current usage.
parent a996fba0
...@@ -1122,11 +1122,39 @@ export default class MyDocument extends Document { ...@@ -1122,11 +1122,39 @@ export default class MyDocument extends Document {
All of `<Head />`, `<Main />` and `<NextScript />` are required for page to be properly rendered. All of `<Head />`, `<Main />` and `<NextScript />` are required for page to be properly rendered.
__Note: React-components outside of `<Main />` 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: 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) - `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 `<Main />` 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 ### Custom error handling
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment