Client SDK

EmbeddedAppProvider

The main React provider that wraps your app. It initializes the session manager and handles route synchronization.

import { EmbeddedAppProvider } from "@/embedded-sdk/client";

function App() {
  return (
    <EmbeddedAppProvider appId="your-app-id">
      <YourApp />
    </EmbeddedAppProvider>
  );
}

Props

Prop	Type	Required	Description
appId	string	Yes	Must match the App ID configured in the Gateway
debug	boolean	No	Enables verbose logging for troubleshooting

What it does

• Creates a SessionManager instance
• Requests an initial session token from the Gateway
• Sets up route synchronization (your app’s routes sync with the Gateway’s URL bar)
• Makes the session manager globally available for the middleware

Important

The appId must match exactly what you configured when adding the app to your Gateway. If they don’t match, the handshake will fail.

SessionManager

The class that handles all token management. You usually don’t interact with this directly - the provider and middleware handle it for you.

interface SessionManagerConfig {
  appId: string;
  debug?: boolean;
}

Key Methods

getToken(): Promise<string>

Returns a valid session token. If the current token is expired or expiring soon (within 10 seconds), it automatically requests a new one.

getTokenState()

Returns the current token state:

type TokenState = {
  status: "NO_TOKEN" | "VALID" | "EXPIRED" | "REFRESHING";
  token: string | null;
};

getAppId(): string

Returns the configured app ID.

getParentOrigin(): string

Returns the Gateway URL (from VITE_GATEWAY_URL env var).

useSessionTokenClientMiddleware

A TanStack Start middleware that automatically adds the session token to all server function requests.

import { useSessionTokenClientMiddleware } from "@/embedded-sdk/client";

export const myServerFunction = createServerFn({ method: "GET" })
  .middleware([useSessionTokenClientMiddleware])
  .handler(async () => {
    // Your handler code
  });

How it works

1. Gets the global SessionManager instance (set by EmbeddedAppProvider)
2. Calls getToken() to get a valid token
3. Adds an Authorization: Bearer <token> header to the request

Tip

You should add this middleware to every server function that needs authentication. Check out the starter template for examples.

lazyInitForWorkers

A utility that wraps resource creation to avoid Cloudflare Workers’ global scope restrictions.

import { lazyInitForWorkers } from "@/embedded-sdk/client";
import { createCollection, queryCollectionOptions } from "@tanstack/db";

export const todosCollection = lazyInitForWorkers(() =>
  createCollection(
    queryCollectionOptions({
      queryKey: ["todos"],
      queryFn: async () => fetchTodos(),
      // ... other options
    }),
  ),
);

Why it’s needed

Cloudflare Workers don’t allow certain async operations (like creating TanStack DB collections) to run in the global scope at module load time. This utility defers initialization until the resource is first accessed.

How it works

Returns a Proxy that:

1. Does nothing at module load time
2. Creates the actual resource on first property access
3. Caches the instance for subsequent accesses (singleton pattern)