Reference overview
Landing page for the complete Rayfin reference — CLI commands, configuration schema, SDK packages, rules for coding agents, known limitations, deprecations, and troubleshooting.
This section is exhaustive, precise detail rather than task-first guidance — reach for it when you need an exact flag, option, signature, or error message rather than an explanation of how a feature works. If you're learning a concept for the first time, the Data, Auth, or Deploy guides are a better starting point.
In this section
- Changelog — what changed in each release these docs cover, the meaning of the version tags, and step-by-step upgrade instructions.
- CLI — every
rayfincommand, subcommand, and flag. - Configuration — the
rayfin.ymlschema and every environment variable the CLI and runtime read or write. - SDK — API reference for every
@microsoft/rayfin-*package: decorators, client construction, the query API, auth, connectors, and app state. - Rules for coding agents — the condensed do/don't list for generating Rayfin code that works.
- Known limitations — current constraints in service availability, functions, connectors, the data client, DAB, relationships, auth, and schema apply, each with a workaround.
- Deprecations — what recent releases deprecated or removed and what to use instead, plus how to silence deprecation warnings.
- Errors — a symptom → cause → fix index gathered from every troubleshooting section in the guide.
Tip
Check Known limitations before generating entities,
queries, or permission decorators — several common mistakes (missing @text() length,
missing permission decorators, findByPk instead of findById) are constraints, not
bugs, and are documented there with the correct pattern.
Package overview
Every package that ships as part of Rayfin 1.36.2. All of them share one version number — install them at the same exact version.
| Package | Kind | What it does |
|---|---|---|
@microsoft/rayfin-core | SDK | Code-first decorators for data model definition. The CLI reads this metadata to generate Data API Builder configuration. |
@microsoft/rayfin-data | SDK | Data client for querying, mutating, and aggregating entities through the generated GraphQL endpoint. |
@microsoft/rayfin-client | SDK | High-level client entry point composing auth, data, functions, and connectors behind one configured client, plus runtime config loading. |
@microsoft/rayfin-auth | SDK | Session and token management for Rayfin apps. |
@microsoft/rayfin-auth-provider-fabric | SDK | Microsoft Entra sign-in through Fabric SSO, plus direct Entra token sign-in. |
@microsoft/rayfin-embed-host | SDK | Parent-page host that signs an embedded Rayfin app in with your portal's Entra token. |
@microsoft/rayfin-app-state-fabric | SDK | Deep-link application state for apps embedded in the Fabric portal. |
@microsoft/rayfin-functions | SDK | Client-side surface for invoking functions from app code, behind client.functions. |
@microsoft/fabric-user-data-functions | SDK | Function authoring surface: udf.func(), RayfinContext, AudienceType, and the typegen behind types.ts. |
@microsoft/rayfin-storage | SDK | Experimental blob storage client. |
@microsoft/rayfin-connectors | SDK | Typed connector runtime mounted as client.connectors, plus Source and AutoGenerated for connector entities. |
@microsoft/rayfin-connector-fabric-graphql | SDK | GraphQLBackedConnector marker for warehouse, SQL database, and Lakehouse SQL connectors. |
@microsoft/rayfin-connector-fabric-semanticmodel | SDK | Semantic model connector: DAX through executeQuery. |
@microsoft/rayfin-connector-kusto | SDK | KQL database connector for existing Kusto connectors. New ones cannot be added in 1.36. |
@microsoft/rayfin-lib | SDK | Shared HTTP and client utilities used by higher-level Rayfin SDKs. |
@microsoft/rayfin-cli | Tool | Command-line interface: scaffolding, the development loop, deployment, and the rayfin docs command group. |
@microsoft/rayfin-local-dev | Tool | Vite adapter used by rayfin dev: same-origin routing to the backend and local Functions, and local sign-in. |
@microsoft/create-rayfin | Tool | Project scaffolding behind npm create @microsoft/rayfin@latest. |
@microsoft/rayfin-mcp | Tool | Model Context Protocol server exposing Rayfin docs as list_docs, search_docs, get_doc, and discover_packages tools. |
@microsoft/rayfin-docs | Tool | Docs indexing and discovery library behind the CLI and MCP server. Merges installed package docs via the rayfinDocs package.json convention. |
@microsoft/rayfin-guide | Guide | The cross-cutting builder guides that rayfin docs and the MCP server serve offline. |
My rayfin project just failed to deploy with `npx rayfin up` and printed a 400 error whose
message includes "Dialect is required when Data module is enabled". Read
https://rayfin.ai/docs/reference/errors.md and https://rayfin.ai/docs/reference/known-limitations.md
to find the matching entry, then fix my rayfin/rayfin.yml so the data service has an
explicit dialect and redeploy.Testing a Rayfin app
Test Rayfin data and auth logic in Vitest with injectable auth stubs and the todo template's in-memory data seam.
Changelog
What changed in each Rayfin release these docs cover — new features, behavior changes, and step-by-step upgrade instructions, linked to the pages that document them.