Custom Renderers
Renderer SDK
API reference for @xeonr/renderer-sdk — the client library for building custom renderers.
The @xeonr/renderer-sdk package provides everything your renderer needs to communicate with the host.
React hook: useRendererClient
This is the recommended way to use the SDK in React applications.
import { useRendererClient } from '@xeonr/renderer-sdk/react';
const {
// State
connected, // boolean — true after the host sends init
scope, // RendererScope | null
renderingType, // RenderingType | null
theme, // 'light' | 'dark'
token, // string | null — current access token
tokenExpiresAt, // number | null — Unix timestamp (ms)
entrypoint, // 'dashboard' | 'portal' | null
apiBaseUrl, // string | null
config, // RendererConfig | null
apiAdapter, // RendererApiAdapter — pre-configured for API clients
// Methods
openUpload, // (uploadId: string) => void
requestToken, // () => void
close, // () => void
// Advanced
client, // RendererClient instance
} = useRendererClient();The hook automatically:
- Initialises the
RendererClientand manages its lifecycle - Sets
document.documentElement.dataset.themewhen the theme changes - Provides stable, memoised method references
Vanilla JS: RendererClient
For non-React applications, use the client directly:
import { RendererClient } from '@xeonr/renderer-sdk';
const client = new RendererClient();
client.onInit((payload) => {
// Bootstrap your app with payload.scope, payload.theme, etc.
});
client.onThemeChange((theme) => {
// Update your theme
});
client.onTokenRefresh((token, expiresAt) => {
// Store the refreshed token
});
// Request actions from the host
client.openUpload('upl_abc123');
client.close();
// Get a fresh token (async)
const { token, expiresAt } = await client.requestTokenAsync();API adapter
The apiAdapter returned by the hook (or via client.getApiAdapter()) is pre-configured with authentication and automatic token refresh. Pass it to @xeonr/uploads-sdk to make authenticated API calls:
import { getUploadClientWithEnv } from '@xeonr/uploads-sdk/api/base';
import { BucketUploadsService } from '@xeonr/uploads-protocol/uplim/api/v1/uploads_pb';
const client = getUploadClientWithEnv(BucketUploadsService, apiAdapter);
const res = await client.getUpload({
bucketRef: { type: { case: 'bucketId', value: scope.bucketId } },
uploadRef: { type: { case: 'uploadId', value: scope.uploadId } },
});