Getting Started with Stanza in React

Stanza has a React library that provides a react context to use in React applications.

Stanza supports all evergreen browsers.

Install the Browser library

npm install @getstanza/react

Getting Started In React

Create a stanzaConfig.ts using the Stanza UI to get your API key.

import type { StanzaCoreConfig } from '@getstanza/core'
 
export const config: StanzaCoreConfig = {
  url: 'https://hub.dev.getstanza.dev', // the Stanza service url
  environment: 'local', // the environment you want to pull configruations for
  stanzaApiKey: 'valid-api-key', // an API key issued in the Stanza UI
  refreshSeconds: 3, // the refresh rate of the feature statuses
  contextConfigs: [ // groups of features that load together - most likely, your app's pages or routes
    {
      name: 'main',
      features: ['featured', 'search', 'checkout']
    },
    {
      name: 'details',
      features: ['checkout']
    }
  ],
}

The URL and API key can be found in the Stanza UI.

Choosing Features and Contexts

Choosing features and contexts can be a little bit tricky! The things to keep in mind are:

Features can span multiple requests, and multiple UI components. As a developer, you will have to decide what you want to do at each location you use a feature.
When Features are disabled, Stanza stops requests related to that feature from sending. This is good for the infra, but it means if you don't handle this in some way in the UI users will have a very weird time.
You don't have to get a feature label on everything! Start with your most important features, and your least important ones. Other features will default to a medium prioirty.
A context is a group of features found in one page - Stanza will grab them all at once and refresh the cache simultaneously.

Using Stanza in React

Initialize Stanza

Initialize stanza very early in your application lifecycle, probably before ReactDOM.createRoot(). Then create a StanzaProvider that wraps your app.

import React from 'react'
import ReactDOM from 'react-dom/client'
import { createStanzaInstance, StanzaProvider } from '@getstanza/react'
 
const stanzaInstance = createStanzaInstance(config)
 
ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <StanzaProvider instance={stanzaInstance}>
      <App/>
    </StanzaProvider>
  </React.StrictMode>
)

Use Stanza Component to Wrap Features

StanzaComponent is a fast wrapper for features that automatically removes them from the UI and/or adds error messages under stress. The following code leverages StanzaComponent to wrap a "featured products" section of an ecommerce page.

import React from 'react'
import products from '../data/products'
import Products from './Products'
import StanzaComponent from './StanzaComponent'
 
const FeaturedProducts = () => {
  const featuredProducts = products.filter(({ tags }) => tags.includes('featured'))
  return <StanzaComponent contextName="main" featureName="featured" removedFallback={({ message }) => (
    <p style={{ color: 'red' }}>{message}</p>
  )}>
    <h2 className="section-title">Products on Sale Today!</h2>
    <Products products={featuredProducts}/>
  </StanzaComponent>
}
 
export default FeaturedProducts

Use Stanza context directly

For more direct control, you can use StanzaContext directly. The Stanza context gives you actions codes and messages related to features you defined in your configuration. Here it is used in an ecommerce app to remove featured products under load, and display relevant error messages in search.

import { useStanzaContext } from '@getstanza/react'
import { ActionCode } from '@getstanza/browser'
import Layout from '../components/Layout'
import Cart from '../components/Cart'
import CartSummary from '../components/CartSummary'
import Products from '../components/Products'
 
 
const MainPage = () => {
  const stanzaContext = useStanzaContext('main')
 
  return (
    <Layout title="Stanza Swag Shop">
      <div className="page-container">
        <Cart>
          <CartSummary />
          <form style={{ display: 'flex' }}>
            <input style={{ flexBasis: '75%' }} type='text' id='searchProducts' placeholder={stanzaContext?.features.search.message}></input> // placeholder search text swap
          <button style={{ flexBasis: '25%' }}>Search</button>
          </form>
          {stanzaContext?.features.featured.code !== ActionCode.DISABLED_REMOVE.valueOf() && ( // show featured products if not removed
            <>
            <h2>Cool New Swag!</h2>
            <Products />
            </>
          ) }
          {stanzaContext?.features.featured.message} // display status message for featured products
        </Cart>
      </div>
    </Layout>
  )
}
 
export default MainPage

NextJS Overview