Getting Started with Stanza in NextJS

Stanza has a NextJS library that provides utilities for integrating Stanza into NextJS APIs.

Install the Next library

npm install @getstanza/next

Getting Started In Next

Stanza's NextJS library is a set of Next specific utilities but it is based on the Stanza React library. Please follow the instructions for getting started with React library first.

Using Stanza in Next

Initialize Stanza

Initialize stanza very early in your application lifecycle.

If you are using the App Router (opens in a new tab) then we suggest putting the initialization logic in the root layout (opens in a new tab). However because we need to initialize Stanza on the client side you need to create a wrapper client component (eg. components/WithStanza.tsx)

'use client'
import { createStanzaInstance, StanzaProvider } from '@getstanza/react'
import React from 'react'
import { config } from '../stanzaConfig'
 
const stanzaInstance = createStanzaInstance(config)
 
const WithStanza: React.FC<React.PropsWithChildren> = ({ children }) => {
  return <StanzaProvider instance={stanzaInstance}>
    {children}
  </StanzaProvider>
}
 
export default WithStanza

After creating the WithStanza component we can use it inside of the root layout -> app/layout.tsx

import WithStanza from '../components/WithStanza'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <WithStanza>{ children }</WithStanza>
      </body>
    </html>
  )
}

If you are using Pages Router (opens in a new tab) you can put the Stanza's initialization logic inside the pages/_app.tsx custom app script (docs (opens in a new tab))

import { createStanzaInstance, StanzaProvider } from '@getstanza/react'
import { type AppProps } from 'next/app'
import { config } from '../stanzaConfig'
 
const stanzaInstance = createStanzaInstance(config)
 
function MyApp ({ Component, pageProps }: AppProps) {
  return (
    <StanzaProvider instance={stanzaInstance}>
      <Component {...pageProps} />
    </StanzaProvider>
  )
}

Stanza Next library makes it easier to keep values that need to be shared between client and server code in sync. Currently, we provide utilities to keep enablementNumber consistent between the client-server boundary.

In order to obtain the enablementNumber in the client you need to create an Next API endpoint e.g. pages/api/enablementNumber.ts with the following content:

import { stanzaSession } from '@getstanza/next'
 
const { withStanzaSession } = stanzaSession()
 
export default withStanzaSession(async (req, res) => {
  res.status(200).json(req.stanzaSession.enablementNumber)
})

Then in your Stanza configuration you can retrieve this enablement number by configuring enablementNumberGenerator property:

const config: StanzaCoreConfig = {
  /* rest of your configuration */
  enablementNumberGenerator: async (): Promise<number> => {
    if (typeof window !== 'undefined') {
      const response = await fetch('/api/enablementNumber')
      return response.json()
    }
    return 100
  }
}

React Overview