Provider

The BoxpressdProvider is the foundation of every Boxpressd Sites SDK application. It establishes authentication, resolves the business context associated with your API key, provides theme configuration, and enables all Boxpressd components and data APIs throughout your application. Every application using the SDK should wrap its component tree with a single provider instance.

Basic Usage

At minimum, provide your Boxpressd API key:

import { BoxpressdProvider } from "@boxpressd/sites-sdk"

export default function App() {
  return (
    <BoxpressdProvider
      apiKey={process.env.NEXT_PUBLIC_BOXPRESSD_API_KEY!}
    >
      {children}
    </BoxpressdProvider>
  )
}

The provider will automatically:

Authenticate with Boxpressd
Resolve the business context
Determine the business type
Configure data access
Enable SDK components and hooks

Environment Variables

Store your API key in an environment variable rather than hardcoding it in your application.

NEXT_PUBLIC_BOXPRESSD_API_KEY=your_api_key

VITE_BOXPRESSD_API_KEY=your_api_key

How Business Context Resolution Works

When the provider initializes, the SDK automatically determines which business should be loaded. For example:

{
  businessType: "venue",
  businessId: "12345"
}

{
  businessType: "brand",
  businessId: "67890"
}

This process happens automatically and does not require any additional configuration. Because the business context is derived from the API key, developers do not need to manually specify:

Venue IDs
Brand IDs
Business IDs
Custom API endpoints

Provider Placement

The provider should typically be mounted once near the root of your application.

Next.js App Router

import { BoxpressdProvider } from "@boxpressd/sites-sdk"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <BoxpressdProvider
          apiKey={process.env.NEXT_PUBLIC_BOXPRESSD_API_KEY!}
        >
          {children}
        </BoxpressdProvider>
      </body>
    </html>
  )
}

React

import ReactDOM from "react-dom/client"
import { BoxpressdProvider } from "@boxpressd/sites-sdk"

ReactDOM.createRoot(document.getElementById("root")!).render(
  <BoxpressdProvider
    apiKey={import.meta.env.VITE_BOXPRESSD_API_KEY}
  >
    <App />
  </BoxpressdProvider>
)

Custom API Endpoint

By default, the SDK connects to the production Boxpressd API.

https://api.boxpressd.io

In development or testing environments, you may provide a custom API base URL.

<BoxpressdProvider
  apiKey={process.env.NEXT_PUBLIC_BOXPRESSD_API_KEY!}
  apiBaseUrl="http://localhost:3000"
>
  {children}
</BoxpressdProvider>

Theme Configuration

The provider supports global theme customization.

<BoxpressdProvider
  apiKey={process.env.NEXT_PUBLIC_BOXPRESSD_API_KEY!}
  theme={{
    primaryColor: "#8B5E3C",
    borderRadius: "12px"
  }}
>
  {children}
</BoxpressdProvider>

Theme values are merged with the SDK defaults. This allows you to customize Boxpressd components while maintaining a consistent user experience.

Theme Example

<BoxpressdProvider
  apiKey={process.env.NEXT_PUBLIC_BOXPRESSD_API_KEY!}
  theme={{
    primaryColor: "#b8894f",
    secondaryColor: "#2a2a2a",
    borderRadius: "16px"
  }}
>
  {children}
</BoxpressdProvider>

CSS Variable Overrides

In addition to provider-level theme options, all Boxpressd components expose CSS variables prefixed with:

--bxp-*

Example:

:root {
  --bxp-primary: #b8894f;
  --bxp-border-radius: 16px;
}

This allows SDK components to seamlessly match your site’s existing design system.

Using SDK Components

Once the provider is configured, all Boxpressd components can access the resolved business context automatically.

import { BoxpressdEventList } from "@boxpressd/sites-sdk/events"

export default function EventsPage() {
  return (
    <BoxpressdEventList
      status="upcoming"
      limit={5}
    />
  )
}

No business identifiers are required. The component automatically loads data for the business associated with the configured API key.

Best Practices

Use a Single Provider

Most websites should only use one provider instance.

<BoxpressdProvider apiKey={apiKey}>
  {children}
</BoxpressdProvider>

Store Keys in Environment Variables

Avoid hardcoding API keys directly into source code.

apiKey={process.env.NEXT_PUBLIC_BOXPRESSD_API_KEY}

Configure Theme Globally

Apply theme settings at the provider level instead of styling individual components whenever possible.

Troubleshooting

Components Show No Data

Verify:

The API key is valid
The provider is mounted correctly
The business contains published content
The environment variable is available at runtime

Authentication Errors

Verify:

The API key has not been revoked
The API key belongs to the expected business
The correct environment variable is being used

Theme Changes Not Appearing

Verify:

The provider is wrapping the component tree
CSS variable overrides are loaded after SDK styles
Theme values are valid CSS values

Next Steps

Now that the provider is configured, continue to:

Business Context
Business Types
Theming
Components Overview

These guides explain how business data is resolved and how to build rich Boxpressd-powered experiences.

Getting started

Core concepts

Components

Data fetching

Examples

Basic Usage

Environment Variables

How Business Context Resolution Works

Provider Placement

Next.js App Router

React

Custom API Endpoint

Theme Configuration

Theme Example

CSS Variable Overrides

Using SDK Components

Best Practices

Use a Single Provider

Store Keys in Environment Variables

Configure Theme Globally

Troubleshooting

Components Show No Data

Authentication Errors

Theme Changes Not Appearing

Next Steps

​Basic Usage

​Environment Variables

​How Business Context Resolution Works

​Provider Placement

​Next.js App Router

​React

​Custom API Endpoint

​Theme Configuration

​Theme Example

​CSS Variable Overrides

​Using SDK Components

​Best Practices

​Use a Single Provider

​Store Keys in Environment Variables

​Configure Theme Globally

​Troubleshooting

​Components Show No Data

​Authentication Errors

​Theme Changes Not Appearing

​Next Steps

Basic Usage

Environment Variables

How Business Context Resolution Works

Provider Placement

Next.js App Router

React

Custom API Endpoint

Theme Configuration

Theme Example

CSS Variable Overrides

Using SDK Components

Best Practices

Use a Single Provider

Store Keys in Environment Variables

Configure Theme Globally

Troubleshooting

Components Show No Data

Authentication Errors

Theme Changes Not Appearing

Next Steps