Rayfin

Rayfin is a backend platform for TypeScript developers. You define your data model as decorated TypeScript classes, and Rayfin generates the database schema, REST and GraphQL APIs, and type-safe clients — then runs them on Microsoft Fabric with authentication, functions, blob storage, and static hosting built in.

import { entity, uuid, text, boolean, authenticated } from '@microsoft/rayfin-core';

@entity()
@authenticated('*', { policy: (claims, item) => claims.sub.eq(item.user_id) })
export class Todo {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @boolean({ default: false }) isCompleted!: boolean;
  @text({ max: 128 }) user_id!: string;
}

That class becomes a table, a GraphQL API, a typed client, and a row-level security policy. One command deploys all of it.

npx rayfin up

These docs cover Rayfin 1.36.2. Every @microsoft/rayfin-* package — SDK, connectors, and CLI — shares that version number. See the Changelog for what changed in 1.36 and how to upgrade.

Get started

If you read one page, read the Quickstart — it goes from an empty terminal to a running app in a few commands.

• Installation — install Node.js 20+ on Windows, macOS, or Linux.
• Quickstart — scaffold a project, sign in, and start the development session with npm run dev.
• Develop locally — what rayfin dev does: it keeps the backend in Fabric and runs your frontend and Functions on your machine.
• Project structure — the rayfin/ folder, rayfin.yml, and how entity classes become a database schema.
• Deploy to Fabric — enable the tenant setting, create a Fabric app, and publish with rayfin up.

How a Fabric app runs

Rayfin runs one way: as a managed Fabric app on Microsoft Fabric.

rayfin up packages your project and provisions it as a Fabric app: Fabric hosts the MSSQL database, a WebService and Data API Builder layer in front of it, your built frontend as static content, and sign-in through Microsoft Entra ID.

Functions are server-side TypeScript you enable in rayfin.yml. They are also how the app reaches anything outside itself:

• They call any HTTPS API with secrets you store with rayfin secret set and read as ctx.Secrets — see Secrets in functions.
• They reach Microsoft resources — Fabric REST APIs, OneLake, Fabric and Azure SQL databases, Azure Storage, Azure AI Foundry, and Azure DevOps — through connections that run as the app's identity (for current Fabric apps, the owner of the Fabric app item). You grant that identity access to each resource.
• Reads and writes to your own Rayfin data from a function still run as the signed-in caller, so your entity permissions keep applying.

Connectors cover the other direction: data that already lives in Fabric. Point one at a Warehouse, SQL database, Lakehouse SQL analytics endpoint, or semantic model and query it from the same client — as typed entities, or with DAX. rayfin connector add configures SQL connectors to run as the app identity, and you can switch one to the signed-in user; semantic models always run as the signed-in user. See Delegated access for which identity each surface uses.

During development, npm run dev runs rayfin dev: it provisions or reuses this same backend in Fabric, applies your schema, and serves the frontend — plus any Functions — from your machine, in place of the Static content node above. There is no backend to run yourself. See Develop locally.

Build your app

• Data — model entities, query and aggregate them, and control who can read each row.
• Auth — sign users in with Fabric SSO, sign in with an Entra token you already hold, or embed the app in your own portal.
• Functions — server-side TypeScript for logic that does not belong in the client, and for calling external services.
• Connectors — read and write data that already exists in Fabric: warehouses, SQL databases, Lakehouse SQL endpoints, and semantic models.
• Storage — upload, serve, and secure files in blob storage. Experimental.
• Hosting — build and serve your frontend from the deployed app, control who can load it, and make views shareable with deep links.
• Deploy — capacity, secrets, environments, deployment pipelines, and troubleshooting.

Using an agent

These docs are built for coding agents as much as for people. Every page has a raw Markdown mirror — append .md to any URL — and the whole corpus is available at /llms-full.txt.

See Rules for coding agents for the constraints an agent needs before it writes Rayfin code.

Reference

• Changelog — what changed in each release, and how to upgrade.
• CLI — every command and flag.
• rayfin.yml — the configuration schema.
• SDK — API reference for every @microsoft/rayfin-* package.
• Known limitations — current constraints and workarounds.