-
Notifications
You must be signed in to change notification settings - Fork 112
/
Copy pathapi-ssr-docs.js
205 lines (200 loc) · 8.68 KB
/
api-ssr-docs.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
/**
* 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