rayfin dev
Start a local frontend and optional Functions runtime against a deployed Fabric Rayfin backend with rayfin dev.
Use rayfin dev for the local development loop. It provisions or reuses a Fabric
AppBackend, applies service settings, Data schema, and Storage folder declarations, writes
browser-visible environment values, then starts local project code.
npx rayfin devThe Fabric backend remains deployed in Microsoft Fabric. The CLI runs only your frontend,
and Functions when enabled, on localhost. It never publishes static content.
What the session does
- Finds the Rayfin project from
[project-path](default.). - Authenticates with Fabric, using
-t, --tenantwhen provided. - Resolves or creates the target Fabric backend.
--workspace,--workspace-id,RAYFIN_WORKSPACE_ID, and recorded deployments can all select the workspace. - Applies runtime settings from
rayfin.yml, including connectors. - Applies the Data configuration unless
--skip-db-applyis passed. - Applies Storage folder declarations to the Fabric backend when
services.storage.enabled: true.--skip-db-applydoes not skip this step, and no local Storage service starts. Changed in 2.0 - Reserves the frontend dev port and appends
http://localhost:<port>andhttp://127.0.0.1:<port>to auth redirect URIs when Auth is enabled. - Writes
RAYFIN_PUBLIC_*values torayfin/.envand regenerates the framework.env.localunless--no-emit-envis passed. - Starts
npm run dev:frontendwhen present, otherwisenpm run devif it is not recursive. - When
services.functions.enabled: true, builds Functions, writesrayfin/functions/local.settings.json, starts type generation and the local Functions host, then starts the frontend withRAYFIN_PUBLIC_FUNCTIONS_URLpointing at that host. It warns when the Functionshost.jsonstill allows a Preview extension bundle older than 4.49.0. New in 2.0
Press Ctrl+C to stop local runtimes. The Fabric backend is long-lived and is not deleted.
Options
| Option | Default | Description |
|---|---|---|
[project-path] | . | Path to the project root directory. |
--skip-db-apply | false | Skip automatic database configuration apply. |
--env-file <path> | rayfin/.env | Path to .env for rayfin.yml interpolation. |
--provider <provider> | fabric | Backend provider for managed Rayfin services. Use fabric. |
-w, --workspace <name> | — | Fabric workspace display name to provision a first-run backend into. |
--workspace-id <id> | — | Fabric workspace GUID to provision a first-run backend into. |
--capacity-id <id> | — | Fabric capacity ID to assign when the target workspace has no usable capacity. New in 1.36 |
-t, --tenant <id> | signed-in tenant | Entra ID tenant GUID. |
--encryption-fallback-enabled | false | Allow plaintext token storage when the OS keychain is unavailable. |
--no-emit-env | false | Leave existing framework .env.local untouched. |
-v, --verbose | false | Enable verbose logging. |
Files written
| File | Written when |
|---|---|
rayfin/.deployments.json | A backend is provisioned or selected. |
rayfin/.env | Public backend values, frontend port, retained port aliases, and local Functions URL are updated. |
.env.local or <staticHosting.path>/.env.local | Framework environment is regenerated unless --no-emit-env. |
rayfin/functions/local.settings.json | Functions are enabled and run locally. |
.vscode/launch.json | Best-effort Functions attach config when Functions debugging is enabled. |
Ports
| Port | Behavior |
|---|---|
| Frontend | Starts from RAYFIN_PUBLIC_FRONTEND_PORT or 5173. If occupied, the CLI slides to the next available port and keeps the old occupied value in RAYFIN_FRONTEND_DEV_PORT_ALIASES so existing auth redirects keep working. |
| Functions | Starts at 7071 and slides forward when occupied. The chosen URL is written to RAYFIN_PUBLIC_FUNCTIONS_URL. |
| Node inspector | Starts at 9229 and slides forward when Functions debugging is enabled. |
dev storage apply
npx rayfin dev storage applyUse this subcommand to retry only the Storage configuration on the Fabric backend that
rayfin dev uses, without starting local runtimes or applying other settings. It
generates the configuration from the @blob folders registered in
rayfin/storage/schema.ts and applies it. For the folder model, see
Storage.
| Option | Default | Description |
|---|---|---|
--force | false | Force the storage controller to accept configuration that may result in data loss. |
--gen-config-only | false | Generate configuration without applying it to the server. The file is written to rayfin/.temp/storage-config.json under the Storage service root (services.storage.path, or the project root). |
The subcommand needs services.storage.enabled: true and a backend that a full
rayfin dev run has already provisioned. It always targets the active deployment, so it
rejects --workspace and --workspace-id; run full rayfin dev with a workspace selector
first when you need another workspace. When no @blob folders are declared, it skips the
apply and prints
⚠️ No @blob folder declarations found. Storage configuration was not applied.
In 1.36 this subcommand existed only behind the experimental storage feature flag and
did not target the Fabric backend.
Warning
Removing a folder declaration makes that folder unavailable as soon as the apply
succeeds, and permanently deletes its objects and metadata in the background. Deleted
folders cannot be restored. When a removed folder still contains objects, the apply
stops with Storage apply blocked (409) until you pass --force.
| Message | Fix |
|---|---|
Storage is not enabled in rayfin.yml. | Set services.storage.enabled: true, then retry. |
`dev storage apply` uses the active deployment and does not accept a workspace selector. | Run full rayfin dev with --workspace or --workspace-id first, then retry without the selector. |
No configured active Fabric deployment is registered for this project. | Run full rayfin dev first to provision the backend and apply project settings. |
Storage apply endpoint not found (404) at … | Run the full rayfin dev workflow to apply project settings and enable Storage, then retry. |
dev functions apply
npx rayfin dev functions applyUse this subcommand when you want to run only the local Functions host against the active Fabric deployment, without starting the frontend. For the full workflow, see Functions local development.
| Option | Default | Description |
|---|---|---|
--port <port> | 7071 | Port for the local function host. Slides forward when occupied. |
--inspect-port <port> | 9229 | Port for the Node.js inspector when debug is on. |
--no-debug | debug enabled | Disable the Node.js inspector on func start. |
--no-emit-env | false | Skip framework .env.local regeneration from rayfin/.env. |
--verbose | false | Show detailed diagnostic output. |
--json | false | Output result as JSON. |
-y, --yes | false | Run without interactive prompts. |
The subcommand requires services.functions.enabled: true, an active deployment from
rayfin up, Node.js 20 or later, and Azure Functions Core Tools. When Core Tools are
missing, an interactive run asks for consent before installing prerequisites; a
non-interactive run prints the commands to run and exits.
From my Rayfin project root, run `npx rayfin dev --workspace <workspace-name>` to start the
Fabric-backed local development session. If Functions are enabled, confirm the chosen
Functions URL was written to RAYFIN_PUBLIC_FUNCTIONS_URL and that the frontend started on
the port written to RAYFIN_PUBLIC_FRONTEND_PORT.My Rayfin 2.0 project has services.storage.enabled: true in rayfin/rayfin.yml and a backend
already provisioned by `npx rayfin dev`. Run `npx rayfin dev storage apply --gen-config-only`
and list the folders in the generated rayfin/.temp/storage-config.json. Compare them with
the @blob classes registered in the schema array of rayfin/storage/schema.ts. If they
match, run `npx rayfin dev storage apply`. If the apply stops with "Storage apply blocked
(409)", show me which folders would be removed and ask before re-running with --force,
because removing a folder permanently deletes its objects.rayfin init
Scaffold a new Rayfin project, add Rayfin to an existing directory, select templates, and choose services with rayfin init.
rayfin login
Sign in to Rayfin for Fabric operations, inspect status, sign out, recover from network failures in WSL2 or dev containers, and understand token cache storage.