Arc

As with the backend, you can mix and match from the features you want to use. But there is a convenience wrapper that will help you configure it all in the form of a custom component that provides the ArcContext and configures other Arc contexts in one go.

However, if you’re looking to use some of the microservice capabilities, you will have to use the ArcContext to provide the name of the currently running microservice. Internally, Arc uses this information to add the correct headers / query string parameters to distinguish one microservice from the other in a composition with a single ingress in front of it.

To add Arc, you simply add the following to your application:

export const App = () => {
    return (
        <Arc>
            {/* Your application */}
        </Arc>
    );
};

Configuration Options

The <Arc /> component provides centralized configuration for all commands and queries in your application. These settings apply cross-cuttingly to all operations, eliminating the need to configure individual commands or queries.

Option	Type	Purpose
microservice	String	Name of the microservice, which will add necessary HTTP headers on Commands and Queries
development	Boolean	Whether or not we’re running in development, defaults to false
origin	String	Url for where the APIs are located, defaults to empty string and makes them relative to the documents location
basePath	String	Base path for the application
apiBasePath	String	Base path prepended to all Command and Query requests
httpHeadersCallback	Function	Optional callback function that returns additional HTTP headers to include with all commands, queries, and identity requests (e.g., for including cookies or authentication tokens)
eventSourceFactory	(url: string) => EventSource	Optional factory for creating the EventSource instances used by SSE observable query connections. Falls back to the global EventSource constructor when not set — see Custom EventSource Factory
queryTransportMethod	QueryTransportMethod	Transport used by observable queries (ServerSentEvents or WebSocket)
queryDirectMode	Boolean	Whether observable queries bypass the central hub and connect directly per-query
queryConnectionCount	Number	Number of observable query hub connection slots
observableQueryTransferMode	ObservableQueryTransferMode	Transfer mode used by useChangeStream
queryCacheRetentionMs	Number	How long (ms) to keep query data in cache after the last subscriber unmounts — defaults to 30000
observableQueryDiagnostics	IObservableQueryDiagnostics	Live diagnostics stream for query cache, transport, and ownership state

Example:

export const App = () => {
    return (
        <Arc apiBasePath="/some/location">
            {/* Your application */}
        </Arc>
    );
};

Microservice Support

In microservice architectures, multiple services often share a single ingress point (e.g., an API gateway or reverse proxy). The microservice property enables the Arc to route requests to the correct backend service automatically.

How It Works

When you specify a microservice name, the Arc adds this information to all HTTP requests (via headers or query parameters), allowing the ingress to route requests appropriately:

export const App = () => {
    return (
        <Arc microservice="user-service">
            {/* Your application */}
        </Arc>
    );
};

All commands and queries within this application will automatically include the microservice identifier, ensuring they reach the correct backend service.

Development Configuration

For local development, you can use environment variables to dynamically configure the microservice and API paths:

export const App = () => {
    const microserviceName = import.meta.env.VITE_MICROSERVICE_NAME || 'user-service';
    const apiBasePath = import.meta.env.VITE_API_BASE_PATH || '/api';
    const isDevelopment = import.meta.env.DEV;

    return (
        <Arc
            microservice={microserviceName}
            apiBasePath={apiBasePath}
            development={isDevelopment}>
            {/* Your application */}
        </Arc>
    );
};

.env.development example:

VITE_MICROSERVICE_NAME=user-service
VITE_API_BASE_PATH=/api

.env.production example:

VITE_MICROSERVICE_NAME=user-service
VITE_API_BASE_PATH=/api/v1

This approach allows you to:

• Run different microservices locally with different configurations
• Switch between local development and remote APIs
• Configure different API paths for different environments
• Test microservice routing without modifying code

Multiple Microservices in One Frontend

If your frontend application needs to communicate with multiple microservices, you can override the microservice configuration for specific sections of your application using nested <Arc /> components:

export const App = () => {
    return (
        <Arc microservice="main-service" apiBasePath="/api">
            <MainContent />

            {/* This section communicates with a different microservice */}
            <Arc microservice="reporting-service">
                <ReportingDashboard />
            </Arc>
        </Arc>
    );
};

Query Configuration

Query-related Arc configuration (transport, direct mode, connection count, transfer mode, and headers) is documented in Queries Configuration.

Observable Query Diagnostics

Arc exposes a diagnostics service through ArcContext.observableQueryDiagnostics for tooling and internal dashboards. The service provides both a snapshot API and a live observable stream for the current query cache, transport, and ownership state.

See Observable Query Diagnostics for usage examples.

HTTP Headers Callback

The httpHeadersCallback property allows you to provide additional HTTP headers that will be automatically included with all HTTP requests made by commands, queries, and identity operations. This is particularly useful for including authentication cookies, authorization tokens, or other dynamic headers.

export const App = () => {
    const getHeaders = () => {
        return {
            'X-Custom-Header': 'custom-value',
            'Authorization': `Bearer ${getAuthToken()}`,
            // Include cookies or other dynamic headers
        };
    };

    return (
        <Arc
            apiBasePath="/api"
            httpHeadersCallback={getHeaders}>
            {/* Your application */}
        </Arc>
    );
};

The callback function should return a HeadersInit object (compatible with the Fetch API headers) that contains the additional headers to include with each request.

Reconnecting Queries

When authentication state changes at runtime — for example when a user logs in or logs out — the existing WebSocket or Server-Sent Events connections may no longer carry the correct credentials. The reconnectQueries() method on the Arc context tears down all active observable query subscriptions, disposes the shared transport connections, and signals every useObservableQuery hook to re-subscribe through fresh connections that pick up the current cookies and headers.

Accessing reconnectQueries

Use useContext(ArcContext) inside any component rendered within <Arc>:

import { useContext } from 'react';
import { ArcContext } from '@cratis/arc.react';

export const LoginButton = () => {
    const arc = useContext(ArcContext);

    const handleLogin = () => {
        // Set authentication cookie or token first
        document.cookie = 'auth-token=abc123; path=/; SameSite=Lax';

        // Then reconnect queries so new connections carry the credential
        arc.reconnectQueries?.();
    };

    return <button onClick={handleLogin}>Log in</button>;
};

Login and logout flow

A typical authentication transition follows this pattern:

1. Login: Set the authentication cookie, then call reconnectQueries(). New transport connections are established with the cookie attached, and the identity provider picks up the authenticated user on refresh.
2. Logout: Call identity.clearIdentity() to reset the client-side identity state and remove the identity cookie, then call reconnectQueries() so queries reconnect as anonymous.

import { useContext } from 'react';
import { ArcContext } from '@cratis/arc.react';
import { useIdentity } from '@cratis/arc.react/identity';

export const AuthControls = () => {
    const arc = useContext(ArcContext);
    const identity = useIdentity();

    const login = () => {
        // Set your auth cookie
        document.cookie = 'auth=...; path=/; SameSite=Lax';
        arc.reconnectQueries?.();
    };

    const logout = () => {
        // Clear cookie
        document.cookie = 'auth=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT';
        // Clear client-side identity
        identity.clearIdentity();
        // Reconnect queries as anonymous
        arc.reconnectQueries?.();
    };

    return (
        <div>
            {identity.isSet
                ? <button onClick={logout}>Log out</button>
                : <button onClick={login}>Log in</button>}
        </div>
    );
};

What happens internally

Calling reconnectQueries() performs three steps in order:

1. Tear down subscriptions — Every cached query entry has its subscription callback torn down without evicting the cache entry. This allows hooks to detect the unsubscribed state and re-subscribe.
2. Reset the shared multiplexer — The module-level multiplexer singleton (WebSocket or SSE) is disposed, so the next subscription creates a fresh transport connection.
3. Bump the query version — An internal version counter increments, which is included in the dependency array of every useObservableQuery effect. React re-runs the effects, each hook re-subscribes, and new connections are established with the current credentials.