gatsby
Version:
Blazing fast modern site generator for React
210 lines (204 loc) • 9.07 kB
JavaScript
"use strict";
/**
* 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
* @returns {void | Promise<void>}
* @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 context providers, 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 context providers 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 {string} $0.pathname The pathname of the page currently being rendered.
* @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;
//# sourceMappingURL=api-ssr-docs.js.map