@frontera-sdk/blueprint

React hooks for reading Blueprint — the organization-wide model of object types, properties, links and metrics — from inside a Frontera app.

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

import { blueprintProvider } from '@frontera-sdk/blueprint/provider'
import { useObjects } from '@frontera-sdk/blueprint/hooks'
import { createFronteraApp } from '@frontera-sdk/core/create-frontera-app'

createFronteraApp(<App />, { providers: [blueprintProvider] })

function App() {
  const { data, isLoading } = useObjects('Shipment', {
    where: { property: 'deliveryStatus', op: 'eq', value: 'late' },
    pageSize: 20,
  })
  return <p>{isLoading ? 'Loading…' : `${data?.rows.length} late`}</p>
}

Generate workspace types

Inside a Frontera App, run:

frontera blueprint generate-types

This writes src/generated/frontera-blueprint.ts, which augments the SDK from the active Blueprint slice granted to the authenticated workspace. When that file is part of the TypeScript project, object names and returned rows are inferred automatically; filter, projection, and ordering property names are checked as well.

const shipments = useObjects('Shipment', {
  where: { property: 'status', op: 'eq', value: 'delayed' },
  select: ['shipmentId', 'status'],
})

Commit the generated file. Run frontera blueprint generate-types --check in an authenticated CI freshness gate; do not generate during install or build. Apps without a generated registry retain the existing string-keyed behavior, and explicit calls such as useObjects<MyRow>('Shipment') remain supported.

Filter on the server

where compiles into the object set, so the server filters and pages. Filtering the returned array instead narrows one page and misreports every total — a filter matching 8,961 records renders 5 of them under "Page 1 of 1". For the same reason a total is its own query (useAggregate with a count over the same object set), never rows.length.

Page with cursors

The query API uses stable cursor pagination, not page numbers. Omit pageToken for the first request, then pass the response's nextPageToken to the next request:

const rows = useObjects('Shipment', { pageSize: 25, pageToken })
const next = rows.data?.nextPageToken

nextPageToken is present exactly when hasMore. Keep previously received tokens in UI state if the experience needs a Previous button. Changing a filter, projection, or ordering invalidates that history and must return to the first page.

Entry points

| Import | What it is | |---|---| | @frontera-sdk/blueprint/hooks | useObjects, useAggregate, useObjectInstance | | @frontera-sdk/blueprint/provider | the provider createFronteraApp takes | | @frontera-sdk/blueprint/blueprint-client | the client underneath the hooks | | @frontera-sdk/blueprint/types | request and response types, WhereNode |

Every read is scoped by the credential the host handed over at handshake, so an object type the workspace was not granted is absent rather than forbidden.

License

Apache-2.0. See LICENSE.