---
title: "Quickstart"
description: "Scaffold a Rayfin project, deploy it to Microsoft Fabric, and run the frontend locally — from nothing to a running app in four commands."
url: https://rayfin.ai/docs/start/quickstart
markdown_url: https://rayfin.ai/docs/start/quickstart.md
section: start
product: Rayfin
sdk_version: 1.34.0
cli_version: 1.33.2
last_updated: 2026-08-23T00:07:16-07:00
source: start/quickstart.mdx
---

# Quickstart

> Scaffold a Rayfin project, deploy it to Microsoft Fabric, and run the frontend locally — from nothing to a running app in four commands.

From nothing to a running app in four commands. You need [Node.js 20 or later and the
GitHub CLI](/docs/start/installation) first.

Rayfin deploys your backend to Microsoft Fabric and you run your frontend locally against
it. There is no backend to run yourself.

```prompt title="Let an agent do all of this"
Set up a new Rayfin app for me, end to end.

Rayfin is a backend platform for TypeScript developers on Microsoft Fabric. Before writing
any code, read https://rayfin.ai/docs/reference/agent-rules.md — every page on that site is available as
raw Markdown by appending .md to its URL.

Then do the work yourself rather than printing steps for me:
1. Scaffold a project with `npm create @microsoft/rayfin@latest my-app` and install dependencies.
2. Sign in with `npx rayfin login`.
3. Deploy with `npx rayfin up` and confirm it with `npx rayfin up status`.
4. Start the frontend with `npm run dev` and tell me the URL to open.
```

## 1. Scaffold a project [#1-scaffold-a-project]

```bash
npm create @microsoft/rayfin@latest my-app
cd my-app
```

Pick a template when prompted. You should see `✔ Project created`.

## 2. Sign in [#2-sign-in]

```bash
npx rayfin login
```

Opens a browser for Entra ID sign-in. You need an account with access to a Fabric
workspace.

## 3. Deploy [#3-deploy]

```bash
npx rayfin up
```

This creates the Fabric item, applies the database schema generated from your entities,
and deploys your frontend. Confirm it worked:

```bash
npx rayfin up status
```

> [!TIP]
> While iterating on frontend code, add `--exclude-services staticHosting` to skip
> rebuilding and uploading the bundle — the local dev server serves it instead.

## 4. Run the frontend [#4-run-the-frontend]

```bash
npm run dev
```

The scaffolded `predev` script runs `rayfin env --framework vite`, which writes a
`.env.local` pointing at the backend you just deployed. Open the URL it prints and you have
a working app reading and writing real data.

## Make your first change [#make-your-first-change]

Entities live in `rayfin/data/`. Add a field:

```typescript title="rayfin/data/Timestamp.ts"
import { entity, anonymous, uuid, text, date } from '@microsoft/rayfin-core';

@entity()
@anonymous()
export class Timestamp {
  @uuid() id!: string;
  @date() timestamp!: Date;
  @text({ max: 500 }) message!: string;
}
```

Then redeploy with the same command:

```bash
npx rayfin up
```

`rayfin up` applies pending schema changes as part of a normal deploy. Two rules worth
knowing now: every `@text()` field needs a `max`, and every entity needs an explicit
permission decorator.

## Next [#next]

* [Project structure](/docs/start/project-structure) — what got generated and why.
* [Modeling entities](/docs/data/modeling) — how classes become tables and APIs.
* [Schema migrations](/docs/data/migrations) — how changes reach the database.
* [Known limitations](/docs/reference/known-limitations) — read before modeling seriously.