powerbi-fabric-apps
Skill3 starsChanged 7 months agoMITView on GitHub
Build, run and deploy Microsoft Fabric Apps with the Rayfin SDK and CLI — TypeScript decorator data models, Fabric SSO, GraphQL/DAB data API, storage, Functions, static hosting, and the fabric-semanticmodel connector that executes DAX against a Power BI semantic model from a custom app. Use when the user mentions: Fabric App, Fabric Apps, Rayfin, rayfin CLI, rayfin up, rayfin init, rayfin dev, rayfin connector, data app, backend as a service on Fabric, custom app on a semantic model, app on top of Power BI data, GraphQL on Fabric, Fabric SQL database app, appbackends, deploy an app to a Fabric workspace.
- Reads credentials
- Installs packages
In this repository58 other files it gives its agents.
- powerbi-audit-tenant-settingsSkill
- powerbi-bpa-rulesSkill
- powerbi-connect-pbidSkill
- powerbi-connectSkill
- powerbi-create-pbi-reportSkill
- powerbi-c-sharp-scriptingSkill
- powerbi-custom-visualsSkill
- powerbi-cyber-securitySkill
- powerbi-data-catalog-lineageSkill
- powerbi-data-governance-traceabilitySkill
- powerbi-data-transformationSkill
- powerbi-dax-masterySkill
- powerbi-dax-performanceSkill
- powerbi-daxSkill
- powerbi-deneb-visualsSkill
- powerbi-doctorSkill
- powerbi-duckdb-lakehouseSkill
- powerbi-fabric-app-templatesSkill
- powerbi-fabric-capacitySkill
- powerbi-fabric-cliSkill
- powerbi-fabric-pipelinesSkill
- powerbi-fabricSkill
- powerbi-lineage-analysisSkill
- powerbi-measure-glossarySkill
- powerbi-medallion-architectureSkill
- powerbi-modelSkill
- powerbi-modifying-theme-jsonSkill
- powerbi-paginated-reportsSkill
- powerbi-pbi-cliSkill
- powerbi-pbip-formatSkill
- powerbi-pbir-cliSkill
- powerbi-pbir-format-enhancedSkill
- powerbi-performance-scaleSkill
- powerbi-power-querySkill
- powerbi-project-managementSkill
- powerbi-python-visualsSkill
- powerbi-refresh-semantic-modelSkill
- powerbi-report-authoringSkill
- powerbi-report-conversionSkill
- powerbi-report-designSkill
- powerbi-reportSkill
- powerbi-report-structureSkill
- powerbi-report-themingSkill
- powerbi-review-reportSkill
- powerbi-review-semantic-modelSkill
- powerbi-r-visualsSkill
- powerbi-security-rlsSkill
- powerbi-source-integrationSkill
- powerbi-spark-livySkill
- powerbi-standardize-naming-conventionsSkill
- powerbi-star-schema-modelingSkill
- powerbi-svg-visualsSkill
- powerbi-te2-cliSkill
- powerbi-te-cliSkill
- powerbi-te-docsSkill
- powerbi-testing-validationSkill
- powerbi-time-series-dataSkill
- powerbi-tmdlSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 38
If you can reach none of those sources, say so and stop.
- Distinctive: line 60
Check before scaffolding, even when the user says "new app".
- Distinctive: line 72
Never create a nested or sibling project inside one that already exists.
- Distinctive: line 126
Verify the decorator set against the in-project skill — this shape is the documented pattern, not a guarantee for your installed version:
- Very specific: line 197
Keep the generated version value.
- Very specific: line 214
Always branch on status before touching table.
- Very specific: line 222
Query the model metadata before writing DAX: Never guess table, column or measure names.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Fabric Apps with the Rayfin SDK
Fabric Apps (preview) is a managed backend-as-a-service inside Microsoft Fabric. You
declare the data model as TypeScript classes with decorators; Rayfin provisions the SQL
database, Entra SSO, a GraphQL data API, file storage, Functions and static hosting, and
deploys all of it as one Fabric item with npx rayfin up.
For powerbi-agent the headline use is the fabric-semanticmodel connector: an app that
executes DAX against an existing Power BI semantic model with delegated user identity, so
you can ship a bespoke analytical front end on a model you already govern — without
embedding, without a service principal, and without the Execute Queries REST API in your
own code.
Rule zero: route, don't improvise
Never write Rayfin API code from memory. The decorator set, the client generics, the connector packages and the deployment surface are version-locked per project, and they move fast in preview. Remembered signatures are routinely wrong against the installed version.
Order of authority, highest first:
.agents/skills/rayfin/SKILL.mdin the project — the version-matched skill the CLI installs. If it exists, it wins over this file for every in-project specific.rayfin docsCLI and the package READMEs undernode_modules/@microsoft/rayfin-*.AGENTS.mdat the project root, when the template ships a capability router.- Microsoft Learn: Fabric Apps overview, CLI reference.
This skill owns getting there and the Power BI bridge. Once you are inside a project,
load .agents/skills/rayfin/SKILL.md and follow it.
If you can reach none of those sources, say so and stop. Do not offer a "general approach" or placeholder code — fabricated Rayfin APIs are the specific failure this discipline exists to prevent.
Prerequisites
| Requirement | Check |
| Node.js 20+ | node --version |
| Rayfin CLI | npx rayfin --version (installs on demand; or npm i @microsoft/rayfin-cli) |
| Fabric capacity on the target workspace | fab ls then check the workspace capacity, or the portal |
| Tenant setting Fabric Apps (preview) enabled | Fabric admin portal → Tenant settings |
| Tenant setting Semantic Model Execute Queries REST API enabled | only for the fabric-semanticmodel connector |
| Contributor / Member / Admin on the workspace | fab acl ls or the portal |
| Build + Read on the semantic model | only for the fabric-semanticmodel connector |
| Supported region | region availability — Fabric Apps is not in every region |
Fabric Apps consumes CUs from the assigned capacity. Before standing one up on a shared
production capacity, read powerbi-fabric-capacity and tell the user the expected impact.
Is this already a Rayfin project?
Check before scaffolding, even when the user says "new app". A directory is a Rayfin project if either is true:
rayfin/rayfin.ymlexistspackage.jsondepends on any@microsoft/rayfin-*package
| Situation | Do this |
| Already a Rayfin project | Load .agents/skills/rayfin/SKILL.md, continue in place |
| Existing non-Rayfin app here | Add Rayfin in place: npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <name> |
| Empty directory | Scaffold (below) |
Never create a nested or sibling project inside one that already exists.
Scaffold
Agents run non-interactively (stdin is not a TTY), so use the npx -y form —
npm create can mishandle piped stdin and strip flags, and --project-name is required
non-interactively.
# Analytical app on a semantic model — the Power BI case. Use this template.
npm create @microsoft/rayfin@latest -- "<app-name>" --template dataapp --workspace "<workspace-name>"
# Minimal app, no framework opinions
npx -y @microsoft/create-rayfin@latest --project-name <app-name> --template blankapp
# Add Rayfin to a directory that already has source
npx -y -p @microsoft/rayfin-cli@latest rayfin init --project-name <app-name> [directory]
# See what the installed CLI offers before choosing
npx rayfin init --list-templatescreate-rayfin creates a child directory named from a slugified --project-name, so cd
into it. An in-place rayfin init scaffolds into the current directory.
For the gallery of community templates and how to author one, see
powerbi-fabric-app-templates.
Then read AGENTS.md (if present) and .agents/skills/rayfin/SKILL.md before writing a
line of app code.
Project shape
<app>/
├── rayfin/
│ ├── rayfin.yml # services, auth, static hosting, connectors — the contract
│ ├── .env # deployment properties; never commit secrets
│ ├── .deployments.json # recorded deployments: fabricWorkspaceId, fabricItemId,
│ │ # hostingUrl, fabricDeepLink, deployedAt
│ ├── data/ # TypeScript entity classes — the schema source of truth
│ ├── connectors/<name>/ # generated connector schema (schema.ts, connectorConfig)
│ └── functions/ # Functions package (optional)
├── .agents/skills/rayfin/ # version-locked in-project skill — authoritative
├── AGENTS.md # capability router, when the template ships one
└── src/ # frontendrayfin/.deployments.json is how any tool (including Kurt Buhler's /fabric-app-pane mod)
knows where an app is deployed. Read it rather than asking the user for IDs.
Data model
Entities are plain TypeScript classes with decorators from @microsoft/rayfin-core.
Verify the decorator set against the in-project skill — this shape is the documented
pattern, not a guarantee for your installed version:
import { entity, role, text, boolean, date, uuid } from '@microsoft/rayfin-core';
@entity()
@role('authenticated', '*', {
policy: (claims, item) => claims.sub.eq(item.user_id),
})
export class Todo {
@uuid() id!: string;
@text({ min: 1, max: 100 }) title!: string;
@boolean() isCompleted!: boolean;
@date() createdAt!: Date;
@date({ optional: true }) dueDate?: Date;
@text() user_id!: string;
}Rayfin derives the table definitions, the GraphQL endpoints, the row-level authorization rules and the type-safe client methods from this.
The code is the only safe place to change schema. The child SQL database is editable in
the Fabric portal, and editing it there causes schema conflicts that break the app. Change
rayfin/data/, then npx rayfin up db apply.
The Power BI bridge: fabric-semanticmodel
This is the connector that makes Fabric Apps interesting to a Power BI practice. It gives the app typed, delegated, read-only DAX execution against a semantic model.
# 1. Find the model (omit --workspace-id to search the project's recorded workspaces)
npx rayfin connector search --workspace-id <workspace-id> --type fabric-semanticmodel --json
# 2. Add it
npx rayfin connector add \
--type fabric-semanticmodel \
--workspace-id <workspace-id> \
--item-id <semantic-model-item-id> \
--name salesModel \
--operations executeQuery
# 3. Run the npm install command the CLI prints — verbatim. It is version-matched.
# 4. Inspect without changing anything; --url accepts a portal URL and derives both IDs
npx rayfin connector inspect --name salesModel --entity Sales --rows 10
npx rayfin connector inspect --url "https://app.powerbi.com/groups/<ws>/datasets/<id>"
npx rayfin connector inspect --name salesModel --query ./queries/top-products.dax
# 5. Smoke-test an operation from the terminal before wiring the UI
npx rayfin connector invoke salesModel executeQuery --input '{"query":"EVALUATE ROW(\"n\", 1)"}'connector add writes to rayfin/rayfin.yml:
connectors:
- name: salesModel
type: fabric-semanticmodel
config:
workspaceId: "<workspace-id>"
itemId: "<semantic-model-item-id>"
auth:
type: delegated
version: "1"
operations:
- name: executeQueryKeep the generated version value. Do not hand-edit workspaceId / itemId when a
connector subcommand can set them.
Client side — one data-access path, the connector client:
const result = await client.connectors.salesModel.executeQuery({
query: 'EVALUATE TOPN(10, Sales)',
});
if (result.status === 'success') {
render(result.table.columns, result.table.rows);
} else {
showError(result.error.category, result.error.message);
}Always branch on status before touching table. A failed query must surface an error
state — never substitute mock data for a connector failure.
DAX inside a Fabric App
The DAX discipline does not change because the host is a web app. powerbi-dax-mastery and
powerbi-dax-performance still apply, plus:
- Query the model metadata before writing DAX. Never guess table, column or measure
names.
pbi-agent model tables/model measuresagainst the model (orrayfin connector inspect --entity) first. - Bound every result set.
TOPN, an explicit row cap, or a filteredSUMMARIZECOLUMNS. An unboundedEVALUATE Saleson a real fact table will take the app down, not just slow it. - Reuse results. Each
executeQueryis a capacity-billed query against the model. Cache per interaction rather than per component render. - Apply the model's format strings to cards, axes, tooltips, data labels and grid cells, so the app agrees with the reports built on the same model.
- Delegated auth only. RLS on the model is enforced because the caller is the signed-in user. Never add a service principal, a stored token, or a direct call to the Execute Queries REST API to work around a permission error — fix the permission.
Other connector types are available; npx rayfin connector types -v lists what the
installed CLI supports (lakehouse, warehouse, SQL database in Fabric, semantic model).
Local development
npx rayfin dev # full stack locally
npx rayfin dev --workspace "<ws-name>" # first run, names the backend workspace
npx rayfin dev --skip-db-apply # don't auto-apply schema
npx rayfin dev functions apply # local Functions host (default port 7071)
npx rayfin env --framework vite # emit .env.local from rayfin/.env
npx rayfin env --framework nextjs --show # preview without writingLocal dev may use email/password auth. Deployed apps are Fabric SSO only — no other provider is available after deployment. Do not build a sign-in flow that assumes otherwise.
Deploy
npx rayfin login # and: rayfin login status / rayfin logout
npx rayfin up --dry-run --verbose # always first: validates and resolves the workspace
npx rayfin up --workspace-id <id> --yes # non-interactive deploy
npx rayfin up --exclude-services functions # skip functions or staticHosting
npx rayfin up status --json
npx rayfin up list # every recorded deployment
npx rayfin up switch --list # then: rayfin up switch <workspace>Targeted re-deploys, when only one service changed:
| Command | Deploys |
npx rayfin up db apply | DAB config / schema to the remote item |
npx rayfin up staticapp deploy [--skip-build] | built frontend assets |
npx rayfin up functions deploy [--skip-build] | Functions |
npx rayfin up connector apply [--name <n>] | declared GraphQL connector config |
--force on rayfin up allows destructive data-schema changes. Treat it the way you
treat DROP: name the entity and the column, say what data is lost, and get an explicit yes
before running it. Never add --force to clear an error you have not diagnosed.
--capacity-id cannot be combined with --workspace, --workspace-id or --workspace-uri.
Deployed topology
One backend endpoint fronts every service:
https://<your-app>-app.rayfin.windows.net/
/api/graphql data API, used by the Rayfin client
/auth authentication
/storage file storageChild items appear under the Fabric app in the portal: the SQL database (read-only there), authentication, and static content. Item permissions do not inherit from workspace roles — a user needs Run and interact to use the app, Edit to deploy to it, Reshare to grant access.
Agent context files
npx rayfin init ai-files status --json # up-to-date / update-available / user-modified / missing / …
npx rayfin init ai-files install --yes # idempotent; preserves user config
npx rayfin init ai-files install --force skill:rayfin
npx rayfin init ai-files install --dry-runThis manages AGENTS.md, .mcp.json and .agents/skills/rayfin/SKILL.md. --force never
overwrites AGENTS.md. Run status at the start of any session in an existing project: a
user-modified or stale in-project skill is the usual cause of code that compiles against
the wrong Rayfin version.
Security
You own, and Fabric does not:
- No secrets in the repo, in
rayfin/.envcommits, or in frontend assets — regardless of theassetAccesssetting. Static assets are shipped to the browser. - What authenticated users can see and do. SSO proves identity; your
@rolepolicies and your queries decide authorization. - Least privilege for contributors. Edit on the item means they can
rayfin up. - Compliance accountability for whatever the app stores. An app over a governed semantic
model that persists extracts into its own SQL database has created a second copy of that
data — say so, and check it against
powerbi-data-governance-traceability.
Not a fit
Say so early rather than fighting the platform:
- Complex multi-step transactions or stored procedures.
- Custom auth providers beyond Fabric SSO (and email/password locally).
- Anything needed in a region where Fabric Apps is not yet available.
- A report. If the deliverable is a report, build a report —
powerbi-create-pbi-report. Fabric Apps is for interactions a report cannot express.
Related skills
| Need | Skill |
| Template gallery, choosing and authoring templates | powerbi-fabric-app-templates |
| CU cost of running the app on a capacity | powerbi-fabric-capacity |
| Workspace / item plumbing around the app | powerbi-fabric-cli |
| DAX the app will execute | powerbi-dax-mastery, powerbi-dax-performance |
| Chart choice and formatting in the frontend | powerbi-report-design |
| Governance of a second copy of governed data | powerbi-data-governance-traceability |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

