206 lines
8.7 KiB
JavaScript
206 lines
8.7 KiB
JavaScript
/**
|
|
* Object containing options defined in `gatsby-config.js`
|
|
* @typedef {object} pluginOptions
|
|
*/
|
|
|
|
/**
|
|
* Replace the default server renderer. This is useful for integration with
|
|
* Redux, css-in-js libraries, etc. that need custom setups for server
|
|
* rendering.
|
|
* @param {object} $0
|
|
* @param {string} $0.pathname The pathname of the page currently being rendered.
|
|
* @param {ReactNode} $0.bodyComponent The React element to be rendered as the page body
|
|
* @param {function} $0.replaceBodyHTMLString Call this with the HTML string
|
|
* you render. **WARNING** if multiple plugins implement this API it's the
|
|
* last plugin that "wins". TODO implement an automated warning against this.
|
|
* @param {function} $0.setHeadComponents Takes an array of components as its
|
|
* first argument which are added to the `headComponents` array which is passed
|
|
* to the `html.js` component.
|
|
* @param {function} $0.setHtmlAttributes Takes an object of props which will
|
|
* spread into the `<html>` component.
|
|
* @param {function} $0.setBodyAttributes Takes an object of props which will
|
|
* spread into the `<body>` component.
|
|
* @param {function} $0.setPreBodyComponents Takes an array of components as its
|
|
* first argument which are added to the `preBodyComponents` array which is passed
|
|
* to the `html.js` component.
|
|
* @param {function} $0.setPostBodyComponents Takes an array of components as its
|
|
* first argument which are added to the `postBodyComponents` array which is passed
|
|
* to the `html.js` component.
|
|
* @param {function} $0.setBodyProps Takes an object of data which
|
|
* is merged with other body props and passed to `html.js` as `bodyProps`.
|
|
* @param {pluginOptions} pluginOptions
|
|
* @example
|
|
* // From gatsby-plugin-glamor
|
|
* const { renderToString } = require("react-dom/server")
|
|
* const inline = require("glamor-inline")
|
|
*
|
|
* exports.replaceRenderer = ({ bodyComponent, replaceBodyHTMLString }) => {
|
|
* const bodyHTML = renderToString(bodyComponent)
|
|
* const inlinedHTML = inline(bodyHTML)
|
|
*
|
|
* replaceBodyHTMLString(inlinedHTML)
|
|
* }
|
|
*/
|
|
exports.replaceRenderer = true
|
|
|
|
/**
|
|
* Called after every page Gatsby server renders while building HTML so you can
|
|
* set head and body components to be rendered in your `html.js`.
|
|
*
|
|
* Gatsby does a two-pass render for HTML. It loops through your pages first
|
|
* rendering only the body and then takes the result body HTML string and
|
|
* passes it as the `body` prop to your `html.js` to complete the render.
|
|
*
|
|
* It's often handy to be able to send custom components to your `html.js`.
|
|
* For example, it's a very common pattern for React.js libraries that
|
|
* support server rendering to pull out data generated during the render to
|
|
* add to your HTML.
|
|
*
|
|
* Using this API over [`replaceRenderer`](#replaceRenderer) is preferable as
|
|
* multiple plugins can implement this API where only one plugin can take
|
|
* over server rendering. However, if your plugin requires taking over server
|
|
* rendering then that's the one to
|
|
* use
|
|
* @param {object} $0
|
|
* @param {string} $0.pathname The pathname of the page currently being rendered.
|
|
* @param {function} $0.setHeadComponents Takes an array of components as its
|
|
* first argument which are added to the `headComponents` array which is passed
|
|
* to the `html.js` component.
|
|
* @param {function} $0.setHtmlAttributes Takes an object of props which will
|
|
* spread into the `<html>` component.
|
|
* @param {function} $0.setBodyAttributes Takes an object of props which will
|
|
* spread into the `<body>` component.
|
|
* @param {function} $0.setPreBodyComponents Takes an array of components as its
|
|
* first argument which are added to the `preBodyComponents` array which is passed
|
|
* to the `html.js` component.
|
|
* @param {function} $0.setPostBodyComponents Takes an array of components as its
|
|
* first argument which are added to the `postBodyComponents` array which is passed
|
|
* to the `html.js` component.
|
|
* @param {function} $0.setBodyProps Takes an object of data which
|
|
* is merged with other body props and passed to `html.js` as `bodyProps`.
|
|
* @param {pluginOptions} pluginOptions
|
|
* @example
|
|
* // Import React so that you can use JSX in HeadComponents
|
|
* const React = require("react")
|
|
*
|
|
* const HtmlAttributes = {
|
|
* lang: "en"
|
|
* }
|
|
*
|
|
* const HeadComponents = [
|
|
* <script key="my-script" src="https://gatsby.dev/my-script" />
|
|
* ]
|
|
*
|
|
* const BodyAttributes = {
|
|
* "data-theme": "dark"
|
|
* }
|
|
*
|
|
* exports.onRenderBody = ({
|
|
* setHeadComponents,
|
|
* setHtmlAttributes,
|
|
* setBodyAttributes
|
|
* }, pluginOptions) => {
|
|
* setHtmlAttributes(HtmlAttributes)
|
|
* setHeadComponents(HeadComponents)
|
|
* setBodyAttributes(BodyAttributes)
|
|
* }
|
|
*/
|
|
exports.onRenderBody = true
|
|
|
|
/**
|
|
* Called after every page Gatsby server renders while building HTML so you can
|
|
* replace head components to be rendered in your `html.js`. This is useful if
|
|
* you need to reorder scripts or styles added by other plugins.
|
|
* @param {object} $0
|
|
* @param {string} $0.pathname The pathname of the page currently being rendered.
|
|
* @param {Array<ReactNode>} $0.getHeadComponents Returns the current `headComponents` array.
|
|
* @param {function} $0.replaceHeadComponents Takes an array of components as its
|
|
* first argument which replace the `headComponents` array which is passed
|
|
* to the `html.js` component. **WARNING** if multiple plugins implement this
|
|
* API it's the last plugin that "wins".
|
|
* @param {Array<ReactNode>} $0.getPreBodyComponents Returns the current `preBodyComponents` array.
|
|
* @param {function} $0.replacePreBodyComponents Takes an array of components as its
|
|
* first argument which replace the `preBodyComponents` array which is passed
|
|
* to the `html.js` component. **WARNING** if multiple plugins implement this
|
|
* API it's the last plugin that "wins".
|
|
* @param {Array<ReactNode>} $0.getPostBodyComponents Returns the current `postBodyComponents` array.
|
|
* @param {function} $0.replacePostBodyComponents Takes an array of components as its
|
|
* first argument which replace the `postBodyComponents` array which is passed
|
|
* to the `html.js` component. **WARNING** if multiple plugins implement this
|
|
* API it's the last plugin that "wins".
|
|
* @param {pluginOptions} pluginOptions
|
|
* @example
|
|
* // Move Typography.js styles to the top of the head section so they're loaded first.
|
|
* exports.onPreRenderHTML = ({ getHeadComponents, replaceHeadComponents }) => {
|
|
* const headComponents = getHeadComponents()
|
|
* headComponents.sort((x, y) => {
|
|
* if (x.key === 'TypographyStyle') {
|
|
* return -1
|
|
* } else if (y.key === 'TypographyStyle') {
|
|
* return 1
|
|
* }
|
|
* return 0
|
|
* })
|
|
* replaceHeadComponents(headComponents)
|
|
* }
|
|
*/
|
|
exports.onPreRenderHTML = true
|
|
|
|
/**
|
|
* Allow a plugin to wrap the page element.
|
|
*
|
|
* This is useful for setting wrapper components around pages that won't get
|
|
* unmounted on page changes. For setting Provider components, use [wrapRootElement](#wrapRootElement).
|
|
*
|
|
* _Note:_
|
|
* There is an equivalent hook in Gatsby's [Browser API](/docs/browser-apis/#wrapPageElement).
|
|
* It is recommended to use both APIs together.
|
|
* For example usage, check out [Using i18n](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-i18n).
|
|
* @param {object} $0
|
|
* @param {ReactNode} $0.element The "Page" React Element built by Gatsby.
|
|
* @param {object} $0.props Props object used by page.
|
|
* @param {pluginOptions} pluginOptions
|
|
* @returns {ReactNode} Wrapped element
|
|
* @example
|
|
* const React = require("react")
|
|
* const Layout = require("./src/components/layout").default
|
|
*
|
|
* exports.wrapPageElement = ({ element, props }) => {
|
|
* // props provide same data to Layout as Page element will get
|
|
* // including location, data, etc - you don't need to pass it
|
|
* return <Layout {...props}>{element}</Layout>
|
|
* }
|
|
*/
|
|
exports.wrapPageElement = true
|
|
|
|
/**
|
|
* Allow a plugin to wrap the root element.
|
|
*
|
|
* This is useful to set up any Provider components that will wrap your application.
|
|
* For setting persistent UI elements around pages use [wrapPageElement](#wrapPageElement).
|
|
*
|
|
* _Note:_
|
|
* There is an equivalent hook in Gatsby's [Browser API](/docs/browser-apis/#wrapRootElement).
|
|
* It is recommended to use both APIs together.
|
|
* For example usage, check out [Using redux](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-redux).
|
|
* @param {object} $0
|
|
* @param {ReactNode} $0.element The "Root" React Element built by Gatsby.
|
|
* @param {pluginOptions} pluginOptions
|
|
* @returns {ReactNode} Wrapped element
|
|
* @example
|
|
* const React = require("react")
|
|
* const { Provider } = require("react-redux")
|
|
*
|
|
* const createStore = require("./src/state/createStore")
|
|
* const store = createStore()
|
|
*
|
|
* exports.wrapRootElement = ({ element }) => {
|
|
* return (
|
|
* <Provider store={store}>
|
|
* {element}
|
|
* </Provider>
|
|
* )
|
|
* }
|
|
*/
|
|
exports.wrapRootElement = true
|