SDK
Which @microsoft/rayfin-* package to install for each capability, how they depend on each other, and version notes for the whole family.
The Rayfin SDK is split into small, single-purpose packages rather than one monolithic library. Most applications only install one or two of them directly — the rest arrive as transitive dependencies.
Which package do I need?
| I want to... | Package |
|---|---|
| Define entities, fields, relationships, and permissions in TypeScript | @microsoft/rayfin-core |
| Query and mutate data with a type-safe GraphQL client | @microsoft/rayfin-data — usually via client.data, rarely installed on its own |
| Sign users out and manage sessions | @microsoft/rayfin-auth — usually via client.auth |
| Add Microsoft Fabric SSO | @microsoft/rayfin-auth-provider-fabric |
| One configured client for data, auth, and functions | @microsoft/rayfin-client — RayfinClient / RayfinServerClient |
| Call serverless functions from the client | @microsoft/rayfin-functions — experimental |
| Store and serve files | @microsoft/rayfin-storage |
| Query an existing Fabric warehouse, SQL database, semantic model, or KQL database | @microsoft/rayfin-connectors — experimental runtime kernel |
| Type a Fabric warehouse, SQL database, or Lakehouse SQL analytics endpoint connector | @microsoft/rayfin-connector-fabric-graphql — type-only Category A marker |
| Type and run a Fabric semantic model connector | @microsoft/rayfin-connector-fabric-semanticmodel — DAX marker and runtime |
| Type and run a Fabric KQL Database connector | @microsoft/rayfin-connector-kusto — KQL marker and runtime |
| (internal) shared HTTP client, error types, naming utilities | @microsoft/rayfin-lib |
In practice, most applications install two packages:
npm install @microsoft/rayfin-core @microsoft/rayfin-clientAdd @microsoft/rayfin-auth-provider-fabric when deploying to Fabric with Fabric SSO, and
@microsoft/rayfin-storage or @microsoft/rayfin-functions when you use those services.
@microsoft/rayfin-data, @microsoft/rayfin-auth, and @microsoft/rayfin-lib are pulled
in automatically as dependencies of @microsoft/rayfin-client — install them directly only
if you need their lower-level API without the rest of the client.
How the packages compose
@microsoft/rayfin-core is the odd one out in this graph: every other package is a
runtime client that talks to your deployed backend, while rayfin-core is what you
import in rayfin/data/*.ts to describe your schema at build/deploy time. rayfin-data
depends on it only for the shared PrimaryKeyField type, not for any runtime behavior.
Version notes
rayfin-core,rayfin-client,rayfin-data,rayfin-auth,rayfin-auth-provider-fabric,rayfin-lib, andrayfin-functionsare versioned in lockstep — in the environment this reference was checked against, all seven were at the same1.31.0release. Keep them on matching versions in your own project; mixing versions across this family is untested.- The CLI and tooling packages version independently from the SDK —
@microsoft/rayfin-cliand@microsoft/rayfin-docswere at different version numbers than the SDK family in that same environment. Don't assume a CLI version implies a matching SDK version, or vice versa. @microsoft/rayfin-functionsand@microsoft/rayfin-storageare the two packages still actively evolving — the functions package is explicitly marked experimental, and both are gated behind CLI feature flags in current builds. Expect their APIs to change faster thanrayfin-core,rayfin-client,rayfin-data, andrayfin-auth.- The connector packages ship in lockstep with the CLI, are preview APIs, and need
version-pinned installs. Their npm
latestandpreviewtags can lag the published release, so install the exact version printed by the connector tooling. - When in doubt about the exact signature for the version you have installed, use
rayfin docs get --symbol <name>or the MCP server rather than trusting a cached mental model of the API — see Rules for coding agents.
In this section
@microsoft/rayfin-core— decorators for entities, fields, relationships, and permissions.@microsoft/rayfin-client—RayfinClient/RayfinServerClientconstruction and configuration.@microsoft/rayfin-data— the fluent query and mutation API behindclient.data.@microsoft/rayfin-auth— the auth client behindclient.auth.@microsoft/rayfin-auth-provider-fabric— Fabric brokered SSO.@microsoft/rayfin-functions— typed serverless function calls.@microsoft/rayfin-storage— blob storage client.@microsoft/rayfin-connectors— connector runtime kernel andConnectorsRayfinClientsupport.@microsoft/rayfin-connector-fabric-graphql— type-only marker for Fabric SQL-backed entity connectors.@microsoft/rayfin-connector-fabric-semanticmodel— semantic model marker, runtime, and result helpers.@microsoft/rayfin-connector-kusto— KQL Database marker, runtime, and result helpers.@microsoft/rayfin-lib— shared HTTP client and utilities.
Environment variable interpolation
The ${VAR} and ${VAR:-default} syntax Rayfin supports inside rayfin.yml — usage, .env file location, resolution priority, type coercion, and error handling.
@microsoft/rayfin-core
Complete decorator reference for @microsoft/rayfin-core — entities, field types, relationships, and permissions that generate Data API Builder configuration.