Skip to main content

Provider for NextJS

info

Any components that will make use of the Evolv AI platform must be wrapped by <EvolvProvider />.

Configuring the <EvolvProvider /> for NextJS applications requires a few more steps. Furthermore, the provider must be included in every page component or within a Custom App or Custom Document.

Configure getServerSideProps()​

NextJS allows you to export a getServerSideProps() loader function from your page component, which must resolve before NextJS will send a response for a page request.

NextJS Documentation for getServerSideProps()

In order to properly hydrate your page with the Evolv variant, getServerSideProps() must also wait for Evolv to initialize. The SDK provides its own loader function, getEvolvServerSideProps(), for incorporating Evolv into your loader function. Using this loader function will inject the data needed by <EvolvProvider /> into the page props.

See also​

Usages​

If your page does not already export its own getServerSideProps() function, you can use the shorter form.

src/pages/index.tsx
import { getEvolvServerSideProps } from '@evolv/nextjs';

const Page = () => {
	// ...
};

export const getServerSideProps = getEvolvServerSideProps(options);

If your page does export its own getServerSideProps() function, use the longer form inside the page's getServerSideProps() function to merge together your page props and Evolv props.

src/pages/index.tsx
import { getEvolvServerSideProps } from '@evolv/nextjs';
import { GetServerSidePropsContext } from 'next';

const Page = () => {
    // ...
};

export async function getServerSideProps(ctx: GetServerSidePropsContext) {
	const { props: evolvProps } = await getEvolvServerSideProps({
		client: options,
		uid,
		remoteContext,
		localContext
	}, ctx);

	return {
		props: {
			...evolvProps
		}
	};
}

Add <EvolvProvider /> to your page​

Adding the <EvolvProvider /> to your NextJS application differs slightly from the normal usage. In order to properly synchronize the variant state on both the server-side and client-side, the <EvolvProvider /> also needs a value for the hydratedState prop. When the result of getEvolvServerSideProps() has been incorporated into getServerSideProps(), pageProps will include values for hydratedState and remoteContext.

note

hydratedState and remoteContext may be available under a subproperty rather than pageProps itself depending on how you merged the result for getEvolvServerSideProps().

src/pages/index.tsx
import { EvolvProvider, EvolvServerSideProps } from '@evolv/nextjs';
import React, { FC } from 'react';

interface Props {}

const Page: FC<Props & EvolvServerSideProps> = (pageProps) => {
	return (
		<EvolvProvider
			options={options}
			uid={uid}
			hydratedState={pageProps.hydratedState}
			remoteContext={pageProps.remoteContext}
		>
			<h1>My NextJS page</h1>
		</EvolvProvider>
	);
}

export default Page;

Coexistence Mode​

You want to use the Evolv NextJS SDK while also including or injecting the Asset Manager (via something like Google Tag Manager) on the same page. In these scenarios you will need to activate Coexistence Mode, which instructs the Asset Manager to use the same instance of the Evolv client as the <EvolvProvider> is using.

To activate Coexistence Mode, add the <CoexistenceMode /> component to the <head> your page. This component must be added to the page so that it loads before the webloader.js script. This will likely need to be done in the Custom Document component.

src/pages/_document.tsx
import { CoexistenceMode } from '@evolv/nextjs';
import { Html, Head, Main, NextScript } from 'next/document';
import React, { FC } from 'react';

const Document: FC = () => {
	return (
		<Html>
			<Head>
				{/* This component must be added to the page so that it loads before the webloader.js script */}
				<CoexistenceMode />
			</Head>
			<body>
				<Main />
				<NextScript />
			</body>
		</Html>
	);
};

export default Document;

See also: