Environments and configuration

Understand Rayfin environment files, deployment records, frontend variables, and workspace targeting rules.

Rayfin uses checked-in configuration for desired state and gitignored files for local deployment targets and generated runtime values.

File locations

Path	Purpose	Commit it
`rayfin/rayfin.yml`	Desired service configuration.	Yes
`rayfin/.env`	Local deployment values, `RAYFIN_PUBLIC_*`, and interpolation inputs.	No
`rayfin/.env.example`	Documented placeholders for teammates.	Yes
`rayfin/.project.json`	Scaffold lineage identifier.	Usually yes
`rayfin/.deployments.json`	Recorded Fabric deployments and active target.	No
`.env.local` or package `.env.local`	Framework variables generated from `rayfin/.env`.	No
`~/.rayfin/auth.json` and token cache	CLI sign-in state.	No

Frontend-visible variables

Rayfin variable	Vite variable	Description
`RAYFIN_PUBLIC_API_URL`	`VITE_RAYFIN_API_URL`	Managed Fabric backend API URL.
`RAYFIN_PUBLIC_PUBLISHABLE_KEY`	`VITE_RAYFIN_PUBLISHABLE_KEY`	Public SDK key.
`RAYFIN_PUBLIC_ITEM_ID`	`VITE_FABRIC_ITEM_ID`	Fabric item ID.
`RAYFIN_PUBLIC_WORKSPACE_ID`	`VITE_FABRIC_WORKSPACE_ID`	Fabric workspace ID.
`RAYFIN_PUBLIC_TENANT_ID`	`VITE_FABRIC_TENANT_ID`	Entra tenant ID.
`RAYFIN_PUBLIC_PORTAL_URL`	`VITE_FABRIC_PORTAL_URL`	Fabric portal base URL.
`RAYFIN_PUBLIC_FRONTEND_PORT`	`VITE_PORT`	Stable local frontend port used by `rayfin dev` (Next.js maps it to `PORT`).
`RAYFIN_PUBLIC_FUNCTIONS_URL`	`VITE_RAYFIN_FUNCTIONS_URL`	Local Functions URL while `rayfin dev` runs Functions.

CI and automation variables

Variable	Use
`RAYFIN_TOKEN`	Pre-acquired token for headless automation when service principal login is not used.
`RAYFIN_TENANT_ID`	Ambient tenant equivalent to `--tenant`.
`RAYFIN_WORKSPACE_ID`	Ambient workspace target for `rayfin dev` and `rayfin up`. Do not combine with `--capacity-id`.
`RAYFIN_ENV_FILE`	Alternate env file path, equivalent to `--env-file`.
`RAYFIN_ENCRYPTION_FALLBACK_ENABLED`	Allows plaintext token cache when the OS keychain is unavailable. Use for development environments only.
`RAYFIN_FEATURE_FLAGS`	Experimental feature opt-ins, such as storage.

Workspace targeting

Input	Applies to	Notes
`--workspace <name>`	`rayfin dev`, `rayfin up`	Resolves a Fabric workspace display name.
`--workspace-id <id>`	`rayfin dev`, `rayfin up`	Targets a Fabric workspace GUID.
`--workspace-uri <uri>`	`rayfin up`	Derives the workspace ID from a Fabric portal URL.
`RAYFIN_WORKSPACE_ID`	`rayfin dev`, `rayfin up`	Ambient non-interactive target.
`--capacity-id <id>`	`rayfin dev`, `rayfin up`	Assigns capacity when creating or preparing a target. New in 1.36

Resolution priority

When the same value is available in more than one place, Rayfin resolves it in this order:

Shell environment variables.
The file passed with --env-file, or the file named by RAYFIN_ENV_FILE.
rayfin/.env.
Defaults from rayfin.yml interpolation or CLI defaults.

Variable interpolation in rayfin.yml

Use shell-style interpolation to keep environment-specific values out of checked-in config:

rayfin/rayfin.yml

services:
  staticHosting:
    assetAccess: ${STATIC_ASSET_ACCESS:-protected}
  data:
    dialect: ${RAYFIN_DATA_DIALECT:-mssql}

Syntax	Meaning
`${VAR}`	Requires `VAR` to be set and non-empty.
`${VAR:-default}`	Uses `default` when `VAR` is unset or empty.

When the entire YAML value is an interpolation, Rayfin preserves booleans and numbers where the resolved value can be parsed as that type. Partial interpolation always produces a string.

Multiple deployments

Use separate Fabric workspaces for environments such as dev, test, and production. One checkout can record each deployment in rayfin/.deployments.json:

npx rayfin up --workspace-id <dev-workspace> --item-name my-app-dev
npx rayfin up --workspace-id <test-workspace> --item-name my-app-test
npx rayfin up --workspace-id <prod-workspace> --item-name my-app-prod
npx rayfin up list
npx rayfin up switch prod-workspace

A switch changes the active deployment for local commands. It does not copy data or promote a build; use Deployment pipelines for Fabric stage promotion.

PromptAdd a staging deployment target

Configure my Rayfin project for a staging Fabric workspace. Run `npx rayfin up --workspace-id <staging-workspace-id> --item-name <staging-item-name>`, then `npx rayfin up list` and `npx rayfin up switch --workspace-id <staging-workspace-id>`. Confirm rayfin/.env and the frontend .env.local now point at staging.

Something wrong on this page?Report an issueEdit this page