Installation

Install Node.js 20+ and the Rayfin project CLI workflow before scaffolding or deploying a Fabric app.

Install the tools Rayfin needs on your development machine, then use the project-local CLI that npm create @microsoft/rayfin@latest installs. Rayfin deploys managed backends to Microsoft Fabric; the development loop also signs in to Fabric because npm run dev runs rayfin dev.

Prerequisites

Tool	Minimum	Why Rayfin needs it
Node.js	20	Runs npm, Vite, the Rayfin CLI, and TypeScript tooling.
npm	Bundled with Node.js	Installs templates and project dependencies.
Fabric account	Workspace access	`rayfin login`, `rayfin dev`, and `rayfin up` target Microsoft Fabric.

Windows

Install the latest LTS Node.js:

winget install -e --id OpenJS.NodeJS.LTS

Open a new terminal and verify Node.js and npm:

node --version
npm --version

macOS

Install Node.js 24 with Homebrew. Homebrew installs versioned Node.js without putting it on your PATH, so add it:

brew install node@24
echo 'export PATH="$(brew --prefix node@24)/bin:$PATH"' >> ~/.zshrc

Open a new terminal and verify Node.js and npm:

node --version
npm --version

Linux (Ubuntu or Debian)

Install the latest LTS Node.js from the official Node.js download instructions, then verify it:

node --version
npm --version

Install the Rayfin CLI in a project

You usually do not install @microsoft/rayfin-cli globally. New projects include it as a dev dependency and run it through npx or npm scripts.

Create a new project:

npm create @microsoft/rayfin@latest my-app
cd my-app
npm install
npx rayfin --version

Add Rayfin to an existing project:

npm install --save-dev @microsoft/rayfin-cli
npx rayfin init
npx rayfin --help

Use Microsoft Entra ID for Fabric operations:

npx rayfin login
npx rayfin login status

The CLI stores tokens with the OS keychain. If a dev container, Codespace, or Linux environment has no keychain, opt in to plaintext fallback only for that development environment:

npx rayfin login --encryption-fallback-enabled

For CI, use service principal login instead of an interactive browser flow.

Update project dependencies

Rayfin packages ship in lockstep. Update the project dependency graph, not a global CLI:

npm update --save
npm install
npx rayfin --version

If the CLI reports a static-hosting or auth SDK compatibility problem during deploy, update all @microsoft/rayfin-* packages together.

PromptPrepare this machine for Rayfin

Check this machine for Node.js 20 or later. Install or update missing prerequisites for the current operating system, then run `node --version`, `npm --version`, and `npx rayfin --version` inside my Rayfin project. If `npx rayfin login` fails because there is no OS keychain, retry with `--encryption-fallback-enabled` and explain that the fallback is for this development environment only.

Quickstart — scaffold and run a Rayfin app.
Develop locally — understand the rayfin dev loop.
Deploy to Fabric — publish a static build with rayfin up.

Something wrong on this page?Report an issueEdit this page