Create a Fabric app with the Rayfin CLI

This tutorial shows you how to use the Rayfin CLI to create a project, run it locally, and deploy it to Fabric. You use the same CLI workflow for new apps and for later updates to your schema or frontend.

In this tutorial, you:

  • Create a Fabric Apps project from a template.
  • Start the app locally.
  • Sign in to Fabric from the CLI.
  • Deploy the app to a Fabric workspace.
  • Verify the deployment status.

Prerequisites

  • Access to Fabric.
  • A Fabric workspace where you have Contributor, Member, or Admin permissions.
  • The Fabric Apps workload enabled in your tenant.
  • Node.js and npm installed.

Create an app with an AI prompt

Use the following prompt with GitHub Copilot or another coding agent to create, explore, run, customize, and deploy a Fabric app:

Set up a new Fabric App project called "rayfin-app-ws".

1. Run: npm create @microsoft/rayfin@latest
2. Open the scaffolded project directory.
3. Explore the project structure and understand the Rayfin app framework.
4. Run: npm run dev
5. Make changes to the app based on my instructions.
6. When ready, deploy with: npx rayfin up

The agent runs the commands interactively and asks for any required project or workspace settings. Review generated files and command output before deployment. If the Fabric Apps workload isn't enabled yet, ask a Fabric administrator to turn on Fabric Apps (preview) in OneLake catalog > Govern > Configurations > Workloads.

Create a new app from CLI

To scaffold a new app from a template, use npm create:

npm create @microsoft/rayfin@latest -- my-app --workspace <workspacename>

This command creates a new project folder with the app template, the rayfin configuration, and the frontend source code.

Go to the project directory:

cd my-app

Tip

If you already have an empty project folder or existing source code, use npx rayfin init instead of npm create.

npx rayfin init .

Review the generated project

After scaffolding, the project includes the files you need to start developing:

  • rayfin/rayfin.yml stores app services and deployment settings.
  • rayfin/.env stores environment values used by the CLI.
  • rayfin/data/ contains your data model files.
  • Your frontend app lives in the root project structure created by the selected template.

For a detailed file-by-file breakdown, see Understand the project structure.

Run the app locally

Start the local development environment:

npx rayfin dev

This command starts the frontend development server for the scaffolded app and deploys the backend to Fabric. To confirm the app starts correctly, open the local URL shown in the terminal.

Deploy the app to Fabric

Build more features into your application. After you test your changes, deploy to Fabric again.

npx rayfin up

To preview the deployment without making changes, run:

npx rayfin up --dry-run

Verify the deployment

Check the current deployment state:

npx rayfin up status

For a machine-readable response, use JSON output:

npx rayfin up status --json

After a successful deploy, the CLI prints the hosted app URL and the Fabric portal link for the deployed item.

Deploy database or static content only

If you only changed data models, apply the database changes without a full redeploy:

npx rayfin up db apply

If you only changed frontend code, redeploy the static assets:

npx rayfin up staticapp deploy

Add functions

Functions are TypeScript functions that run on the server inside your Fabric app. Use functions for logic that must not run in the browser, such as working with secrets, accessing privileged data, and calling downstream services on behalf of the signed-in user.

npx rayfin functions init

GitHub Copilot can generate and update the required files and components. You can also ask the agent to run the app, debug functions locally, and deploy the app. For example, you can use the following prompt to build an AI pull request review assistant by using functions:

Build an app that lets me view all pull requests for the repository
<repoURL>, chat with my Azure AI Foundry agent <agentName> to review
pull requests, and post review comments. Use functions with delegated
authentication to connect to Azure AI Foundry and Azure DevOps.

Troubleshoot common issues

Sign-in fails or deployment returns 401 or 403

Run npx rayfin login again, then retry npx rayfin up.

You need to inspect what the CLI will do

Before deploying changes, run npx rayfin up --dry-run.

The app deploys, but you change the schema only

To push schema changes independently, use npx rayfin up db apply. If you perform destructive changes like altering the type of a column or removing a column, this command fails. To force your changes, you can use the --force flag. This action can be a breaking change.

Next steps

  • Last updated on