Static content hosting

Static hosting serves your built frontend from the same Fabric app as the Rayfin backend. rayfin up publishes static content; rayfin dev runs the frontend locally and never publishes static assets.

How it works

1. Rayfin reads services.staticHosting from rayfin/rayfin.yml.
2. The CLI resolves the frontend package directory from path and root.
3. The CLI refreshes the frontend .env.local when it can detect the framework.
4. Rayfin runs buildCommand unless the command is skipped.
5. The output folder is validated and packaged into a compressed archive.
6. The archive is uploaded to the Fabric app.
7. The returned hosting URL is recorded in rayfin/.deployments.json.
8. The hosting origin is registered in allowedRedirectUris for Fabric SSO.

Configure static hosting

services:
  staticHosting:
    enabled: true
    path: packages/frontend
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html
    assetAccess: protected

assetAccess replaces the older anonymousAccess authoring property. The CLI removes services.staticHosting.anonymousAccess when it records the new value. Non-interactive rayfin up runs such as --yes, --json, and CI default a missing posture to protected and write it to rayfin.yml instead of failing. New in 1.35.1

Choose protected or public assets

Do not combine assetAccess: public with embedded.only: true. An embedded-only app has no standalone public surface.

Workspace frontend example

The 1.36 universal app uses an npm workspace and points static hosting at the frontend package:

services:
  staticHosting:
    enabled: true
    path: packages/frontend
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html
    assetAccess: protected

The archive path is packages/frontend/dist, not a root dist directory.

Flat frontend example

Flat templates can omit path:

services:
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html
    assetAccess: protected

Deploy static content

A full deploy builds and uploads static content:

npx rayfin up

For static-only updates after an initial deploy:

npx rayfin up staticapp deploy

Skip the build step only when the output folder already contains the production build you want to publish:

npx rayfin up staticapp deploy --skip-build

staticapp deploy requires an existing remote deployment. Run npx rayfin up once first.

Develop without publishing static content

Use the development loop for frontend iteration:

npm run dev

That runs rayfin dev, starts Vite locally, and does not publish static assets.

Existing automation can still skip the static phase while running the deploy workflow:

npx rayfin up --exclude-services staticHosting

Runtime settings still sync, so the backend remains aligned with rayfin.yml.

Declared package versions

Every runtime-settings write declares packageVersions for the deploying CLI, and includes @microsoft/rayfin-auth when the frontend package has it installed. New in 1.35.1 The control plane uses these declarations to reject static-hosting deployments from a CLI too old to record the asset-access posture.

Run a dry run to see the versions that would be sent:

npx rayfin up --dry-run

Static-hosting access control also checks that an installed @microsoft/rayfin-auth is at least 1.35.0-alpha.1541. New in 1.35.1 If an older Rayfin auth package is present, the CLI prompts to upgrade Rayfin packages together before anything is published.

Redirect URIs

When static hosting is enabled, rayfin up registers the deployed hosting origin with services.auth.allowedRedirectUris. rayfin dev separately registers the local frontend origin and retained port aliases. See Redirect URIs.

Archive limit

The compressed static archive must be at most 100 MB. If the archive is too large:

• Exclude source maps from production output.
• Optimize or move large images and binary assets.
• Store large user-facing files in a service designed for file storage instead of bundling them into the app shell.
• Re-run npx rayfin up staticapp deploy after rebuilding.

Local Vite adapter

Templates register rayfinLocalDev() from @microsoft/rayfin-local-dev/vite. The adapter is for rayfin dev, not production builds. It serves local rayfin.config.json, proxies backend and Functions routes, and supports local automatic sign-in for protected static assets. See Develop locally.

Troubleshooting