projectstructuur Fabric Apps

Fabric Apps scheidt aparte backendconfiguratie, datamodellen en frontendcode. De exacte lay-out hangt af van het sjabloon. De standaardtemplate blankapp verwijst standaard naar Universal App, een npm-werkruimte met aparte frontend-, data- en gedeelde pakketten.

Mapindeling

De standaard Universal App-basissjabloon heeft de volgende structuur:

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
Location Eigendom
rayfin/ Backendconfiguratie en actieve omgevingswaarden.
packages/frontend/ browserinterface, clientinitialisatie en frontend-build.
packages/data/ Gedecoreerde runtime entity-klassen en schemaregistratie.
packages/shared/ Isomorfe recordcontracten en schema-types worden gedeeld met de frontend. Plaats backendcode hier niet.

Gegevens zijn uitgeschakeld in het basissjabloon. Schakel het in wanneer je app opgeslagen records nodig heeft:

npm run pack:add -- data-modeling

De mogelijkheid voegt een starterentiteit en een gedeeld contract toe en maakt de dataservice mogelijk. Voor het ontwerpen van entiteiten en MSSQL-dialectconfiguratie, zie Gegevensmodellen definiëren.

Alternatief voor flat-template

Sommige sjablonen en bestaande apps gebruiken een vlakke lay-out met frontendcode in root src/, entiteiten in rayfin/data/, en een schema-type map in rayfin/data/schema.ts. Deze indeling blijft geldig. Verplaats geen bestanden of maak geen dubbele pakketten alleen om met een ander sjabloon te matchen. Lees de servicepaden in rayfin/rayfin.yml om de mappen te vinden die je project daadwerkelijk genereert.

Sleutelconfiguratiebestanden

rayfin/rayfin.yml

Het bestand rayfin/rayfin.yml is het hoofdconfiguratiebestand voor uw back-end van Fabric Apps. Het bepaalt welke services worden uitgevoerd tijdens lokale ontwikkeling en ondersteunt omgevingsvariabele interpolatie voor dynamische configuratiewaarden.

De standaardwerkruimte gebruikt expliciete servicepaden. Het volgende voorbeeld toont die paden met Data ingeschakeld voor een app die een database nodig heeft:

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

Servicewaarden path zijn relatief aan de projectwortel. Buildcommando's draaien vanuit de opgeloste servicedirectory. Functie-initialisatie registreert services.functions.path ook wanneer het een werkruimtepakket zoals packages/functions selecteert. Flatprojecten kunnen gebruikmaken van de bestaande rayfin/functions locatie. Zie Functies gebruiken.

De configuratie bevat de volgende sleutelvelden:

Velden op het hoogste niveau

Veld Type Required Beschrijving
id string Ja Projectslug wordt gebruikt als de Docker Compose-projectnaam en de Fabric-item-id.
name string Ja Leesbare weergavenaam van het project.
version string Ja Project versie (semver).
services object Ja Blok voor serviceconfiguratie.

services.data

Veld Type Verstek Beschrijving
enabled boolean false Schakel de gegevensservice in.
dialect string — Gebruik mssql voor een SQL-database in Fabric. Vereist wanneer Data is ingeschakeld.
path string — Datapakketdirectory relatief aan de hoofdmap van het project, zoals packages/data. Platte sjablonen kunnen gebruik maken van rayfin/data.
buildCommand string — Buildcommando voor het geconfigureerde datapakket.

services.auth

Veld Type Verstek Beschrijving
enabled boolean false Schakel de verificatieservice in.
expiryInMinutes number — Vervaltijd van JWT-token in minuten.
customClaims Record<string, string> — Aangepaste claims toegevoegd aan uitgegeven JWT's.
scopes string[] — OAuth-bereiken (bijvoorbeeld ["read:data", "write:data"]).
refreshToken.lifetimeInDays number — Levensduur van het vernieuwingstoken in dagen.
allowedRedirectUris string[] ["http://localhost:5173"] Toegestane omleidings-URI's voor callbacks voor verificatie.

services.auth.password

Veld Type Verstek Beschrijving
enabled boolean true E-mail- en wachtwoordverificatie inschakelen voor lokale ontwikkeling

services.auth.fabric

Veld Type Verstek Beschrijving
enabled boolean false Schakel Fabric brokered authentication (Microsoft Entra ID SSO) in.
externalEntraExchange boolean — Schakel directe gedelegeerde Entra-tokenuitwisseling en externe-ouder-host-authenticatie in wanneer ondersteund door de doelomgeving.

services.staticHosting

Veld Type Verstek Beschrijving
enabled boolean false Schakel hosting van statische inhoud in.
path string — Frontend pakketmap ten opzichte van de projectroot.
root string — Legacy frontend-root die wordt gebruikt door platte configuraties.
folder string "dist" Map met gebouwde statische assets ten opzichte van het opgeloste frontendpad.
buildCommand string — Shell-opdracht die moet worden uitgevoerd voordat ze worden verpakt (bijvoorbeeld npm run build).
indexDocument string — Standaarddocument dat wordt geleverd voor het hoofdpad (bijvoorbeeld index.html).

Tip

Alle tekenreekswaarden ondersteunen omgevingsvariabeleinterpolatie met ${VAR} en ${VAR:-default} syntaxis. Variabelen worden opgelost uit rayfin/.env en de shell-omgeving.

rayfin/.env

Het rayfin/.env bestand bevat de actieve runtime- en deploymentwaarden en levert waarden aan rayfin.yml via interpolatie. De CLI schrijft framework-neutrale RAYFIN_PUBLIC_* waarden voor de actieve backend. Alleen variabelen met dat voorvoegsel worden opgenomen in gegenereerde frontend-omgevingsbestanden. Plaats nooit geheimen in RAYFIN_PUBLIC_* variabelen.

Houd rayfin/.env uit versiebeheer. Gebruik rayfin/.env.example om verwachte variabelen te documenteren met plaatsaanduidingen.

rayfin/.deployments.json

Het deploymentregister registreert backend-URL's, hosting-URL's, item-ID's en workspace-ID's voor de deployments van je project. Het is geen frontend omgevingsbestand. Houd het uit het broncodebeheer. Gebruik npx rayfin up list om geregistreerde deployments weer te geven en npx rayfin up switch <name> om de actieve implementatie te wisselen en de omgevingswaarden te regenereren.

rayfin/tsconfig.json

Sjablonen bieden TypeScript-configuratie voor hun layout. Werkruimtepakketten hebben hun eigen configuraties en projectreferenties; platte sjablonen kunnen entiteiten compileren via rayfin/tsconfig.json. Behoud de referenties van de scaffold en gebruik de build- en type-checkscripts in plaats van aan te nemen dat er één rootcompilatie is.

Gegevensmodelbestanden

Houd runtime-registratie en klantgerichte types afgestemd op je gekozen layout.

Workspace-entiteiten en gedeelde contracten

In de Universele App definiëren bestanden onder packages/data/src/ gedecoreerde entiteitsklassen. Registreer de runtime-klassen in de schema array die door packages/data/src/index.ts geëxporteerd wordt.

Zorg dat overeenkomstige recordinterfaces en het type UniversalAppSchema in packages/shared/src/index.ts overeenkomen. De frontend importeert dit contract vanuit @rayfin-app/shared in plaats van gedecoreerde backendklassen te importeren.

Flat-template entiteiten

In een flat template rayfin/data/*.ts definieert entiteiten en rayfin/data/schema.ts koppelt entiteitsnamen aan types voor client.data.<Entity>. Volg het registratiemechanisme dat door dat sjabloon wordt aangeboden.

Gegenereerde artefacten

rayfin/.temp/

De rayfin/.temp/ map bevat gegenereerde backend-artefacten die worden aangemaakt wanneer u de ontwikkelserver uitvoert. Als de back-end verouderde schema's of configuraties lijkt te gebruiken, moet u de ontwikkelstack stoppen en opnieuw starten om deze bestanden opnieuw te genereren.

Important

Voer de .temp/ map niet door naar uw opslagplaats. Voeg het toe aan uw .gitignore bestand.

Front-endstructuur

De standaard frontend is in packages/frontend/src/. Platte sjablonen kunnen de root src/ gebruiken. De services.staticHosting.path instelling identificeert het frontendpakket.

Actieve omgeving en raamwerkmapping

rayfin dev en rayfin up genereren raamwerk-specifieke .env.local waarden uit rayfin/.env. Voor een geneste frontend wordt het bestand geschreven onder services.staticHosting.path, zoals packages/frontend/.env.local; platte projecten gebruiken de projectwortel.

Bron in rayfin/.env Vite-uitvoer in .env.local Next.js uitvoer in .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

Bewerk de bronwaarden in rayfin/.env, niet het gegenereerde bestand. Om te regenereren zonder te deployen:

npx rayfin env --framework vite

Gebruik --framework nextjs of --framework plain voor andere ondersteunde mappings. Gebruik --output <dir> om een uitvoermap te kiezen of --show om de publieke mapping te inspecteren zonder te schrijven. Houd gegenereerde .env.local bestanden buiten versiebeheer.

Migreer een oudere omgevingsindeling

Oudere projecten kunnen .env.fabric- of .env.fabric-<workspace>-bestanden bevatten. Deze bestanden zijn niet de actieve omgevingsbestanden in de huidige lay-out. Voer npx rayfin up uit om de huidige omgevingsworkflow te gebruiken. Bekijk alle migratieberichten en kopieer aangepaste waarden naar rayfin/.env indien nodig. Het implementatieregister vervangt omgevingsbestanden per workspace. Configureer nieuwe apps niet zodanig dat ze ervan afhankelijk zijn.

Verwante inhoud

  • Laatst bijgewerkt om