struktur proyek Fabric Apps

Fabric Apps memisahkan konfigurasi backend, model data, dan kode frontend. Tata letak yang tepat tergantung pada template. Template default blankapp mengarah ke Universal App, workspace npm dengan frontend, data, dan paket bersama terpisah.

Tata letak folder

Scaffold Universal App default memiliki struktur sebagai berikut:

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	Kepemilikan
rayfin/	Konfigurasi backend dan nilai environment yang aktif.
packages/frontend/	Antarmuka browser, inisialisasi klien, dan pembangunan frontend.
packages/data/	Kelas entitas runtime yang didekorasi dan registrasi skema.
packages/shared/	Kontrak record isomorfik dan tipe skema yang dibagikan dengan frontend. Jangan masukkan kode khusus backend di sini.

Data dinonaktifkan di scaffold dasar. Aktifkan saat aplikasi Anda membutuhkan rekaman persisten:

npm run pack:add -- data-modeling

Kapabilitas ini menambahkan entitas starter dan kontrak bersama serta mengaktifkan layanan data. Untuk pembuatan entitas dan konfigurasi dialek MSSQL, lihat Definisikan model data.

Alternatif templat datar

Beberapa template dan aplikasi yang sudah ada menggunakan tata letak datar dengan kode frontend di root src/, entitas di rayfin/data/, dan peta tipe skema di rayfin/data/schema.ts. Tata letak ini tetap berlaku. Jangan memindahkan file atau membuat paket duplikat hanya untuk mencocokkan template lain. Baca jalur layanan di rayfin/rayfin.yml untuk menemukan direktori yang sebenarnya dibangun proyek Anda.

File konfigurasi kunci

rayfin/rayfin.yml

File rayfin/rayfin.yml adalah file konfigurasi utama untuk backend Fabric Apps Anda. Ini mengontrol layanan mana yang berjalan selama pengembangan lokal dan mendukung interpolasi variabel lingkungan untuk nilai konfigurasi dinamis.

Workspace bawaan menggunakan jalur layanan yang eksplisit. Contoh berikut menunjukkan path-path tersebut dengan Data diaktifkan untuk aplikasi yang membutuhkan 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

Nilai service path relatif terhadap root proyek. Perintah build dijalankan dari direktori layanan hasil resolusi. Functions initialization juga merekam services.functions.path saat memilih paket workspace seperti packages/functions. Proyek datar dapat menggunakan lokasi yang sudah ada rayfin/functions . Lihat Menggunakan Fungsi.

Konfigurasi mencakup bidang kunci ini:

Bidang tingkat atas

Ladang	Tipe	Required	Deskripsi
id	string	Yes	Slug proyek yang digunakan sebagai nama proyek Docker Compose dan pengidentifikasi item Fabric.
name	string	Yes	Nama tampilan proyek yang dapat dibaca manusia.
version	string	Yes	Versi proyek (semver).
services	object	Yes	Blok konfigurasi layanan.

services.data

Ladang	Tipe	Default	Deskripsi
enabled	boolean	false	Aktifkan layanan data.
dialect	string	—	Gunakan mssql untuk database SQL di Fabric. Diperlukan saat Data diaktifkan.
path	string	—	Direktori paket data relatif terhadap root proyek, seperti packages/data. Template flat dapat menggunakan rayfin/data.
buildCommand	string	—	Perintah Build untuk paket data yang dikonfigurasi.

services.auth

Ladang	Tipe	Default	Deskripsi
enabled	boolean	false	Aktifkan layanan autentikasi.
expiryInMinutes	number	—	Token JWT kedaluwarsa dalam hitung menit.
customClaims	Record<string, string>	—	Klaim kustom ditambahkan pada JWT yang dikeluarkan.
scopes	string[]	—	Cakupan akses OAuth (misalnya, ["read:data", "write:data"]).
refreshToken.lifetimeInDays	number	—	Refresh masa pakai token dalam hari.
allowedRedirectUris	string[]	["http://localhost:5173"]	URI pengalihan yang diizinkan untuk panggilan balik autentikasi.

services.auth.password

Ladang	Tipe	Default	Deskripsi
enabled	boolean	true	Mengaktifkan autentikasi email dan kata sandi untuk pengembangan lokal

services.auth.fabric

Ladang	Tipe	Default	Deskripsi
enabled	boolean	false	Aktifkan autentikasi terperantara Fabric (SSO Microsoft Entra ID).
externalEntraExchange	boolean	—	Aktifkan pertukaran token Entra yang didelegasikan langsung dan autentikasi induk-host eksternal saat didukung oleh lingkungan target.

services.staticHosting

Ladang	Tipe	Default	Deskripsi
enabled	boolean	false	Aktifkan penghostingan konten statis.
path	string	—	Direktori paket frontend relatif terhadap root proyek.
root	string	—	Root frontend lama yang digunakan oleh konfigurasi flat.
folder	string	"dist"	Direktori yang berisi aset statis hasil build relatif terhadap jalur frontend yang telah diselesaikan.
buildCommand	string	—	Perintah shell untuk dijalankan sebelum pengemasan (misalnya, npm run build).
indexDocument	string	—	Dokumen default disajikan untuk jalur akar (misalnya, index.html).

Tip

Semua nilai string mendukung interpolasi variabel lingkungan dengan ${VAR} sintaks dan ${VAR:-default} . Variabel ditentukan dari rayfin/.env dan lingkungan shell.

rayfin/.env

File rayfin/.env berisi nilai runtime aktif dan deployment serta memberikan nilai ke rayfin.yml melalui interpolasi. CLI menulis nilai yang netral terhadap framework RAYFIN_PUBLIC_* untuk backend aktif. Hanya variabel dengan awalan tersebut yang dimasukkan ke dalam file lingkungan frontend yang dihasilkan. Jangan pernah memasukkan rahasia ke dalam RAYFIN_PUBLIC_* variabel.

Jauhkan rayfin/.env dari kontrol versi. Gunakan rayfin/.env.example untuk mendokumentasikan variabel yang diharapkan dengan placeholder.

rayfin/.deployments.json

Registry deployment mencatat URL backend, URL hosting, ID item, dan ID workspace untuk deployment proyek Anda. Ini bukan file lingkungan frontend. Jauhkan dari source control. Gunakan npx rayfin up list untuk mencantumkan deployment yang tercatat dan npx rayfin up switch <name> untuk mengganti deployment aktif serta meregenerasi nilai lingkungannya.

rayfin/tsconfig.json

Template menyediakan konfigurasi TypeScript untuk tata letaknya. Paket workspace memiliki konfigurasi dan referensi proyek sendiri; template datar dapat mengompilasi entitas melalui rayfin/tsconfig.json. Simpan referensi scaffold dan gunakan skrip build serta type-check daripada mengasumsikan satu kompilasi root.

File model data

Jaga agar registrasi runtime dan tipe yang ditujukan untuk klien tetap selaras dengan tata letak yang Anda pilih.

Entitas ruang kerja dan kontrak yang dibagikan

Di Universal App, file di bawah packages/data/src/ mendefinisikan kelas entitas yang didekorasi. Daftarkan kelas runtime dalam schema array yang diekspor oleh packages/data/src/index.ts.

Pertahankan antarmuka catatan yang cocok dan tipe UniversalAppSchema di packages/shared/src/index.ts. Frontend mengimpor kontrak ini dari @rayfin-app/shared alih-alih mengimpor kelas backend yang didekorasi.

Entitas templat flat

Dalam template datar, rayfin/data/*.ts mendefinisikan entitas dan rayfin/data/schema.ts memetakan nama entitas ke tipe untuk client.data.<Entity>. Ikuti mekanisme pendaftaran yang disediakan oleh template tersebut.

Artefak yang dihasilkan

rayfin/.temp/

Folder rayfin/.temp/ berisi artefak backend yang dibuat saat Anda menjalankan server pengembangan. Jika backend tampaknya menggunakan skema atau konfigurasi kedaluarsa, hentikan dan mulai ulang tumpukan dev untuk meregenerasi file-file ini.

Important

Jangan commit folder .temp/ ke repositori Anda. Tambahkan itu ke dalam file Anda .gitignore.

Struktur frontend

Frontend bawaan berada di packages/frontend/src/. Template datar dapat menggunakan root src/. Pengaturan services.staticHosting.path ini mengidentifikasi paket frontend.

Pemetaan lingkungan aktif dan kerangka kerja

rayfin dev dan rayfin up menghasilkan nilai .env.local khusus kerangka kerja dari rayfin/.env. Untuk frontend bersarang, file ditulis di bawah services.staticHosting.path, seperti packages/frontend/.env.local; proyek datar menggunakan root proyek.

Sumber di rayfin/.env	Output Vite dalam .env.local	Next.js output dalam .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

Edit nilai sumber di rayfin/.env, bukan file yang dihasilkan. Untuk meregenerasi tanpa menerapkan:

npx rayfin env --framework vite

Gunakan --framework nextjs atau --framework plain untuk pemetaan lain yang didukung. Gunakan --output <dir> untuk memilih direktori output atau --show untuk memeriksa pemetaan publik tanpa menulis. Jangan sertakan file yang dihasilkan .env.local dalam kontrol versi.

Migrasikan tata letak lingkungan lama

Proyek lama mungkin berisi file .env.fabric atau .env.fabric-<workspace>. File-file ini bukanlah file lingkungan aktif dalam tata letak saat ini. Jalankan npx rayfin up untuk menggunakan alur kerja lingkungan saat ini. Tinjau pesan migrasi apa pun, dan salin nilai kustom ke rayfin/.env sesuai kebutuhan. Registri deployment menggantikan file lingkungan per-workspace. Jangan konfigurasikan aplikasi baru agar bergantung pada hal tersebut.

Konten terkait

• Buat proyek Fabric Apps pertama Anda
• Referensi Rayfin CLI