Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Fabric Apps trennt Backend-Konfiguration, Datenmodelle und Frontend-Code. Das genaue Layout hängt von der Vorlage ab. Die Standardvorlage blankapp wird als Universal App aufgelöst, ein npm-Arbeitsbereich mit separaten Frontend-, Daten- und gemeinsamen Paketen.
Ordnerstruktur
Das Standard-Universal-App-Gerüst hat folgende 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
| Location | Eigentum |
|---|---|
rayfin/ |
Backend-Konfiguration und aktive Umgebungswerte. |
packages/frontend/ |
Browser-UI, Client-Initialisierung und Frontend-Build. |
packages/data/ |
Dekorierte Laufzeit-Entitätsklassen und Schema-Registrierung. |
packages/shared/ |
Isomorphe Datensatzdefinitionen und Schematypen, die mit dem Frontend geteilt werden. Fügen Sie hier keinen Code ein, der nur im Backend ausgeführt wird. |
Die Daten sind im Basisgerüst deaktiviert. Aktivieren Sie es, wenn Ihre App gespeicherte Datensätze benötigt:
npm run pack:add -- data-modeling
Die Funktion fügt eine Starter-Entität und einen gemeinsamen Vertrag hinzu und aktiviert den Datendienst. Zum Erstellen von Entitäten und zur MSSQL-Dialektkonfiguration siehe Datenmodelle definieren.
Alternative zur Flat-Template
Einige Vorlagen und bestehende Apps verwenden ein flaches Layout mit Frontend-Code im Root src/, Entitäten in rayfin/data/ und eine Schema-Typ-Abbildung in rayfin/data/schema.ts. Dieses Layout bleibt gültig. Verschiebe keine Dateien oder erstelle keine doppelten Pakete, nur um mit einer anderen Vorlage zu übereinstimmen. Lies die Servicepfade in rayfin/rayfin.yml, um die Verzeichnisse zu finden, die dein Projekt tatsächlich erstellt.
Wichtige Konfigurationsdateien
rayfin/rayfin.yml
Die datei rayfin/rayfin.yml ist die Hauptkonfigurationsdatei für Ihr Fabric Apps-Back-End. Er steuert, welche Dienste während der lokalen Entwicklung ausgeführt werden und die Interpolation von Umgebungsvariablen für dynamische Konfigurationswerte unterstützt.
Der Standardarbeitsbereich verwendet explizite Servicepfade. Das folgende Beispiel zeigt jene Pfade mit aktiviertem Datenzugriff für eine App, die eine Datenbank benötigt:
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
path Servicewerte sind relativ zur Projektwurzel. Build-Befehle werden im aufgelösten Service-Verzeichnis ausgeführt. Die Funktionsinitialisierung protokolliert auch services.functions.path, wenn sie ein Arbeitsbereichspaket wie packages/functions auswählt. Flache Projekte können den bestehenden rayfin/functions Standort nutzen. Siehe Funktionen verwenden.
Die Konfiguration umfasst die folgenden Schlüsselfelder:
Felder auf oberster Ebene
| Feld | Typ | Erforderlich | Description |
|---|---|---|---|
id |
string |
Ja | Projekt-Slug, der als Docker-Compose-Projektname und Fabric-Elementkennung verwendet wird. |
name |
string |
Ja | Für Menschen lesbarer Projektanzeigename. |
version |
string |
Ja | Projektversion (semver). |
services |
object |
Ja | Konfigurationsblock des Dienstes. |
services.data
| Feld | Typ | Vorgabe | Description |
|---|---|---|---|
enabled |
boolean |
false |
Aktivieren Sie den Datendienst. |
dialect |
string |
— | Verwenden Sie mssql für eine SQL-Datenbank in Fabric. Erforderlich, wenn Data aktiviert ist. |
path |
string |
— | Datenpaketverzeichnis relativ zur Projektwurzel, wie packages/data. Flache Vorlagen können rayfin/dataverwendet werden. |
buildCommand |
string |
— | Build-Befehl für das konfigurierte Datenpaket. |
services.auth
| Feld | Typ | Vorgabe | Description |
|---|---|---|---|
enabled |
boolean |
false |
Aktivieren Sie den Authentifizierungsdienst. |
expiryInMinutes |
number |
— | JWT-Token läuft in Minuten ab. |
customClaims |
Record<string, string> |
— | Benutzerdefinierte Ansprüche, die zu ausgestellten JWTs hinzugefügt wurden. |
scopes |
string[] |
— | OAuth-Bereiche (z. B ["read:data", "write:data"]. ). |
refreshToken.lifetimeInDays |
number |
— | Aktualisierung der Tokenlebensdauer in Tagen. |
allowedRedirectUris |
string[] |
["http://localhost:5173"] |
Zulässige Umleitungs-URIs für Authentifizierungsrückrufe. |
services.auth.password
| Feld | Typ | Vorgabe | Description |
|---|---|---|---|
enabled |
boolean |
true |
Aktivieren der E-Mail- und Kennwortauthentifizierung für die lokale Entwicklung |
services.auth.fabric
| Feld | Typ | Vorgabe | Description |
|---|---|---|---|
enabled |
boolean |
false |
Aktivieren sie Fabric brokered authentication (Microsoft Entra ID SSO). |
externalEntraExchange |
boolean |
— | Aktivieren Sie den direkten delegierten Entra-Tokenaustausch und die Authentifizierung über externen übergeordneten Host, wenn dies von der Zielumgebung unterstützt wird. |
services.staticHosting
| Feld | Typ | Vorgabe | Description |
|---|---|---|---|
enabled |
boolean |
false |
Aktivieren Sie statisches Inhaltshosting. |
path |
string |
— | Frontend-Paketverzeichnis relativ zur Projektwurzel. |
root |
string |
— | Legacy-Frontend-Root, das von flachen Konfigurationen genutzt wird. |
folder |
string |
"dist" |
Verzeichnis, das gebaute statische Assets relativ zum gelösten Frontend-Pfad enthält. |
buildCommand |
string |
— | Shell-Befehl, der vor dem Verpacken ausgeführt werden soll (z. B npm run build. ). |
indexDocument |
string |
— | Standarddokument, das für den Stammpfad bereitgestellt wird (z. B index.html. ). |
Tipp
Alle Zeichenfolgenwerte unterstützen die Interpolation von Umgebungsvariablen mit ${VAR} und ${VAR:-default} syntax. Variablen werden aus rayfin/.env und der Shell-Umgebung ermittelt.
rayfin/.env
Die rayfin/.env Datei enthält die aktiven Laufzeit- und Bereitstellungswerte und liefert durch Interpolation Werte an rayfin.yml . Die CLI schreibt framework-neutrale RAYFIN_PUBLIC_* Werte für das aktive Backend. Nur Variablen mit diesem Präfix werden in generierte Frontend-Umgebungsdateien projiziert. Speichern Sie niemals Geheimnisse in RAYFIN_PUBLIC_* Variablen.
rayfin/.env aus der Versionsverwaltung heraushalten. Verwenden Sie rayfin/.env.example, um erwartete Variablen mit Platzhaltern zu dokumentieren.
rayfin/.deployments.json
Das Deployment-Register speichert Backend-URLs, Hosting-URLs, Item-IDs und Workspace-IDs für die Deployments Ihres Projekts. Es handelt sich nicht um eine Frontend-Umgebungsdatei. Halte es aus der Versionsverwaltung heraus. Verwenden Sie npx rayfin up list, um aufgezeichnete Deployments aufzulisten, und npx rayfin up switch <name>, um das aktive Deployment zu wechseln und dessen Umgebungswerte neu zu generieren.
rayfin/tsconfig.json
Vorlagen bieten eine TypeScript-Konfiguration für das Layout. Workspace-Pakete haben eigene Konfigurationen und Projektreferenzen; Flat-Templates können Entitäten über rayfin/tsconfig.json kompilieren. Bewahren Sie die Referenzen des Scaffolds und verwenden Sie dessen Build- und Typprüfskripte, anstatt von einer einzelnen Root-Kompilierung auszugehen.
Datenmodelldateien
Halten Sie die Laufzeitregistrierung und kundenorientierte Typen für Ihr gewähltes Layout ausgerichtet.
Workspace-Entitäten und freigegebene Verträge
In der Universal App definieren Dateien unter packages/data/src/ dekorierte Entity-Klassen. Registrieren Sie die Laufzeitklassen im von packages/data/src/index.ts exportierten schema-Array.
Behalten Sie passende Datensatzschnittstellen und den UniversalAppSchema Typ in packages/shared/src/index.ts bei. Das Frontend importiert diesen Vertrag aus @rayfin-app/shared statt dekorierte Backend-Klassen zu importieren.
Entitäten mit Flat-Template
In einer flachen Vorlage definiert rayfin/data/*.ts Entitäten, und rayfin/data/schema.ts bildet Entitätsnamen auf Typen für client.data.<Entity> ab. Folgen Sie dem von dieser Vorlage bereitgestellten Registrierungsmechanismus.
Generierte Artefakte
rayfin/.temp/
Der rayfin/.temp/ Ordner enthält generierte Back-End-Artefakte, die beim Ausführen des Entwicklungsservers erstellt werden. Wenn das Back-End offenbar ein veraltetes Schema oder eine veraltete Konfiguration verwendet, beenden und starten Sie den Dev-Stack neu, um diese Dateien neu zu generieren.
Important
Übernehmen Sie den .temp/ Ordner nicht in Ihr Repository. Fügen Sie sie Zu Ihrer .gitignore Datei hinzu.
Front-End-Struktur
Das Standard-Frontend ist in packages/frontend/src/. Flat-Templates können root src/ verwenden. Die Einstellung services.staticHosting.path identifiziert das Frontend-Paket.
Aktive Umgebung und Framework-Mapping
rayfin dev und rayfin up generieren rahmenspezifische .env.local Werte aus rayfin/.env. Für ein verschachteltes Frontend wird die Datei unter services.staticHosting.pathgeschrieben, zum Beispiel packages/frontend/.env.local; flache Projekte verwenden die Projektwurzel.
Quelle in rayfin/.env |
Vite-Ausgabe in .env.local |
Die Next.js-Ausgabe 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 |
Bearbeite die Quellwerte in rayfin/.env, nicht in der generierten Datei. Ohne Bereitstellung neu generieren:
npx rayfin env --framework vite
Verwenden Sie --framework nextjs oder --framework plain für andere unterstützte Mappings. Verwenden Sie --output <dir>, um ein Ausgabeverzeichnis auszuwählen oder --show, um das öffentliche Mapping einzusehen, ohne zu schreiben. Halten Sie generierte .env.local Dateien aus der Quellcodeverwaltung heraus.
Migrieren Sie ein älteres Umgebungslayout
Ältere Projekte könnten .env.fabric- oder .env.fabric-<workspace>-Dateien enthalten. Diese Dateien sind nicht die aktiven Umgebungsdateien im aktuellen Layout. Führe npx rayfin up aus, um den aktuellen Umgebungs-Workflow zu verwenden. Überprüfen Sie alle Migrationsnachrichten und kopieren Sie benutzerdefinierte Werte bei Bedarf in rayfin/.env. Das Bereitstellungsregister ersetzt die Umgebungsdateien pro Arbeitsbereich. Konfigurieren Sie keine neuen Apps so, dass sie von ihnen abhängig sind.