Rayfin

Rayfin Docs

Rayfin's documentation is available via MCP tools and the rayfin docs CLI. Use these for code examples, API details, and troubleshooting — not this skill. Docs are version-locked to the Rayfin packages installed in the user's project. Run MCP and CLI lookups from the project root so local node_modules wins whether the CLI/MCP package is installed locally, globally, or through npx.

MCP tools (if the rayfin MCP server is connected):

• search_docs(query: '<topic>', module: 'guide') — builder guides and tutorials
• search_docs(query: '<topic>', module: 'ts-sdk') — TypeScript SDK API reference
• get_doc(symbol: '<decorator or class>') — resolve a symbol to its docs
• discover_packages(query: '<topic>') — find missing or too-old Rayfin packages when installed docs do not cover the task

CLI fallback (when MCP is unavailable):

• rayfin docs search '<topic>' --module guide — builder guides and tutorials
• rayfin docs search '<topic>' --module ts-sdk — TypeScript SDK API reference
• rayfin docs get --symbol '<decorator or class>' — resolve a symbol to its docs
• rayfin docs discover '<topic>' — find a Rayfin package when installed docs do not cover the task

If rayfin is not on PATH, use npx -y @microsoft/rayfin-cli docs ... from the project root.

Key doc topics:

• Known limitations — FK naming, constraint limits, relationship rules
• Data permissions — @role decorator, policy DSL, field visibility
• GraphQL data access — RayfinClient setup, query chain, mutations
• Auth overview — auth methods, session handling
• Fabric deployment — workspace and static app deployment workflow

Before creating entities or writing queries, check known limitations:

search_docs(query: 'known limitations', module: 'guide')
# or: npx -y @microsoft/rayfin-cli docs search 'known limitations' --module guide

Rules

Platform

• Rayfin uses TC39 Stage 3 decorators — never enable experimentalDecorators or emitDecoratorMetadata.
• Include ESNext.Decorators in the tsconfig lib array.
• Two deployment targets: Rayfin Local (Docker, MSSQL or PostgreSQL) and Fabric Apps (managed, MSSQL only).
• Prefer npm create @microsoft/rayfin@latest for new projects — it generates correct tsconfig and schema boilerplate.

Security

• Every entity must have an explicit permission decorator (@role, @anonymous, @authenticated) — entities without one are inaccessible.
• Add policy: (claims, item) => claims.sub.eq(item.user_id) for row-level filtering on user-scoped data.
• Use exclude in role options to hide sensitive fields (e.g., exclude: ['secret']).
• Publishable keys (pk-*) are safe for client-side code — never expose service secrets or connection strings.
• Keep allowedRedirectUris in rayfin.yml tightly scoped to your app's origin.
• Email/password auth is local development only — deployed Fabric apps support Fabric SSO (Entra ID) exclusively.
• Fabric SSO only works inside the Fabric Portal — do not attempt it in local development.

Data Modeling

• Define entities with @entity() in rayfin/data/ and register them in rayfin/data/schema.ts as type AppSchema = { Name: Name }.
• Every field needs exactly one decorator: @uuid, @text, @int, @decimal, @boolean, @date, @email, @set.
• Fields are required by default — use { optional: true } and ? together for nullable fields.
• @text() length option is max (not maxLength) — e.g., @text({ max: 200 }).
• Use @one(() => Target) with lazy arrow functions for relationships — Rayfin auto-generates FK columns named {property}_id.
• Use import (not import type) for entity classes referenced in @one()/@many() arrow functions — decorators need the runtime class value.
• FK columns referencing another entity ({property}_id) must use @uuid() to match the PK type. Auth-based fields like user_id from claims.sub use @text().
• Many-to-many requires an explicit join entity with two @one() fields.
• Use @many(() => Target) for the inverse side of relationships.

Querying

• Query chain: .select() → .where() → .orderBy() → .execute().
• Single record by ID: client.data.Entity.findById('uuid-here') — not findByPk.
• Filter by FK columns using {property}_id (e.g., customer_id), not dot-path (e.g., customer.id).
• Dot-paths are for .select() only (e.g., customer.companyName).
• Use .first(n).executePaginated() for cursor-based pagination.
• Sort directions must be lowercase: 'asc' or 'desc'.

Schema

• For Fabric: rayfin up is the canonical command for "deploy this change," "apply this schema change," or "push my entity update" — it deploys the app and applies pending schema migrations in a single step. Recommend it on every deploy, including incremental schema changes after the initial deploy.
• rayfin up db apply is a narrow advanced subcommand that applies schema-only without touching the static build — only recommend it when the user explicitly asks to skip the static deploy step.
• --force permits destructive changes (drop table, drop column, alter type) — never use without review.
• --gen-config-only generates the underlying API config without applying — use to inspect before applying.

Deployment

• When the user asks to "build and deploy," "make it live," or "deploy this change" (including schema-only changes like adding a column), execute the full workflow — do not present steps as instructions for the user to run manually.
• Workflow: rayfin login → rayfin up → rayfin up status. rayfin up builds the static app, deploys it, and applies any pending schema migrations.
• rayfin up status checks endpoint health — run after deployment to verify.
• Deployment metadata is written to rayfin/.deployments.json (per-workspace record: fabricItemId, hostingUrl, publishableKey, etc.). The deploy also appends the live hosting URL to allowedRedirectUris in rayfin.yml.

Anti-Patterns

• Never use raw fetch() or hand-built GraphQL for data operations — always use client.data.<Entity> (provides type-safe queries and automatic auth).
• Never omit permission decorators on entities — always add an explicit @permissions(...). Forgetting silently applies authenticated: * (full CRUD for any signed-in user), which is usually too permissive for production data.
• Never use @text() without max on MSSQL — always set @text({ max: N }) (e.g. max: 200 for typical strings). NVARCHAR(MAX) breaks GraphQL schema generation and cannot be uniquely indexed.
• Never use @text() for FK columns that reference another entity's @uuid() PK — use @uuid() to match types. (user_id from claims.sub is @text(), not a FK.)
• Never skip search_docs('known limitations') before implementing entities — always run it first to surface platform constraints (text length caps, supported scalar types, MSSQL-specific gotchas) that affect entity design.

CLI Quick Reference

# Scaffold
npm create @microsoft/rayfin@latest <name>   # Create from template
npx rayfin init [directory]                   # Interactive setup

# Deploy to Fabric (default workflow)
npx rayfin login                              # Sign in with Entra ID
npx rayfin up                                 # Deploy app + apply schema (canonical)
npx rayfin up status                          # Check deployment health
npx rayfin up db apply                        # Schema-only, skip static deploy (advanced)
npx rayfin up staticapp deploy                # Redeploy static content