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();

export function App() {
  return (
    
       localStorage.getItem("access_token") ?? ""}
        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.

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;

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

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