Astrato App runtime
Browser runtime for Astrato Apps. It creates an Astrato SDK client using the app's authorized context. See the runtime reference for the public API.
npm install @astrato-io/app-runtime
Follow the installation instructions for package
access available to your organization. @astrato-io/sdk is an ordinary production dependency
installed by npm; applications importing the SDK directly must use a compatible version.
This runtime requires SDK ^0.6.0. Preview bootstrap and the runtime must resolve to the same
SDK module so they share the established iframe connection.
Create and destroy the runtime
import { createAstratoApp } from '@astrato-io/app-runtime';
const app = await createAstratoApp();
// Use app.client and app.dataBinding with the SDK and visualization packages.
// Release the runtime when the app is unmounted.
app.destroy();
Retain one runtime across charts. Reload after semantic model changes to refresh metadata; query results are not cached by this package.
The package is ESM-only and browser-only. Run it at the origin printed by astrato dev, an
Astrato App preview with an established host connection, or an enabled hosted publication URL.
It cannot bootstrap from a raw Vite origin or server-side rendering.
The factory accepts an optional abort signal, bootstrap timeoutMs, and explicit runtime
selection (publication, local or preview). An explicitly selected preview requires an established host
connection and does not fall back to HTTP bootstrap. Application code supplies no account token,
tenant ID, semantic-layer ID or custom transport; the hosting boundary establishes those values.
Runtime boundaries
Hosted apps use governed direct data-node access. Expired or replaced publication sessions require reload. Preview data access is read-only. Procedure execution and row writeback are available only in local development under the caller's existing permissions; hosted and preview apps reject them. See local write methods.
Publication changes
Hosted publications automatically reload after a confirmed version change, with a per-tab loop
guard. Register onPublicationChanged in createAstratoApp() to save app state before navigation
or return false to defer and call the event's reload() after a user decision. Async callbacks
are awaited; a failed callback or blocked automatic reload falls back to a manual prompt.
The hook can run during bootstrap before the factory resolves. It does not run in local
development, previews or SDK-only apps.
See the hook reference, persistence and confirmation examples for the complete contract, loop guard and package availability. Published versions 0.2.1 and earlier do not include this behavior; existing apps require an updated runtime, rebuild and republish.
Externally hosted apps that authenticate and host themselves, and Workbooks created in the Workbook Editor, do not need this package.