Skip to main content
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

​
How Business Context Resolution Works

When the provider initializes, the SDK automatically determines which business should be loaded. For example: 
{
  businessType: "venue",
  businessId: "12345"
}
or 
{
  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.