UNPKG

8.82 kBJavaScriptView Raw
1/**
2 * Object containing options defined in `gatsby-config.js`
3 * @typedef {object} pluginOptions
4 */
5
6/**
7 * Replace the default server renderer. This is useful for integration with
8 * Redux, css-in-js libraries, etc. that need custom setups for server
9 * rendering.
10 * @param {object} $0
11 * @param {string} $0.pathname The pathname of the page currently being rendered.
12 * @param {function} $0.replaceBodyHTMLString Call this with the HTML string
13 * you render. **WARNING** if multiple plugins implement this API it's the
14 * last plugin that "wins". TODO implement an automated warning against this.
15 * @param {function} $0.setHeadComponents Takes an array of components as its
16 * first argument which are added to the `headComponents` array which is passed
17 * to the `html.js` component.
18 * @param {function} $0.setHtmlAttributes Takes an object of props which will
19 * spread into the `<html>` component.
20 * @param {function} $0.setBodyAttributes Takes an object of props which will
21 * spread into the `<body>` component.
22 * @param {function} $0.setPreBodyComponents Takes an array of components as its
23 * first argument which are added to the `preBodyComponents` array which is passed
24 * to the `html.js` component.
25 * @param {function} $0.setPostBodyComponents Takes an array of components as its
26 * first argument which are added to the `postBodyComponents` array which is passed
27 * to the `html.js` component.
28 * @param {function} $0.setBodyProps Takes an object of data which
29 * is merged with other body props and passed to `html.js` as `bodyProps`.
30 * @param {pluginOptions} pluginOptions
31 * @example
32 * // From gatsby-plugin-glamor
33 * const { renderToString } = require("react-dom/server")
34 * const inline = require("glamor-inline")
35 *
36 * exports.replaceRenderer = ({ bodyComponent, replaceBodyHTMLString }) => {
37 * const bodyHTML = renderToString(bodyComponent)
38 * const inlinedHTML = inline(bodyHTML)
39 *
40 * replaceBodyHTMLString(inlinedHTML)
41 * }
42 */
43exports.replaceRenderer = true
44
45/**
46 * Called after every page Gatsby server renders while building HTML so you can
47 * set head and body components to be rendered in your `html.js`.
48 *
49 * Gatsby does a two-pass render for HTML. It loops through your pages first
50 * rendering only the body and then takes the result body HTML string and
51 * passes it as the `body` prop to your `html.js` to complete the render.
52 *
53 * It's often handy to be able to send custom components to your `html.js`.
54 * For example, it's a very common pattern for React.js libraries that
55 * support server rendering to pull out data generated during the render to
56 * add to your HTML.
57 *
58 * Using this API over [`replaceRenderer`](#replaceRenderer) is preferable as
59 * multiple plugins can implement this API where only one plugin can take
60 * over server rendering. However, if your plugin requires taking over server
61 * rendering then that's the one to
62 * use
63 * @param {object} $0
64 * @param {string} $0.pathname The pathname of the page currently being rendered.
65 * @param {function} $0.setHeadComponents Takes an array of components as its
66 * first argument which are added to the `headComponents` array which is passed
67 * to the `html.js` component.
68 * @param {function} $0.setHtmlAttributes Takes an object of props which will
69 * spread into the `<html>` component.
70 * @param {function} $0.setBodyAttributes Takes an object of props which will
71 * spread into the `<body>` component.
72 * @param {function} $0.setPreBodyComponents Takes an array of components as its
73 * first argument which are added to the `preBodyComponents` array which is passed
74 * to the `html.js` component.
75 * @param {function} $0.setPostBodyComponents Takes an array of components as its
76 * first argument which are added to the `postBodyComponents` array which is passed
77 * to the `html.js` component.
78 * @param {function} $0.setBodyProps Takes an object of data which
79 * is merged with other body props and passed to `html.js` as `bodyProps`.
80 * @param {pluginOptions} pluginOptions
81 * @example
82 * const { Helmet } = require("react-helmet")
83 *
84 * exports.onRenderBody = (
85 * { setHeadComponents, setHtmlAttributes, setBodyAttributes },
86 * pluginOptions
87 * ) => {
88 * const helmet = Helmet.renderStatic()
89 * setHtmlAttributes(helmet.htmlAttributes.toComponent())
90 * setBodyAttributes(helmet.bodyAttributes.toComponent())
91 * setHeadComponents([
92 * helmet.title.toComponent(),
93 * helmet.link.toComponent(),
94 * helmet.meta.toComponent(),
95 * helmet.noscript.toComponent(),
96 * helmet.script.toComponent(),
97 * helmet.style.toComponent(),
98 * ])
99 * }
100 */
101exports.onRenderBody = true
102
103/**
104 * Called after every page Gatsby server renders while building HTML so you can
105 * replace head components to be rendered in your `html.js`. This is useful if
106 * you need to reorder scripts or styles added by other plugins.
107 * @param {object} $0
108 * @param {string} $0.pathname The pathname of the page currently being rendered.
109 * @param {Array<ReactNode>} $0.getHeadComponents Returns the current `headComponents` array.
110 * @param {function} $0.replaceHeadComponents Takes an array of components as its
111 * first argument which replace the `headComponents` array which is passed
112 * to the `html.js` component. **WARNING** if multiple plugins implement this
113 * API it's the last plugin that "wins".
114 * @param {Array<ReactNode>} $0.getPreBodyComponents Returns the current `preBodyComponents` array.
115 * @param {function} $0.replacePreBodyComponents Takes an array of components as its
116 * first argument which replace the `preBodyComponents` array which is passed
117 * to the `html.js` component. **WARNING** if multiple plugins implement this
118 * API it's the last plugin that "wins".
119 * @param {Array<ReactNode>} $0.getPostBodyComponents Returns the current `postBodyComponents` array.
120 * @param {function} $0.replacePostBodyComponents Takes an array of components as its
121 * first argument which replace the `postBodyComponents` array which is passed
122 * to the `html.js` component. **WARNING** if multiple plugins implement this
123 * API it's the last plugin that "wins".
124 * @param {pluginOptions} pluginOptions
125 * @example
126 * // Move Typography.js styles to the top of the head section so they're loaded first.
127 * exports.onPreRenderHTML = ({ getHeadComponents, replaceHeadComponents }) => {
128 * const headComponents = getHeadComponents()
129 * headComponents.sort((x, y) => {
130 * if (x.key === 'TypographyStyle') {
131 * return -1
132 * } else if (y.key === 'TypographyStyle') {
133 * return 1
134 * }
135 * return 0
136 * })
137 * replaceHeadComponents(headComponents)
138 * }
139 */
140exports.onPreRenderHTML = true
141
142/**
143 * Allow a plugin to wrap the page element.
144 *
145 * This is useful for setting wrapper components around pages that won't get
146 * unmounted on page changes. For setting Provider components, use [wrapRootElement](#wrapRootElement).
147 *
148 * _Note:_
149 * There is an equivalent hook in Gatsby's [Browser API](/docs/browser-apis/#wrapPageElement).
150 * It is recommended to use both APIs together.
151 * For example usage, check out [Using i18n](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-i18n).
152 * @param {object} $0
153 * @param {ReactNode} $0.element The "Page" React Element built by Gatsby.
154 * @param {object} $0.props Props object used by page.
155 * @param {pluginOptions} pluginOptions
156 * @returns {ReactNode} Wrapped element
157 * @example
158 * const React = require("react")
159 * const Layout = require("./src/components/layout").default
160 *
161 * exports.wrapPageElement = ({ element, props }) => {
162 * // props provide same data to Layout as Page element will get
163 * // including location, data, etc - you don't need to pass it
164 * return <Layout {...props}>{element}</Layout>
165 * }
166 */
167exports.wrapPageElement = true
168
169/**
170 * Allow a plugin to wrap the root element.
171 *
172 * This is useful to set up any Provider components that will wrap your application.
173 * For setting persistent UI elements around pages use [wrapPageElement](#wrapPageElement).
174 *
175 * _Note:_
176 * There is an equivalent hook in Gatsby's [Browser API](/docs/browser-apis/#wrapRootElement).
177 * It is recommended to use both APIs together.
178 * For example usage, check out [Using redux](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-redux).
179 * @param {object} $0
180 * @param {ReactNode} $0.element The "Root" React Element built by Gatsby.
181 * @param {pluginOptions} pluginOptions
182 * @returns {ReactNode} Wrapped element
183 * @example
184 * const React = require("react")
185 * const { Provider } = require("react-redux")
186 *
187 * const createStore = require("./src/state/createStore")
188 * const store = createStore()
189 *
190 * exports.wrapRootElement = ({ element }) => {
191 * return (
192 * <Provider store={store}>
193 * {element}
194 * </Provider>
195 * )
196 * }
197 */
198exports.wrapRootElement = true