rayfin.yml reference

The complete rayfin.yml schema, key by key — id, services.auth, services.data, services.storage, services.staticHosting, services.functions, and connectors.

rayfin/rayfin.yml is a project's committed configuration file: which services are enabled, the database dialect, static hosting settings, and Functions settings. The CLI reads it on every command and writes back to it during scaffolding, rayfin init reconfiguration, and (for allowedRedirectUris and connector entries) after a deploy.

Warning

Always declare services.auth and services.data explicitly, even as enabled: false. The CLI reads those keys without guarding and does no defaulting — omitting either block entirely causes a failure rather than falling back to a default. Also: if services.data.enabled is true, omitting dialect causes a 400 at deploy time (Dialect is required when Data module is enabled).

Top-level keys

Key	Type	Description
`id`	string	Required. Unique project identifier. Used as the Fabric item name when deploying.
`name`	string	Required. Human-readable project name.
`version`	string	Required. Project version string.
`services`	object	Required. See below.
`connectors`	list	Optional. External Fabric data sources. Each entry has its own `name` — see Connector.
`frontend`	object	Deprecated. The frontend framework is now auto-detected from `vite.config.` / `next.config.` / `package.json` at runtime. Retained only for backward compatibility with older `rayfin.yml` files.
`publishable_key`	string	Legacy. Some projects scaffolded by older CLI versions carry a top-level `publishable_key`. Current CLI versions manage the publishable key through `rayfin/.env` (`RAYFIN_PUBLIC_PUBLISHABLE_KEY`) instead — see Environment variables.

`services.auth`

Key	Type	Description
`enabled`	boolean	Required. Turns the Auth service on or off.
`fabric.enabled`	boolean	Fabric SSO (Entra ID). The only supported authentication method.
`allowedRedirectUris`	string[]	Origins allowed to receive auth redirects. `rayfin up` appends the live hosting URL here automatically after a static deploy.
`expiryInMinutes`	number	Session token lifetime.
`customClaims`	map	Additional claims to include in issued tokens.
`scopes`	string[]	Additional OAuth scopes.
`refreshToken.lifetimeInDays`	number	Refresh token lifetime.

`services.data`

Key	Type	Description
`enabled`	boolean	Required. Turns the Data service (Data API Builder) on or off.
`dialect`	`mssql`	Required if `enabled` is `true`. Fabric supports `mssql` only.

`services.storage`

Key	Type	Description
`enabled`	boolean	Turns the Storage service (Azure Storage) on or off. Requires the `storage` feature flag to configure interactively — see Environment variables.

`services.staticHosting`

Key	Type	Description
`enabled`	boolean	Turns static hosting on or off.
`folder`	string	Required if `enabled` is `true`. Build output directory to package and deploy, relative to the project root.
`buildCommand`	string	Command to run before packaging (e.g. `npm run build:fabric`).
`indexDocument`	string	Default document served for directory requests (e.g. `index.html`).
`root`	string	Root directory of the frontend project, relative to the project root. Optional.

`services.functions`

Key	Type	Description
`enabled`	boolean	Turns the Functions service on or off. `rayfin functions init` sets this to `true` automatically when scaffolding.
`buildCommand`	string	Command to run before deploying Functions. Optional.

`services.connectors`

Key	Type	Description
`enabled`	boolean	Registers the `rayfin connector` command group without needing `RAYFIN_FEATURE_FLAGS=connectors`.

Set this before adding the first connector:

rayfin/rayfin.yml

services:
  connectors:
    enabled: true

`connectors`

connectors: is a top-level list of entries, not a map keyed by connector name. rayfin connector add writes this block and keeps it in the current list shape. See Adding a connector and Connector authentication.

Field	Type	Required	Notes
`name`	string	yes	Unique. Must match `/^[a-zA-Z0-9\-_]+$/` and be at most 256 characters.
`type`	string	yes	One of `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, `fabric-semanticmodel`, or `kusto`.
`version`	string	Category B only	Positive integer string, for example `'1'`. Required for `fabric-semanticmodel` and `kusto`.
`config.workspaceId`	string	yes	Fabric workspace ID.
`config.itemId`	string	yes	Fabric item ID.
`auth.type`	`delegated` \| `application`	yes	Lowercase. `application` is rejected on Category B types.
`operations[].name`	string	no	Operation objects, not bare strings. Must be a subset of the type's allowed operations; defaults to all allowed operations.

rayfin/rayfin.yml

connectors:
  - name: sales_warehouse
    type: fabric-warehouse
    config:
      workspaceId: 00000000-0000-0000-0000-000000000000
      itemId: 11111111-1111-1111-1111-111111111111
    auth:
      type: delegated
    operations:
      - name: read
      - name: create
      - name: update
      - name: delete
  - name: sales_model
    type: fabric-semanticmodel
    version: '1'
    config:
      workspaceId: 00000000-0000-0000-0000-000000000000
      itemId: 22222222-2222-2222-2222-222222222222
    auth:
      type: delegated
    operations:
      - name: executeQuery

For kusto, queryServiceUri and databaseName are never written into rayfin.yml. They live only in the generated rayfin/connectors/<name>/schema.ts.

Complete annotated example

This is a real, deployed project's rayfin.yml (from a project scaffolded with the todoapp template):

rayfin/rayfin.yml

id: test1
name: test1
version: 1.0.0
services:
  auth:
    enabled: true
    fabric:
      enabled: true # Fabric SSO — the only supported auth method
    allowedRedirectUris:
      - http://localhost:5173 # local Vite dev server
      - https://clear-gale-6d8b0ba024-westus.webapp.rayfingwdev.com # appended by `rayfin up` after the first static deploy
  data:
    enabled: true
    dialect: mssql # required whenever data.enabled is true
  storage:
    enabled: false # declared explicitly even though unused — see the warning above
  staticHosting:
    enabled: true
    folder: dist # Vite's build output directory
    buildCommand: npm run build:fabric
    indexDocument: index.html
  functions:
    enabled: false
publishable_key: pk-atYGKKCZi3uykRKndYqX # legacy — current CLI versions keep this in rayfin/.env instead

Environment variable interpolation

Any value in rayfin.yml can reference an environment variable with ${VAR} or ${VAR:-default}:

services:
  data:
    dialect: ${DB_DIALECT:-mssql}

See Environment variable interpolation for the full syntax, type coercion rules, and resolution priority.

PromptAudit required service declarations

Read my project's rayfin/rayfin.yml and confirm that both services.auth and services.data
are declared explicitly, even if disabled, and that services.data.dialect is set to mssql
whenever services.data.enabled is true. Fix anything missing, then run
`npx rayfin up --dry-run` to confirm the change is valid before deploying for real.

Something wrong on this page?Report an issueEdit this page

rayfin.yml reference

On this page