@frontera-sdk/core

The Frontera SDK, in one package: the runtime a Frontera app mounts on (the postMessage bridge to the platform host, the app bootstrap and a typed platform client), and a typed client for each area of the platform.

bun add @frontera-sdk/core react react-dom @tanstack/react-query

React and TanStack Query are needed only by the React subpaths (/react, …/hooks, …/provider); a script or a server imports the clients without them. The package is compiled ESM with type declarations: bundlers, Node.js, Bun and edge runtimes use it as it is. Its TypeScript ships beside the build, under src/, and the declaration and source maps lead there: Go to Definition opens the implementation, a stack trace (node --enable-source-maps, bundlers, browsers) names the source line, and a coding agent reading node_modules finds the code and its comments, not only signatures.

Every area, one subpath each

The packages @frontera-sdk/blueprint, @frontera-sdk/agents, @frontera-sdk/chat, @frontera-sdk/knowledge, @frontera-sdk/workflow and @frontera-sdk/functions keep releasing at the same version as re-exports of these subpaths: @frontera-sdk/blueprint/hooks and @frontera-sdk/core/blueprint/hooks are one module, so code on either name works, and both can be used in one App.

The rest of this README covers the app runtime.

import { FronteraAppProvider } from '@frontera-sdk/core/react'

export function Providers({ children }: { children: React.ReactNode }) {
  return <FronteraAppProvider>{children}</FronteraAppProvider>
}

FronteraAppProvider selects one configured transport before connecting: embedded postMessage bridge, same-origin standalone session, or loopback local session broker. All three synthesize the same BridgeInit, so Blueprint and other domain providers do not need transport-specific branches. A missing transport renders a configuration diagnostic immediately.

With renderWhileConnecting, the provider renders the App while the session connects instead of a loading screen, so a static export carries the App itself and paints before the session is ready. Requests wait for the session and go out with its token. Read what the handshake says with useFronteraConnection(), which is { status: 'connecting', client } until the session is ready; before then useFronteraApp() gives only its client.

The App then renders inside a Suspense boundary whose fallback is loading, for as long as it runs: anything that suspends with no boundary of its own (a suspense read, a lazy component, an update outside a transition) shows loading in place of the App. During a static export, a suspense read is left to the browser. That is quiet in Next.js, which recognises the error the read fails with as its own bailout to client rendering; other frameworks still render the boundary in the browser, but report the error.

createFronteraApp() remains the Vite compatibility wrapper. Embedded navigate() synchronizes the platform-owned URL; standalone and local Apps own routing themselves.

Entry points

Embedded application lifecycle

useFronteraApp() exposes active and setUnsavedChanges(dirty). Use active to pause optional visible-only work; an inactive app may remain mounted, with its credentials refreshed. Inactivity does not cancel server-side operations.

Report local draft changes explicitly, and report false only after the draft is saved or deliberately discarded. An app that never reports its state is treated as unknown when the platform is asked to release its session. This API does not implement saving for the app or provide recovery after a browser reload.

The injected app-host bridge reports native push, replacement, traversal and fragment changes. A frontera:host-navigate request carries a requestId and relative app path; the bridge replaces the child location and responds with frontera:navigation-ack using the same ID. It does not add a second child history step for a navigation the host already owns. Both directions validate the expected origin and sender window. Older hosts may ignore the new lifecycle messages; older app-host scripts do not support acknowledged navigation.

Modules

Standalone and local sessions refresh their short-lived App token at 80% of its lifetime. The browser never receives a long-lived workspace key.

Published as TypeScript source. Every consumer is a bundler or tsc, so a build step would emit output the consumer immediately re-transpiles.

License

Apache-2.0. See LICENSE.