@microsoft/rayfin-guide 1.1.0 → 1.33.0-beta.1

package/assets/docs/getting-started/index.md

@@ -0,0 +1,201 @@
+---
+sidebar_position: 3
+title: Getting Started
+---
+
+## Overview
+
+Rayfin supports two development paths.
+Choose the one that matches how you want to get started.
+
+### Local development
+
+Run the full Rayfin stack on your machine using Docker.
+This path is ideal for building and testing your application before deploying.
+
+1. Install prerequisites.
+1. Scaffold a project with `npm create @microsoft/rayfin@latest` or [add Rayfin to an existing app](../cli/quickstart.md#add-rayfin-to-an-existing-project).
+1. Start backend services with `npx rayfin up`.
+1. Run your frontend with `npm run dev`.
+
+**Start here:** [Build your first Rayfin app](./create-app-with-cli.md)
+
+### Microsoft Fabric
+
+Create a Fabric data app in the Fabric portal and deploy your application to the cloud.
+This path requires a Microsoft account with Fabric access and tenant admin settings enabled.
+
+1. Enable Fabric data app in your tenant admin settings.
+1. Create a Fabric data app in a Fabric workspace.
+1. Connect your local project and deploy with `npx rayfin up`.
+
+**Start here:** [Create a Fabric data app in Fabric](./create-rayfin-item.md)
+
+## Prerequisites
+
+Install these tools before you begin with either path.
+Rayfin requires Node.js 20 or later, Docker Desktop (or Docker Engine on Linux), and the GitHub CLI.
+
+### Windows
+
+- Install the latest LTS Node.js:
+
+```powershell
+winget install -e --id OpenJS.NodeJS.LTS
+```
+
+- Install Docker Desktop:
+
+```powershell
+winget install --id Docker.DockerDesktop -e
+```
+
+- Add Docker to PATH and start Docker Desktop:
+
+```powershell
+# Docker Desktop typically adds itself to PATH, verify with:
+where docker
+# If not found, add Docker to PATH:
+$env:PATH += ";C:\Program Files\Docker\Docker\resources\bin"; [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
+# Start Docker Desktop (required before using docker commands)
+Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"
+```
+
+- Install the GitHub CLI:
+
+```powershell
+winget install --id GitHub.cli -e
+```
+
+- Add GitHub CLI to PATH (if it does not exist):
+
+```powershell
+# To check if your terminal knows about gh CLI
+where gh
+# If there are no results, add github CLI to your PATH by running:
+$env:PATH += ";C:\Program Files\GitHub CLI"; [Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
+```
+
+- Sign in and verify versions:
+
+```powershell
+gh auth login
+node --version
+docker --version
+gh --version
+```
+
+Note: if prompted, authorize GitHub to access Microsoft.
+
+### macOS
+
+- Install latest LTS Node.js via Homebrew:
+
+```bash
+brew install node@lts
+```
+
+- Install Docker Desktop:
+
+```bash
+brew install --cask docker
+```
+
+- Start Docker Desktop and verify docker is in PATH:
+
+```bash
+which docker
+open -a Docker
+```
+
+- Install the GitHub CLI:
+
+```bash
+brew install gh
+```
+
+- Verify GitHub CLI is in PATH:
+
+```bash
+which gh
+```
+
+- Sign in and verify versions:
+
+```bash
+gh auth login
+node --version
+docker --version
+gh --version
+```
+
+Note: if prompted, authorize GitHub to access Microsoft.
+
+### Linux (Ubuntu or Debian)
+
+- Install the latest LTS Node.js using the [official Node.js download instructions](https://nodejs.org/en/download)
+
+- Install Docker Engine and enable non-root access:
+
+```bash
+sudo apt install -y docker.io docker-compose-plugin
+sudo systemctl enable --now docker
+sudo usermod -aG docker "$USER"
+newgrp docker
+```
+
+- Verify docker is in PATH:
+
+```bash
+which docker
+sudo systemctl status docker
+```
+
+- Install the GitHub CLI:
+
+```bash
+type -p curl >/dev/null || sudo apt install -y curl
+curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+sudo apt update
+sudo apt install -y gh
+```
+
+- Verify GitHub CLI is in PATH:
+
+```bash
+which gh
+```
+
+- Sign in and verify versions:
+
+```bash
+gh auth login
+node --version
+docker --version
+gh --version
+```
+
+## Making Changes
+
+- **Apply the database schema generated from `rayfin/data` entities**
+
+```bash
+npx rayfin up db apply [--force]
+```
+
+- Repeat this command whenever you change decorated entity classes under `rayfin/data`.
+- If running `npx rayfin up db apply` errors because there might be a loss of data, include the `--force` option to confirm that the potential data loss is okay.
+- Run this in a terminal from the same project directory.
+- You should see `✔ Configuration applied successfully!`.
+
+## Troubleshooting
+
+- **Docker is not running**: Start Docker Desktop or `sudo systemctl start docker`, then rerun `npx rayfin up`.
+- **Database apply fails**: Wait for services to be healthy and retry `npx rayfin up db apply`.
+
+## Next Steps
+
+- Continue with [Create app with CLI](./create-app-with-cli.md).
+- Review [Project structure](./project-structure.md) to understand the `rayfin/` folder and schema files.

package/assets/docs/getting-started/project-structure.md

@@ -0,0 +1,290 @@
+---
+sidebar_position: 3
+title: Project structure
+---
+
+Rayfin templates follow a consistent layout so data models, backend configuration, and frontend code stay discoverable.
+This page explains the important folders you will see after running `npm create @microsoft/rayfin@latest`.
+
+## Folder layout
+
+```text
+your-project/
+├── rayfin/
+│   ├── data/
+│   │   ├── schema.ts
+│   │   └── *.ts
+│   ├── .env
+│   ├── rayfin.yml
+│   └── tsconfig.json
+├── src/
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Key files
+
+### rayfin/rayfin.yml
+
+`rayfin/rayfin.yml` is the entrypoint for the Rayfin backend configuration.
+It controls which services run in `npx rayfin up`, and it supports environment variable interpolation.
+
+Full example:
+
+```yaml
+id: my-app
+name: my-app
+version: 1.0.0
+services:
+  auth:
+    enabled: true
+    expiryInMinutes: 60
+    refreshToken:
+      lifetimeInDays: 30
+    customClaims:
+      tenant: "default"
+    scopes:
+      - read:data
+      - write:data
+    allowedRedirectUris:
+      - http://localhost:5173
+    password:
+      enabled: true
+    fabric:
+      enabled: false
+    passwordless:
+      magicLink:
+        enabled: false
+        expiryMinutes: 15
+      smsOtp:
+        enabled: false
+    email:
+      enabled: false
+      provider: smtp
+      senderName: Rayfin Platform
+      verificationTokenExpirationHours: 24
+      passwordResetTokenExpirationMinutes: 30
+      smtp:
+        host: maildev
+        port: 1025
+        senderEmail: noreply@rayfin.local
+        username: ""
+        password: ""
+        useSsl: false
+        useStartTls: false
+        webPort: 1080
+  data:
+    enabled: true
+    dialect: mssql
+  storage:
+    enabled: false
+  staticHosting:
+    enabled: true
+    root: .
+    folder: dist
+    buildCommand: npm run build
+    indexDocument: index.html
+```
+
+#### Top-level fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Yes | Project slug used as the Docker Compose project name and Fabric item identifier. |
+| `name` | `string` | Yes | Human-readable project display name. |
+| `version` | `string` | Yes | Project version (semver). |
+| `services` | `object` | Yes | Service configuration block (see below). |
+
+#### `services.data`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable the data service. |
+| `dialect` | `"mssql"` \| `"postgresql"` | `"mssql"` | Database dialect. Fabric deployments support MSSQL only. |
+
+#### `services.auth`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable the auth service. |
+| `expiryInMinutes` | `number` | — | JWT token expiry in minutes. |
+| `customClaims` | `Record<string, string>` | — | Custom claims added to issued JWTs. |
+| `scopes` | `string[]` | — | OAuth scopes (e.g. `["read:data", "write:data"]`). |
+| `refreshToken.lifetimeInDays` | `number` | — | Refresh token lifetime in days. |
+| `allowedRedirectUris` | `string[]` | `["http://localhost:5173"]` | Allowed redirect URIs for auth callbacks and Fabric brokered auth handoff. Must include the bare origin for Fabric auth. |
+
+**`services.auth.password`**
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `true` | Enable email + password authentication. |
+
+**`services.auth.fabric`**
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable Fabric brokered authentication (Entra ID SSO). |
+
+**`services.auth.passwordless`**
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `magicLink.enabled` | `boolean` | `false` | Enable magic link authentication. |
+| `magicLink.expiryMinutes` | `number` | `15` | Magic link expiration in minutes. |
+| `smsOtp.enabled` | `boolean` | `false` | Enable SMS OTP authentication. |
+
+**`services.auth.email`**
+
+Configure an email provider for magic links, password resets, and email verification.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable email service. Required for magic link auth. |
+| `provider` | `string` | `"smtp"` | Email provider type. |
+| `senderName` | `string` | `"Rayfin Platform"` | Display name for outgoing emails. |
+| `verificationTokenExpirationHours` | `number` | `24` | Email verification token expiry in hours. |
+| `passwordResetTokenExpirationMinutes` | `number` | `30` | Password reset token expiry in minutes. |
+
+**`services.auth.email.smtp`**
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `host` | `string` | `"maildev"` | SMTP server hostname. |
+| `port` | `number` | `1025` | SMTP server port. |
+| `senderEmail` | `string` | `"noreply@rayfin.local"` | Sender email address. |
+| `username` | `string` | `""` | SMTP username. |
+| `password` | `string` | `""` | SMTP password. |
+| `useSsl` | `boolean` | `false` | Use SSL for the SMTP connection. |
+| `useStartTls` | `boolean` | `false` | Use STARTTLS for the SMTP connection. |
+| `webPort` | `number` | `1080` | MailDev web UI port (local development only). |
+
+#### `services.storage`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable the storage service. |
+
+#### `services.staticHosting`
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | `boolean` | `false` | Enable static content hosting. |
+| `root` | `string` | — | Root directory of the frontend project (relative to the project root). |
+| `folder` | `string` | `"dist"` | Directory containing built static assets (relative to `root`). |
+| `buildCommand` | `string` | — | Shell command to run before packaging (e.g. `npm run build`). |
+| `indexDocument` | `string` | — | Default document served for the root path (e.g. `index.html`). |
+
+> **Tip:** All string values support environment variable interpolation with `${VAR}` and `${VAR:-default}` syntax.
+> Variables are resolved from `rayfin/.env` and the shell environment.
+> See [Environment Variable Interpolation](../cli/env-interpolation.md) for details.
+
+### rayfin/.env
+
+`rayfin/.env` is an optional environment file used to supply values to `rayfin.yml` via interpolation.
+Do not commit secrets, and prefer a `rayfin/.env.example` file for documentation.
+
+### rayfin/data/*.ts
+
+Files in `rayfin/data/` define your entities.
+Entities are TypeScript classes decorated with `@entity()` plus field decorators like `@uuid()` and `@text()`.
+
+### rayfin/data/schema.ts
+
+`rayfin/data/schema.ts` maps entity names to their classes.
+The Rayfin client uses this map to provide type-safe access to `client.data.<Entity>`.
+
+### rayfin/tsconfig.json
+
+`rayfin/tsconfig.json` is a project-reference tsconfig used by the Rayfin CLI to compile your entity definitions.
+It extends your root `tsconfig.json` and overrides the settings Rayfin needs (for example, `composite: true` and Node.js module resolution).
+You should not need to edit this file.
+
+### rayfin/.temp/
+
+`rayfin/.temp/` contains generated backend artifacts.
+If the backend appears to be using stale schema or configuration, stop the dev stack and rerun `npx rayfin up` to regenerate.
+
+### tsconfig.json (root)
+
+Your root `tsconfig.json` must meet several requirements for Rayfin decorators and the `rayfin/` sub-project to work correctly.
+
+**Project reference to `rayfin/`** — Add a `references` entry so TypeScript knows about the Rayfin sub-project:
+
+```json
+{
+  "references": [{ "path": "./rayfin" }]
+}
+```
+
+> **Note:** Do not set `emitDecoratorMetadata` to `true`.
+> TypeScript only allows it alongside `experimentalDecorators`, which is incompatible with Rayfin's TC39 decorators.
+
+**Minimal example:**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable", "ESNext.Decorators"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "importHelpers": false,
+    "strict": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"],
+  "references": [{ "path": "./rayfin" }]
+}
+```
+
+> **Tip:** Templates created with `npm create @microsoft/rayfin@latest` already include these settings.
+> If you are integrating Rayfin into an existing project, verify your `tsconfig.json` matches the requirements above.
+
+## Frontend configuration
+
+### Vite configuration
+
+Rayfin decorators use the TC39 Stage 3 decorator specification, which requires an ES2022 or later compilation target.
+Set the `target` to `es2022` in your `vite.config.ts` so Vite, esbuild, and dependency pre-bundling all use the correct language level.
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    target: 'es2022',
+  },
+  esbuild: {
+    target: 'es2022',
+  },
+  optimizeDeps: {
+    esbuildOptions: {
+      target: 'es2022',
+    },
+  },
+});
+```
+
+> **Tip:** Templates created with `npm create @microsoft/rayfin@latest` already include these settings.
+> If you are integrating Rayfin into an existing Vite project, add the three `target` entries shown above.
+
+### Environment variables
+
+Rayfin manages environment variables through `rayfin/.env` using the `RAYFIN_PUBLIC_*` prefix convention.
+When you run `npm run dev`, the `predev` hook calls `rayfin env --framework vite` to generate a `.env.local` file with framework-specific variable names.
+When the CLI detects a Vite or Next.js project automatically, you can omit `--framework`.
+
+The following Vite variables are available in your frontend code after generation:
+
+- `VITE_RAYFIN_API_URL` — Base URL pointing the frontend at the Rayfin backend.
+  Sourced from `RAYFIN_PUBLIC_API_URL` in `rayfin/.env`.
+- `VITE_RAYFIN_PUBLISHABLE_KEY` — Publishable key used for Rayfin client authentication.
+  Sourced from `RAYFIN_PUBLIC_PUBLISHABLE_KEY` in `rayfin/.env`.
+
+To override values, edit `rayfin/.env` directly and re-run `rayfin env --framework vite` (or `npm run dev`, which triggers it automatically).

package/assets/docs/hosting/index.md

@@ -0,0 +1,183 @@
+---
+sidebar_position: 50
+---
+
+# Static Content Hosting
+
+Rayfin can build, package, and serve your frontend application as static content alongside your backend APIs.
+When static hosting is enabled, the CLI deploys your built assets to the Rayfin host, which serves them at a public URL.
+
+## How it works
+
+1. Rayfin runs your configured build command (for example, `npm run build`).
+1. The CLI validates that the output folder exists and contains files.
+1. All files are packaged into a compressed ZIP archive (100 MB maximum).
+1. The archive is uploaded to the Rayfin host, which extracts and serves the content.
+1. The host returns a public hosting URL where your site is accessible.
+
+## Configuration
+
+Add a `staticHosting` section under `services` in your `rayfin.yml` file:
+
+```yaml
+services:
+  staticHosting:
+    enabled: true
+    folder: dist
+    buildCommand: npm run build
+    indexDocument: index.html
+```
+
+### Configuration options
+
+| Option | Required | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | Yes | — | Set to `true` to enable static hosting. |
+| `folder` | Yes | — | Output folder containing built static files, relative to `root`. |
+| `root` | No | Project root | Root directory of the frontend project, relative to the project root. |
+| `buildCommand` | No | — | Shell command to run before packaging (for example, `npm run build`). |
+| `indexDocument` | No | — | Default document to serve for directory requests (for example, `index.html`). |
+
+### Example with a separate frontend directory
+
+If your frontend lives in a subdirectory:
+
+```yaml
+services:
+  staticHosting:
+    enabled: true
+    root: frontend
+    folder: dist
+    buildCommand: npm run build
+    indexDocument: index.html
+```
+
+This resolves the output path to `<project-root>/frontend/dist`.
+
+## Deploying static content
+
+### Full deployment with `rayfin up`
+
+When you run `rayfin up`, static content is deployed automatically as part of the full stack deployment.
+The CLI builds your frontend, packages the output, and uploads it alongside your data and auth configuration.
+
+```bash
+rayfin up
+```
+
+After deployment, the CLI prints the hosting URL and stores it in `rayfin/.deployments.json` for reference.
+
+#### Skip static deployment during local dev
+
+When iterating locally with `npm run dev` (Vite serves the frontend), pass `--exclude-services staticHosting` to deploy the backend without rebuilding and uploading the static bundle:
+
+```bash
+rayfin up --exclude-services staticHosting
+```
+
+This skips only the static build/package/deploy phase — runtime settings are still posted, so previously deployed static content keeps serving from Fabric.
+The scaffolded `npm run dev` script in every sample and template uses this flag.
+
+### Standalone static deployment
+
+Use the `staticapp deploy` subcommand to redeploy only your static content without rerunning the full `rayfin up` flow:
+
+```bash
+rayfin up staticapp deploy
+```
+
+This is useful when you have only changed frontend code and want a faster iteration cycle.
+
+#### Skip the build step
+
+If you have already built your frontend and want to deploy the existing output:
+
+```bash
+rayfin up staticapp deploy --skip-build
+```
+
+#### Verbose output
+
+Enable detailed logging with the `-v, --verbose` flag:
+
+```bash
+rayfin up staticapp deploy -v
+```
+
+## Redirect URI registration
+
+When static hosting is enabled, Rayfin automatically registers the hosting URL's bare origin in `allowedRedirectUris` during deployment.
+This is required for the postMessage-based Fabric brokered auth handoff, even when interactive auth is disabled.
+
+For example, if your hosting URL is `https://bold-river-a3f1bc9d02-westus2.webapp.example.com`, the deploy tool adds:
+
+```yaml
+services:
+  auth:
+    allowedRedirectUris:
+      - http://localhost:5173
+      - https://bold-river-a3f1bc9d02-westus2.webapp.example.com
+```
+
+You do not need to configure this manually.
+The deploy tool updates the configuration and pushes it to the backend during deployment.
+
+## Deployment limits
+
+- The compressed ZIP archive must not exceed **100 MB**.
+- The CLI uses maximum compression to minimize upload size.
+- If your build output exceeds the limit, consider excluding large assets or using the storage service for binary files.
+
+## Complete example
+
+A full `rayfin.yml` with static hosting, auth, and data enabled:
+
+```yaml
+id: my-app
+name: my-app
+version: 1.0.0
+services:
+  auth:
+    enabled: true
+    allowedRedirectUris:
+      - http://localhost:5173
+  data:
+    enabled: true
+    dialect: postgresql
+  staticHosting:
+    enabled: true
+    folder: dist
+    buildCommand: npm run build
+    indexDocument: index.html
+```
+
+## Troubleshooting
+
+### Static folder not found
+
+If the CLI reports that the static folder does not exist, verify that:
+
+- The `folder` path in `rayfin.yml` is correct and relative to `root` (or the project root if `root` is not set).
+- Your build command has run successfully and produced output in the expected directory.
+
+### Empty static folder
+
+An empty output folder usually means the build command did not produce output.
+Run the build command manually to check for errors:
+
+```bash
+npm run build
+```
+
+### Deployment too large
+
+If the ZIP exceeds 100 MB:
+
+- Review your build output for unnecessary files (source maps, unoptimized images).
+- Configure your bundler to exclude development artifacts from the production build.
+- Move large binary assets to Rayfin storage instead of bundling them as static content.
+
+### No remote endpoint configured
+
+The `rayfin up staticapp deploy` command requires an existing remote deployment.
+Run `rayfin up` first to provision the remote endpoint, then use `staticapp deploy` for subsequent updates.