Build and deploy a Microsoft Fabric App with Rayfin

Fabric Apps are not Power BI organizational apps. They are code-first web applications that run inside Fabric, with Fabric authentication, a managed backend, a SQL database, and optional static hosting.

The tool in this walkthrough is Rayfin. The flow was validated in a Fabric trial workspace named blog_fabric_app. Fabric Apps are preview technology, so check the current CLI and generated project before using this in production.

The result

React + Vite frontend
        |
        v
Rayfin CLI
        |
        +--> Fabric App item
        +--> Fabric SQL database
        +--> Fabric authentication
        +--> protected static website

Prerequisites

You need:

1. Node.js and npm.
2. A Fabric workspace on active capacity.
3. Contributor, Member, or Admin access to that workspace.
4. Fabric Apps (preview) enabled for the tenant.

An administrator can enable the workload from OneLake catalog > Govern > Configurations > Workloads.

Create or select:

blog_fabric_app

1. Scaffold the project

npm create @microsoft/rayfin@latest -- fabric-orders-app --workspace blog_fabric_app
cd fabric-orders-app

For an existing application:

npx rayfin init .

The generated project includes:

rayfin/rayfin.yml   # services and deployment settings
rayfin/data/        # TypeScript data models
src/                # frontend source
package.json        # scripts and Rayfin package versions

2. Check the service configuration

A minimal rayfin/rayfin.yml is:

id: fabricordersapp
name: FabricOrdersApp
version: 1.0.0
services:
  auth:
    enabled: true
    fabric:
      enabled: true
    allowedRedirectUris:
      - http://localhost:5173
  data:
    enabled: true
    dialect: mssql
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html

Deployed apps support Fabric-brokered Microsoft Entra SSO. Do not use local email/password authentication as the production identity design. It is for local development.

3. Run and build locally

npx rayfin dev

Before deployment, run the project’s own checks:

npm run build
npm test

If the template has no tests, the build is still a useful minimum gate. In the validation run, the React/Vite project compiled to dist successfully.

4. Preview the deployment

npx rayfin login
npx rayfin login status
npx rayfin up --workspace blog_fabric_app --dry-run --verbose

The dry run should show workspace resolution, Fabric App creation or update, runtime settings, the database model, and static-content upload.

5. Deploy and verify

npx rayfin up --workspace blog_fabric_app
npx rayfin up status
npx rayfin up status --json

A successful deployment reports the Fabric workspace and item, its child SQL database, the Fabric portal URL, and the hosted app URL. The validated app returned a protected *.webapp.fabricapps.net URL. Anonymous access showed Sign in to continue, which is the expected result for protected hosting.

The package-version trap

The first live deployment created the Fabric App but failed at static hosting:

Static hosting requires Rayfin CLI version 1.35.0-alpha.1413 or later.

Updating only the CLI was not enough. Rayfin packages are released as a compatible set, and a mixed installation was rejected on the next attempt. Update the CLI and runtime packages together:

npm install --save-dev @microsoft/rayfin-cli@latest
npm install \
  @microsoft/rayfin-auth-provider-fabric@latest \
  @microsoft/rayfin-client@latest \
  @microsoft/rayfin-core@latest \
  @microsoft/rayfin-data@latest

After rebuilding, npx rayfin up --workspace blog_fabric_app deployed the frontend, authentication service, and SQL database.

Keep all @microsoft/rayfin-* packages aligned. That is a preview-era constraint worth checking before debugging the application itself.

Smaller update commands

# Apply data-model changes only
npx rayfin up db apply

# Rebuild and deploy static frontend content only
npx rayfin up staticapp deploy

# Initialize server-side TypeScript functions
npx rayfin functions init

Rayfin blocks potentially destructive database changes by default. Use npx rayfin up db apply --force only after reviewing the proposed data loss.

What rayfin up actually deploys

The command:

1. creates or reuses a Fabric App item;
2. synchronizes runtime and authentication settings;
3. applies the Rayfin data-model schema;
4. builds and packages the static frontend;
5. uploads the application; and
6. records deployment metadata for later updates.

That is useful because the app, identity, backend, and data model share one deployment path. It also means a green frontend build is not the same as a complete deployment.

Before sharing the app

• Keep secrets out of frontend code and Git.
• Enable Fabric authentication in rayfin.yml.
• Run a dry run first.
• Review dependency and npm audit output.
• Test with a user who has only the intended Fabric permissions.
• Keep the compressed static archive below the documented 100 MB limit.
• Version the project in Git.

Sources

• Create a Fabric app with the Rayfin CLI
• Deploy a Fabric app to Fabric
• Rayfin CLI reference

Rayfin makes the scaffold-build-dry-run-deploy loop concrete, but Fabric Apps are still preview technology. Keep the project small, align package versions, and verify the protected deployment rather than stopping when the item appears in the workspace.