ArchivaProvider

The ArchivaProvider component sets up the context that allows your client components to fetch and display events. It's a server component that validates your API key is configured and provides the necessary context to client components.

Why It's Needed

React's context system allows the SDK to share authentication state and configuration across all your components without prop drilling. The provider pattern is the standard way to share global state in React applications.

What it does:

  • Validates that ARCHIVA_SECRET_KEY is set (throws a helpful error if not)
  • Provides context to all child components
  • Never exposes your API key to the client (it stays on the server)
  • Configures token endpoint and API base URL

Basic Usage

Wrap your application layout with the ArchivaProvider:

File: app/layout.tsx

import { ArchivaProvider } from '@archiva/archiva-nextjs/react';

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

Important: Always import ArchivaProvider from @archiva/archiva-nextjs/react (not from the root package). This ensures the import is server-safe and won't trigger Next.js React Server Component errors.

Props

PropTypeRequiredDefaultDescription
childrenReactNodeYes-Child components that will have access to Archiva context
apiBaseUrlstringNo'https://api.archiva.app'Base URL for the Archiva API
tokenEndpointstringNo'/api/archiva/frontend-token'Path to your frontend token endpoint
projectIdstringNo-Project ID for scoped tokens (optional)

Configuration Examples

Default Configuration

Uses all defaults:

<ArchivaProvider>
  {children}
</ArchivaProvider>

This assumes:

  • API base URL: https://api.archiva.app
  • Token endpoint: /api/archiva/frontend-token
  • No project scoping

Custom API Base URL

If you're using a custom Archiva instance or staging environment:

<ArchivaProvider apiBaseUrl="https://staging-api.archiva.app">
  {children}
</ArchivaProvider>

Custom Token Endpoint

If you've placed your token endpoint at a different path:

<ArchivaProvider tokenEndpoint="/api/custom/token-route">
  {children}
</ArchivaProvider>

Project-Scoped Tokens

If you want tokens scoped to a specific project:

<ArchivaProvider projectId="proj_123">
  {children}
</ArchivaProvider>

Why project scoping? If you have multiple projects and want to ensure tokens can only access events from a specific project, use project scoping. The project ID will be passed to your token endpoint, which will include it in the token request.

Complete Configuration

Combine all options:

<ArchivaProvider
  apiBaseUrl="https://api.archiva.app"
  tokenEndpoint="/api/archiva/frontend-token"
  projectId="proj_123"
>
  {children}
</ArchivaProvider>

Server Component Requirement

ArchivaProvider must be a server component. This means:

  • ✅ Use it in app/layout.tsx (server component by default)
  • ✅ Import from @archiva/archiva-nextjs/react (server-safe)
  • ❌ Don't add 'use client' directive
  • ❌ Don't use it in client components

Why server component? It needs to access process.env.ARCHIVA_SECRET_KEY, which is only available on the server. It also validates the key exists before rendering, providing helpful error messages if it's missing.

Error Handling

If ARCHIVA_SECRET_KEY is not set or is empty, the provider will throw a helpful error:

ARCHIVA_SECRET_KEY environment variable is not configured. 
Please set it in your .env.local file with a valid value and restart your Next.js dev server.

This error happens at build/render time, so you'll know immediately if your configuration is wrong.

How It Works

  1. Server-side validation: Checks that ARCHIVA_SECRET_KEY exists and is not empty
  2. Context setup: Creates React context with API configuration
  3. Client wrapper: Renders a client component wrapper that manages token lifecycle
  4. Never exposes secrets: The API key stays on the server and is never sent to the client

Requirements

  • Must have ARCHIVA_SECRET_KEY environment variable set
  • Must be used in a server component (like app/layout.tsx)
  • Requires the frontend token route to be set up (see Frontend Token Route)

Next Steps