Project structure

Rayfin templates keep backend configuration, deployment state, and frontend code in predictable places. Flat templates and the 1.36 default blankapp template share root commands, but the default now creates the Universal App npm workspace.

Flat template layout

my-app/
├── rayfin/
│   ├── data/
│   │   ├── schema.ts
│   │   └── Todo.ts
│   ├── .env
│   ├── .project.json
│   ├── .deployments.json
│   ├── rayfin.yml
│   └── tsconfig.json
├── src/
├── package.json
├── tsconfig.json
└── README.md

Universal App workspace

Changed in 1.36

The CLI-facing blankapp template now creates the Universal App workspace. The hidden universal-app template name is still accepted, but users normally choose blankapp or the default prompt. The root owns orchestration scripts and rayfin/rayfin.yml; packages own runtime code.

my-app/
├── package.json
├── tsconfig.base.json
├── tsconfig.json
├── rayfin/
│   ├── .env
│   ├── .project.json
│   ├── .deployments.json
│   └── rayfin.yml
└── packages/
    ├── frontend/
    ├── data/
    └── shared/

Root scripts coordinate the workspace:

{
  "workspaces": ["packages/*"],
  "scripts": {
    "dev": "rayfin dev",
    "dev:frontend": "npm run -w @rayfin-app/frontend dev",
    "build:fabric": "npm run -w @rayfin-app/shared build && npm run -w @rayfin-app/data build && npm run -w @rayfin-app/frontend build:fabric",
    "rayfin:up": "rayfin up"
  }
}

rayfin/rayfin.yml

rayfin.yml is the checked-in service declaration that rayfin dev and rayfin up sync to Fabric.

id: universal-app
name: Universal App
version: 1.0.0
services:
  auth:
    enabled: true
    fabric:
      enabled: true
      externalEntraExchange: true
    allowedRedirectUris:
      - http://localhost:5173
  data:
    enabled: false
    path: packages/data
    buildCommand: npm run build
  staticHosting:
    enabled: true
    path: packages/frontend
    folder: dist
    buildCommand: npm run build:fabric
    indexDocument: index.html
    assetAccess: protected
    embedded:
      only: false

services.staticHosting.assetAccess replaces the older anonymousAccess authoring shape. New in 1.35.1

Service configuration fields

String values in rayfin.yml support ${VAR} and ${VAR:-default} interpolation from rayfin/.env and the shell environment. See Environment variables.

Generated and local files

Data and TypeScript files

Flat templates keep entity classes under rayfin/data/ and register them in rayfin/data/schema.ts. Universal apps keep data code under packages/data, and services.data.path tells the CLI where to build it.

Rayfin decorators require an ES2022 or later target. Templates already configure TypeScript and Vite; do not enable emitDecoratorMetadata, and do not switch to @vitejs/plugin-react-swc.

rayfin/tsconfig.json and root tsconfig.json

The Rayfin CLI compiles decorated entity files as a TypeScript project. Flat templates include rayfin/tsconfig.json and a project reference from the root tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable", "ESNext.Decorators"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx"
  },
  "include": ["src"],
  "references": [{ "path": "./rayfin" }]
}

Do not set emitDecoratorMetadata to true. It requires legacy decorators, which are incompatible with Rayfin's TC39 decorators.

Vite configuration

Templates set an ES2022 target in Vite so decorator syntax is parsed consistently:

import { rayfinLocalDev } from '@microsoft/rayfin-local-dev/vite';
import react from '@vitejs/plugin-react-swc';
import { defineConfig, loadEnv } from 'vite';

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'VITE_');
  const port = env.VITE_PORT ? Number(env.VITE_PORT) : undefined;

  return {
    plugins: [react(), rayfinLocalDev()],
    ...(port ? { server: { port, strictPort: true } } : {}),
    build: { target: 'es2022' },
    esbuild: { target: 'es2022' },
    optimizeDeps: {
      esbuildOptions: { target: 'es2022' },
    },
  };
});

The rayfinLocalDev() plugin is development-only. It serves local rayfin.config.json, proxies Rayfin backend routes, routes local Functions calls, and supports local automatic sign-in for protected static assets.

Frontend environment generation

rayfin dev, rayfin up, and rayfin env map RAYFIN_PUBLIC_* values from rayfin/.env into the frontend framework's .env.local. For Vite, the generated variables use the VITE_ prefix:

In a workspace layout, the file is written under services.staticHosting.path, such as packages/frontend/.env.local.

rayfin/.temp

rayfin/.temp/ contains generated backend artifacts, including compiled entity metadata and Data API Builder configuration. If the backend appears stale, restart rayfin dev or run npx rayfin up so the CLI regenerates and reapplies the artifacts.

Next

• Develop locally — how this layout runs with rayfin dev.
• Hosting — static hosting configuration and access posture.
• Deploying with rayfin up — deployment metadata and commands.