Fabric Apps projektstruktur

Fabric Apps projekterer separate backend-konfigurationer, datamodeller og frontend-kode. Den præcise opbygning afhænger af skabelonen. Standardskabelonen blankapp løser til Universal App, et npm-arbejdsområde med separate frontend-, data- og delte pakker.

Mappelayout

Standard Universal App-stilladset har følgende struktur:

your-project/
├── rayfin/
│   ├── .env
│   ├── rayfin.yml
│   └── tsconfig.json
├── packages/
│   ├── frontend/
│   │   ├── src/
│   │   └── package.json
│   ├── data/
│   │   └── src/index.ts
│   └── shared/
│       └── src/index.ts
├── package.json
├── tsconfig.json
└── README.md

Lokation	Ejerskab
rayfin/	Backend-konfiguration og aktive miljøværdier.
packages/frontend/	Browser-UI, klientinitialisering og frontend-build.
packages/data/	Dekorerede runtime-entitetsklasser og skemaregistrering.
packages/shared/	Isomorfe postkontrakter og skematyper deles med frontend. Læg ikke kun backend-kode her.

Data er deaktiveret i basisstilladset. Aktiver det, når din app har brug for vedvarende poster:

npm run pack:add -- data-modeling

Kapaciteten tilføjer en starterenhed og en delt kontrakt og muliggør dataservicen. For entitetsforfatterskab og MSSQL-dialektkonfiguration, se Definér datamodeller.

Flad-skabelon alternativ

Nogle skabeloner og eksisterende apps bruger et fladt layout med frontend-kode i root src/, entities i rayfin/data/, og et skema-type map i rayfin/data/schema.ts. Denne opbygning er stadig gyldig. Flyt ikke filer eller lav dubletter af pakker bare for at matche en anden skabelon. Læs servicevejene ind rayfin/rayfin.yml for at finde de mapper, dit projekt faktisk bygger.

Nøglekonfigurationsfiler

Rayfin/rayfin.yml

rayfin/rayfin.yml-filen er hovedkonfigurationsfilen for din Fabric Apps backend. Den styrer, hvilke tjenester der kører under lokal udvikling, og understøtter interpolation af miljøvariabler for dynamiske konfigurationsværdier.

Standardarbejdsområdet bruger eksplicitte servicestier. Følgende eksempel viser de stier med Data aktiveret for en app, der har brug for en database:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
    fabric:
      enabled: true
      externalEntraExchange: true
    password:
      enabled: false
  data:
    enabled: true
    dialect: mssql
    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

Serviceværdier path er relative til projektets rod. Byg-kommandoer kører fra den løste servicemappe. Funktionsinitialisering registrerer services.functions.path også, når den vælger en arbejdsområdepakke såsom packages/functions. Flade projekter kan bruge den eksisterende rayfin/functions placering. Se Brug funktioner.

Konfigurationen inkluderer disse nøglefelter:

Topniveau-felter

Felt	Type	Påkrævet	Beskrivelse
id	string	Ja	Project slug bruges som Docker Compose project navn og Fabric item identifier.
name	string	Ja	Menneskeligt læsbart projektvisningsnavn.
version	string	Ja	Project-version (semver).
services	object	Ja	Servicekonfigurationsblok.

services.data

Felt	Type	Standardindstilling	Beskrivelse
enabled	boolean	false	Aktivér datatjenesten.
dialect	string	–	Brug mssql til en SQL-database i Fabric. Påkrævet, når Data er aktiveret.
path	string	–	Datapakkekatalog relativt til projektets rod, såsom packages/data. Flade skabeloner kan bruge rayfin/data.
buildCommand	string	–	Byg kommandoen til den konfigurerede datapakke.

services.auth

Felt	Type	Standardindstilling	Beskrivelse
enabled	boolean	false	Aktivér autentificeringstjenesten.
expiryInMinutes	number	–	JWT-tokenet udløber om få minutter.
customClaims	Record<string, string>	–	Toldkrav tilføjet til udstedte JWT'er.
scopes	string[]	–	OAuth-scopes (for eksempel, ["read:data", "write:data"]).
refreshToken.lifetimeInDays	number	–	Opdater tokenets levetid i dage.
allowedRedirectUris	string[]	["http://localhost:5173"]	Tillod omdirigerings-URI'er til godkendelses-callbacks.

services.auth.password

Felt	Type	Standardindstilling	Beskrivelse
enabled	boolean	true	Aktiver e-mail- og adgangskodeautentificering til lokal udvikling

services.auth.fabric

Felt	Type	Standardindstilling	Beskrivelse
enabled	boolean	false	Aktiver Fabric brokered authentication (Microsoft Entra ID SSO).
externalEntraExchange	boolean	–	Aktiver direkte delegeret entra-tokenudveksling og ekstern parent-host-autentificering, når det understøttes af målmiljøet.

services.staticHosting

Felt	Type	Standardindstilling	Beskrivelse
enabled	boolean	false	Aktivér hosting af statisk indhold.
path	string	–	Frontend pakkemappe i forhold til projektets rod.
root	string	–	Legacy frontend root, der bruges af flade konfigurationer.
folder	string	"dist"	Mappe med byggede statiske assets i forhold til den løste frontend-sti.
buildCommand	string	–	Shell-kommandoen skal køre før pakning (for eksempel, npm run build).
indexDocument	string	–	Standarddokument leveret for rodstien (for eksempel index.html).

Tip

Alle strengværdier understøtter interpolation af miljøvariabler med ${VAR} og syntaks ${VAR:-default} . Variabler opløses fra rayfin/.env og shell-miljøet.

rayfin/.env

Filen rayfin/.env indeholder de aktive runtime- og deployment-værdier og leverer værdier til rayfin.yml gennem interpolation. CLI'en skriver framework-neutrale RAYFIN_PUBLIC_* værdier for den aktive backend. Kun variabler med det præfiks projiceres ind i genererede frontend-miljøfiler. Læg aldrig hemmeligheder i RAYFIN_PUBLIC_* variabler.

Hold dig rayfin/.env ude af kildekodekontrol. Brug rayfin/.env.example den til at dokumentere forventede variable med pladsholdere.

Rayfin/.deployments.json

Implementeringsregistret registrerer backend-URL'er, hosting-URL'er, item-ID'er og arbejdsområde-ID'er for dit projekts deployments. Det er ikke en frontend-miljøfil. Hold det ude af versionskontrol. Brug npx rayfin up list til at liste registrerede udrulninger og npx rayfin up switch <name> til at skifte den aktive udrulning og gengenerere dens miljøværdier.

Rayfin/tsconfig.json

Skabeloner giver TypeScript-konfiguration til deres layout. Workspace-pakker har deres egne konfigurationer og projektreferencer; flade skabeloner kan kompilere enheder gennem rayfin/tsconfig.json. Bevar stillingens referencer og brug dens build- og type-check-scripts i stedet for at antage en enkelt root-kompilering.

Datamodelfiler

Hold kørselsregistrering og kundeorienterede typer tilpasset dit valgte layout.

Workspace-enheder og delte kontrakter

I Universal App definerer filer under packages/data/src/ dekorerede entitetsklasser. Registrer runtime-klasserne i arrayet, der schema eksporteres af packages/data/src/index.ts.

Behold matchende record-interfaces og UniversalAppSchema typen i packages/shared/src/index.ts. Frontenden importerer denne kontrakt fra @rayfin-app/shared i stedet for at importere dekorerede backend-klasser.

Flad-skabelon-enheder

I en flad skabelon rayfin/data/*.ts definerer entiteter og rayfin/data/schema.ts afbilder entitetsnavne til typer for client.data.<Entity>. Følg registreringsmekanismen, som den skabelon giver.

Genererede artefakter

rayfin/.temp/

Mappen rayfin/.temp/ indeholder genererede backend-artefakter, der oprettes, når du kører udviklingsserveren. Hvis backenden ser ud til at bruge forældet skema eller konfiguration, stop og genstart udviklingsstakken for at generere disse filer.

Vigtig

Commit .temp/ ikke mappen til dit repository. Tilføj det til din .gitignore fil.

Frontendstruktur

Standardfrontenden er i packages/frontend/src/. Flade skabeloner kan bruge root src/. Indstillingen services.staticHosting.path identificerer frontend-pakken.

Aktiv miljø- og rammekortlægning

rayfin dev og rayfin up generere rammeværksspecifikke .env.local værdier fra rayfin/.env. For en indlejret frontend skrives filen under services.staticHosting.path, såsom packages/frontend/.env.local; flade projekter bruger projektets rod.

Kilde i rayfin/.env	Vite-output i .env.local	Next.js output i .env.local
RAYFIN_PUBLIC_API_URL	VITE_RAYFIN_API_URL	NEXT_PUBLIC_RAYFIN_API_URL
RAYFIN_PUBLIC_PUBLISHABLE_KEY	VITE_RAYFIN_PUBLISHABLE_KEY	NEXT_PUBLIC_RAYFIN_PUBLISHABLE_KEY
RAYFIN_PUBLIC_ITEM_ID	VITE_FABRIC_ITEM_ID	NEXT_PUBLIC_FABRIC_ITEM_ID
RAYFIN_PUBLIC_WORKSPACE_ID	VITE_FABRIC_WORKSPACE_ID	NEXT_PUBLIC_FABRIC_WORKSPACE_ID
RAYFIN_PUBLIC_PORTAL_URL	VITE_FABRIC_PORTAL_URL	NEXT_PUBLIC_FABRIC_PORTAL_URL

Rediger kildeværdierne i rayfin/.env, ikke den genererede fil. For at regenerere uden at udrulle:

npx rayfin env --framework vite

Brug --framework nextjs eller --framework plain for andre understøttede mappinger. Brug --output <dir> til at vælge en outputmappe eller --show til at inspicere den offentlige mapping uden at skrive. Hold genererede .env.local filer ude af versionskontrol.

Migrer et ældre miljølayout

Ældre projekter kan indeholde .env.fabric filer eller .env.fabric-<workspace> filer. Disse filer er ikke de aktive miljøfiler i det nuværende layout. Kør npx rayfin up for at bruge det nuværende miljøworkflow. Gennemgå eventuelle migrationsmeddelelser, og kopier brugerdefinerede værdier efter rayfin/.env behov. Deployeringsregistret erstatter filerne for miljøer pr. arbejdsområde. Konfigurer ikke nye apps til at være afhængige af dem.

Relateret indhold

• Opret dit første Fabric Apps-projekt
• Rayfin CLI-reference