Quickstart
Scaffold a Rayfin project, sign in to Fabric, run the local development loop, and deploy the app with rayfin up.
Create a Rayfin app, run it against a managed Fabric backend, and publish the static frontend. You need Node.js 20+ and a Fabric account.
Create a new Rayfin app named my-app with `npm create @microsoft/rayfin@latest my-app`. Install dependencies, run `npx rayfin login`, start the development loop with `npm run dev`, and report the local frontend URL. Then deploy the static build with `npx rayfin up` and confirm the live hosting URL with `npx rayfin up status`.Tip
Prefer a desktop app to a terminal? Fabricator is a Copilot harness that helps you build Rayfin apps. It creates the project, deploys it to Fabric, and lets you build the app by chatting with GitHub Copilot while a live preview updates. It runs on Windows and on macOS (Apple Silicon). Fabricator is a free, open-source community project, not a Microsoft product.
1. Scaffold a project
npm create @microsoft/rayfin@latest my-app
cd my-app
npm installThe project name is positional. The CLI prompts for a template. Bundled templates in Rayfin 1.36 include:
| Template | Use it when |
|---|---|
blankapp | You want the default starter. In Rayfin 1.36, this scaffolds the Universal App workspace with capability packs. Changed in 1.36 |
dataapp | You are starting from the Fabric analytics app template. |
todoapp | You want a data-enabled todo CRUD app with per-user access rules. |
gettingstartedauth | You want a Fabric-authenticated starter with getting-started UI. |
universal-app is hidden from the template list but accepted by name in 1.36; use blankapp for the CLI-facing default.
2. Sign in
npx rayfin loginThe command opens a browser for Microsoft Entra ID sign-in. Use --encryption-fallback-enabled only in development environments where the OS keychain is unavailable.
3. Run the development loop
npm run devSince Rayfin 1.35, every bundled template's npm run dev runs rayfin dev.
rayfin dev provisions or reuses the Fabric AppBackend, applies runtime settings and schema, writes RAYFIN_PUBLIC_* values to rayfin/.env and .env.local, then starts dev:frontend and local Functions when enabled. It does not publish static content.
4. Deploy the app
npx rayfin up
npx rayfin up statusrayfin up builds and deploys the production frontend, syncs rayfin.yml, applies schema changes, deploys Functions when enabled, and records deployment metadata in rayfin/.deployments.json and rayfin/.env. rayfin up status prints the hosting URL.
Make your first data change
In a data-enabled template, entities live under rayfin/data/ or the configured data service path. Add a field:
import { entity, authenticated, uuid, text, date } from '@microsoft/rayfin-core';
@entity()
@authenticated('*')
export class Timestamp {
@uuid() id!: string;
@date() timestamp!: Date;
@text({ max: 500 }) message!: string;
}Restart npm run dev so rayfin dev applies the new schema to your development backend. When you are ready to publish, deploy it:
npx rayfin upEvery @text() field needs a max, and every entity needs an explicit permission decorator.
Next
- Project structure — what the scaffold generated.
- Develop locally — the
rayfin devworkflow. - Deploying with rayfin up — deployment flags and metadata.