Provider Setup

React UI components usually need:

1. SpaceInvoicesProvider — Initializes the modular SDK runtime
2. EntitiesProvider — Optional active-entity state for multi-entity apps

Full Setup

Provider Setuptypescript

Copy

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { EntitiesProvider } from "./providers/entities-provider";
import { SpaceInvoicesProvider } from "./providers/space-invoices-provider";

const queryClient = new QueryClient();
const activeAccountId = "acc_123"; // Required for multi-account user-token flows

export function App() {
  return (
    
       localStorage.getItem("access_token") ?? ""}
        accountId={activeAccountId}
        basePath="https://eu.spaceinvoices.com"
      >
        
          {/* Your app components */}
          
        
      
    
  );
}

SpaceInvoicesProvider

The SpaceInvoicesProvider initializes the Space Invoices runtime and makes authenticated SDK calls work inside copied components.

For multi-account browser apps using a user token, pass accountId explicitly. API-key, embed, and single-account flows can leave it unset.

Props

Prop	Type	Description
basePath	string	API base URL
accessToken	string | () => string | Promise<string>	Token value or async token resolver
accountId	string | null	Optional active account ID
clientName	string	Optional client header override
onUnauthorized	(response: Response) => void	Optional auth failure handler

Getting the Token

How you get the token depends on your auth setup:

Token Providerstypescript

Copy

// From localStorage
const fromLocalStorage = () => localStorage.getItem("si_token");

// From a cookie
const _fromCookie = () => document.cookie.match(/token=([^;]+)/)?.[1] ?? null;

// From an auth library (e.g., NextAuth)
const _fromSession = (session) => session?.accessToken ?? null;

// For multi-account user-token flows, also pass the active account explicitly.
const activeAccountId = "acc_123";

// Usage in SpaceInvoicesProvider:
"https://eu.spaceinvoices.com"
  accessToken={fromLocalStorage}
  accountId={activeAccountId}
>
  {/* or getAccessToken={fromCookie} */}
  {/* or accessToken={() => fromSession(session) ?? ""} */}
;

Multi-account apps

If your host app lets a user switch between multiple accounts, pass the currently selected account ID into SpaceInvoicesProvider. The React UI package does not infer account context from browser cookies.

EntitiesProvider

The EntitiesProvider manages entity selection for multi-entity apps. If your host app already knows the entity, prefer explicit entityId props and skip this provider.

Using Active Entity

Using Active Entitytypescript

Copy

import { useEntities } from "@/providers/entities-provider";

function _InvoicesPage() {
  const { activeEntity, isLoading } = useEntities();

  if (isLoading) return ;
  if (!activeEntity) return ;

  return id} onRowClick={(inv) => navigate(`/invoices/${inv.id}`)} />;
}

Entity Switching

Entity Switchingtypescript

Copy

import { useEntities } from "@/providers/entities-provider";

function _EntitySelector() {
  const { entities, activeEntity, setActiveEntity } = useEntities();

  return (
    id}
      onValueChange={(id) => {
        const entity = entities.find((e) => e.id === id);
        if (entity) setActiveEntity(entity);
      }}
    >
      {entities.map((entity) => (
        id} value={entity.id}>
          {entity.name}
        
      ))}
    
  );
}

Accessing the SDK Directly

Components use the SDK internally, but for custom code prefer direct modular SDK imports instead of a provider hook:

Direct SDK Accesstypescript

Copy

import { invoices } from "@spaceinvoices/js-sdk";

function _CustomComponent() {
  const handleCustomAction = async () => {
    // Prefer direct modular SDK imports for custom operations
    const result = await invoices.renderPdf(invoiceId);
    downloadBlob(result, "invoice.pdf");
  };

  return Download PDF;
}

Next Steps

• Components — Available components
• Customization — Modify components