v28
Addons
Guides
Server Side Rendering
Some projects require you to render your application on the server. There are different reasons to do this, like search engine optimizations, general optimizations and even browser support. What this means for state management is that you want to expose a version of your state on the server and render the components with that state. But that is not all, you also want to hydrate the changed state and pass it to the client with the HTML so that it can rehydrate and make sure that the initial render of the client is the same as coming from the server.
Preparing the project
When doing server-side rendering the configuration of your application will be shared by the client and the server. That means you need to structure your app to make that possible. There is really not much you need to do.
overmind/index.ts
1
import { state } from './state'
2
3
export const config = {
4
state
5
}
Copied!
index.ts
1
import { createOvermind } from 'overmind'
2
import { config } from './overmind'
3
4
const overmind = createOvermind(config)
Copied!
Here we only export the configuration from the main Overmind file. The instantiation rather happens where we prepare the application on the client side. That means we can now safely import the configuration also on the server.
Preparing effects
The effects will also be shared with the server. Typically this is not an issue, but you should be careful about creating effects that run logic when they are defined. You might also consider lazy-loading effects so that you avoid loading them on the server at all. You can read more about that in EFFECTS.
Rendering on the server
When you render your application on the server you will have to create an instance of Overmind designed for running on the server. On this instance you can change the state and provide it to your components for rendering. When the components have rendered you can hydrate the changes and pass them along to the client so that you can rehydrate.
Overmind does not hydrate the actual state, but the mutations you performed. That means it minimizes the payload passed over the wire.
The following shows a very simple example using an EXPRESS middleware to return a server side rendered version of your app.
server/routePosts.ts
1
import { createOvermindSSR } from 'overmind'
2
import { config } from '../client/overmind'
3
import db from './db'
4
5
export default async (req, res) => {
6
const overmind = createOvermindSSR(config)
7
8
overmind.state.currentPage = 'posts'
9
overmind.state.posts = await db.getPosts()
10
11
const html = renderToString(
12
// Whatever implementation your view layer provides
13
)
14
15
res.send(`
16
<html>
17
<body>
18
<div id="app">${html}</div>
19
<script>
20
window.__OVERMIND_MUTATIONS = ${JSON.stringify(overmind.hydrate())}
21
</script>
22
<script src="/scripts/app.js"></script>
23
</body>
24
</html>
25
`)
26
}
Copied!
Rehydrate on the client
On the client you just want to make sure that your Overmind instance rehydrates the mutations performed on the server so that when the client renders, it does so with the same state. The onInitializeOvermind hook of Overmind is the perfect spot to do this.
overmind/actions.ts
1
import { rehydrate } from 'overmind'
2
3
export const onInitializeOvermind = ({ state }) => {
4
const mutations = window.__OVERMIND_MUTATIONS
5
6
rehydrate(state, mutations)
7
}
Copied!
If you are using state first routing, make sure you prevent the router from firing off the initial route, as this is not needed.
OnInitializeOvermind
The
onInitializeOvermind action does not run on the server. The reason is that it is considered a side effect you might not want to run, so we do not force it. If you do want to run an action as Overmind fires up both on the client and the server you can rather call it manually:overmind/actions.js
1
export const onInitializeOvermind = () => {
2
// Whatever...
3
}
Copied!
client/index.js
1
import { createOvermind } from 'overmind'
2
import { config } from './overmind'
3
4
const overmind = createOvermind(config)
5
overmind.actions.onInitializeOvermind()
Copied!
server/index.js
1
import { createOvermindSSR } from 'overmind'
2
import { config } from '../client/overmind'
3
4
export default async (req, res) => {
5
const overmind = createOvermindSSR(config)
6
await overmind.actions.onInitializeOvermind()
7
8
const html = renderToString(
9
// Whatever implementation your view layer provides
10
)
11
12
res.send(`
13
<html>
14
<body>
15
<div id="app">${html}</div>
16
<script>
17
window.__OVERMIND_MUTATIONS = ${JSON.stringify(overmind.hydrate())}
18
</script>
19
<script src="/scripts/app.js"></script>
20
</body>
21
</html>
22
`)
23
}
Copied!
Next.js
The idea behind setting up overmind in
next.js is the same as a standard express server but we have a lot of help from next to get us going.Let's start by adding a
_document.js and this is where we will initialize the SSR version of Overmind:src/_document.js
1
import App from "next/app";
2
import { createOvermind, createOvermindSSR, rehydrate } from "overmind";
3
import { Provider } from "overmind-react";
4
import { config } from "../overmind";
5
6
export default class MyApp extends App {
7
// CLIENT: On initial route
8
// SERVER: On initial route
9
constructor(props) {
10
super(props);
11
12
const mutations = props.pageProps.mutations || [];
13
14
if (typeof window !== "undefined") {
15
// On the client we just instantiate the Overmind instance and run
16
// the "changePage" action
17
this.overmind = createOvermind(config);
18
this.overmind.actions.changePage(mutations);
19
} else {
20
// On the server we rehydrate the mutations to an SSR instance of Overmind,
21
// as we do not want to run any additional logic here
22
this.overmind = createOvermindSSR(config);
23
rehydrate(this.overmind.state, mutations);
24
}
25
}
26
// CLIENT: After initial route, on page change
27
// SERVER: never
28
componentDidUpdate() {
29
// This runs whenever the client routes to a new page
30
this.overmind.actions.changePage(this.props.pageProps.mutations || []);
31
}
32
render() {
33
const { Component, pageProps } = this.props;
34
return (
35
<Provider value={this.overmind}>
36
<Component {...pageProps} />
37
</Provider>
38
);
39
}
40
}
41
Copied!
And then let's create a standard
Overmind instance:1
import { rehydrate } from "overmind";
2
import { createHook } from "overmind-react";
3
4
export const config = {
5
state: {},
6
actions: {
7
add: {
8
changePage({ state }, mutations) {
9
rehydrate(state, mutations || []);
10
}
11
}
12
};
13
14
export const useOvermind = createHook();
15
Copied!
And you are all set to get going with
overmind and next.js. You can also take a look at this example in the next.js examples directory if you need some help.Gatsby
When it comes to Gatsby we need to prepare Overmind for static extraction and the idea is about the same.
We need first to wrap our whole app in the Overmind provider and we can do that in
gatsby-browser.js:1
import React from "react"
2
import { createOvermind } from "overmind"
3
import { Provider } from "overmind-react"
4
import { config } from "./src/overmind"
5
6
const overmind = createOvermind(config);
7
8
export const wrapPageElement = ({ element }) => (
9
<Provider value={createOvermind(config)}>
10
{element}
11
</Provider>
12
)
13
Copied!
After this is done we can do the same thing for the server render and add that code in the
gatsby-ssr.js file:1
import React from "react"
2
import { Provider } from "overmind-react"
3
import { createOvermindSSR } from "overmind"
4
import { ThemeProvider as ChakraProvider } from "@chakra-ui/core"
5
import { theme } from "@chakra-ui/core"
6
import { config } from "./src/overmind"
7
8
const overmind = createOvermindSSR(config)
9
10
export const wrapPageElement = ({ element }) => (
11
<Provider value={createOvermind(config)}>
12
{element}
13
</Provider>
14
)
15
Copied!
As you can see the only difference we have here is that we createOvermindSSR in the
gatsby-ssr.jsLast modified 8mo ago