Server-side rendering

Use the JavaScript Server SDK and JavaScript Client SDK together to create a seamless server-side rendered experience.


For a complete example, see the experiment-node-server demo app on GitHub.


Install both the JavaScript Server SDK and JavaScript Client SDK.

1npm install --save @amplitude/experiment-js-client @amplitude/experiment-node-server

1yarn add @amplitude/skylab-js-client @amplitude/skylab-js-server

Initialize the Server SDK

On server startup, you should run initialize the Server SDK. To distinguish from the Client SDK Experiment object, Experiment has aliased the Experiment object from the Server SDK as ExperimentServer here.

1let ExperimentServer;
2if (typeof window === 'undefined') {
3 console.debug('Initializing Server Experiment');
4 ExperimentServer = require('@amplitude/experiment-node-server').Experiment.initialize(
5 'server-IAxMYws9vVQESrrK88aTcToyqMxiiJoR',
6 { debug: true },
7 );
10export { ExperimentServer };

Fetch variants on request

On each request, fetch variants using the server side SDK. The result is a plain JavaScript object mapping feature keys to variant values. You should store the result where your rendering code can access it in both server side and client side contexts.

1const allFlags = await experimentServer.fetch({
2 id: 'userId',
5// store the result where the rendering code can access it
6global.appProps = { flags: allFlags };

Initialize the Client SDK on Render

At the start of your server side render, initialize the Client SDK with the fetched variants. Here you need to instantiate a ExperimentClient that's accessible in the render scope (for example, a React ContextProvider). If you are in the server side context, create a new ExperimentClient every time. If you are in the client side, you should create a new ExperimentClient if one doesn't already exist.

1import { ExperimentClient } from '@amplitude/experiment-js-client';
3let experimentClient;
5const render = (appProps) => {
6const isServerSide = typeof window === 'undefined';
7 if (isServerSide) {
8 console.debug('Initializing Client Experiment');
9 // on the server, we want to create a new ExperimentClient every time
10 experimentClient = new ExperimentClient(
11 'client-IAxMYws9vVQESrrK88aTcToyqMxiiJoR',
12 {
13 initialVariants: appProps['features'],
14 },
15 );
16 } else if (!experiment) {
17 // in the client, we only want to create the ExperimentClient once
18 experimentClient = Experiment.initialize(
19 'client-IAxMYws9vVQESrrK88aTcToyqMxiiJoR',
20 {
21 initialVariants: appProps['features'],
22 },
23 );
24 }
27// be sure to use a provider or store the ExperimentClient so that it is accessible in the render scope

Get variants on render

After the Client SDK is initialized, you can fetch the flag status in any component.

1// experimentClient should be the same ExperimentClient instance that was instantiated in the previous step
Was this page helpful?

Thanks for your feedback!

May 28th, 2024

Need help? Contact Support


Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.