Rayfin

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 dev

The 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

  1. Finds the Rayfin project from [project-path] (default .).
  2. Authenticates with Fabric, using -t, --tenant when provided.
  3. Resolves or creates the target Fabric backend. --workspace, --workspace-id, RAYFIN_WORKSPACE_ID, and recorded deployments can all select the workspace.
  4. Applies runtime settings from rayfin.yml, including connectors.
  5. Applies the Data configuration unless --skip-db-apply is passed.
  6. Applies Storage folder declarations to the Fabric backend when services.storage.enabled: true. --skip-db-apply does not skip this step, and no local Storage service starts. Changed in 2.0
  7. Reserves the frontend dev port and appends http://localhost:<port> and http://127.0.0.1:<port> to auth redirect URIs when Auth is enabled.
  8. Writes RAYFIN_PUBLIC_* values to rayfin/.env and regenerates the framework .env.local unless --no-emit-env is passed.
  9. Starts npm run dev:frontend when present, otherwise npm run dev if it is not recursive.
  10. When services.functions.enabled: true, builds Functions, writes rayfin/functions/local.settings.json, starts type generation and the local Functions host, then starts the frontend with RAYFIN_PUBLIC_FUNCTIONS_URL pointing at that host. It warns when the Functions host.json still 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

OptionDefaultDescription
[project-path].Path to the project root directory.
--skip-db-applyfalseSkip automatic database configuration apply.
--env-file <path>rayfin/.envPath to .env for rayfin.yml interpolation.
--provider <provider>fabricBackend 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 tenantEntra ID tenant GUID.
--encryption-fallback-enabledfalseAllow plaintext token storage when the OS keychain is unavailable.
--no-emit-envfalseLeave existing framework .env.local untouched.
-v, --verbosefalseEnable verbose logging.

Files written

FileWritten when
rayfin/.deployments.jsonA backend is provisioned or selected.
rayfin/.envPublic backend values, frontend port, retained port aliases, and local Functions URL are updated.
.env.local or <staticHosting.path>/.env.localFramework environment is regenerated unless --no-emit-env.
rayfin/functions/local.settings.jsonFunctions are enabled and run locally.
.vscode/launch.jsonBest-effort Functions attach config when Functions debugging is enabled.

Ports

PortBehavior
FrontendStarts 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.
FunctionsStarts at 7071 and slides forward when occupied. The chosen URL is written to RAYFIN_PUBLIC_FUNCTIONS_URL.
Node inspectorStarts at 9229 and slides forward when Functions debugging is enabled.

dev storage apply

New in 2.0

npx rayfin dev storage apply

Use 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.

OptionDefaultDescription
--forcefalseForce the storage controller to accept configuration that may result in data loss.
--gen-config-onlyfalseGenerate 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.

MessageFix
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

Changed in 1.36

npx rayfin dev functions apply

Use 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.

OptionDefaultDescription
--port <port>7071Port for the local function host. Slides forward when occupied.
--inspect-port <port>9229Port for the Node.js inspector when debug is on.
--no-debugdebug enabledDisable the Node.js inspector on func start.
--no-emit-envfalseSkip framework .env.local regeneration from rayfin/.env.
--verbosefalseShow detailed diagnostic output.
--jsonfalseOutput result as JSON.
-y, --yesfalseRun 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.

PromptStart the Rayfin development session
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.
PromptRetry Storage configuration on the development backend
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.
Something wrong on this page?Report an issueEdit this page

On this page