Fabric Appsのプロジェクトは、バックエンドの設定、データモデル、フロントエンドコードを分離しています。 正確なレイアウトはテンプレートによって異なります。 デフォルトの blankapp テンプレートは Universal Appになります。これは npm ワークスペースで、フロントエンド、データ、共有パッケージが別々です。
フォルダー レイアウト
デフォルトのユニバーサルアプリのスキャフォールドは以下の構造を持っています。
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
| 場所 | 所有権 |
|---|---|
rayfin/ |
バックエンドの設定とアクティブな環境値。 |
packages/frontend/ |
ブラウザUI、クライアント初期化、フロントエンドビルド。 |
packages/data/ |
装飾されたランタイムエンティティクラスとスキーマ登録。 |
packages/shared/ |
フロントエンドと共有される同型レコード契約とスキーマタイプ。 ここにバックエンド専用のコードを載せないでください。 |
ベーススキャフォールドではデータは無効化されています。 アプリで永続記録が必要なときに有効にしてください:
npm run pack:add -- data-modeling
この機能はスターター エンティティと共有コントラクトを追加し、データ サービスを有効にします。 エンティティオーサリングおよびMSSQL方言の設定については、「 データモデルの定義」を参照してください。
フラットテンプレートの代替
一部のテンプレートや既存のアプリでは、フロントエンドコードがルート src/に、エンティティが rayfin/data/、スキーマタイプのマップが rayfin/data/schema.tsに配置されたフラットレイアウトを使用しています。 このレイアウトは現在も有効です。 ファイルを移動したり、他のテンプレートに合わせるために重複パッケージを作成したりしないでください。
rayfin/rayfin.ymlのサービスパスを読んで、プロジェクトが実際にビルドするディレクトリを見つけてください。
主要な構成ファイル
rayfin/rayfin.yml
rayfin/rayfin.yml ファイルは、Fabric Apps バックエンドのメイン構成ファイルです。 ローカル開発中に実行されるサービスを制御し、動的構成値の環境変数補間をサポートします。
デフォルトのワークスペースは明示的なサービスパスを使用しています。 以下の例は、データベースが必要なアプリに対してDataを有効にしたこれらのパスを示しています:
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の値はプロジェクト ルートからの相対値です。 ビルドコマンドは解決されたサービスディレクトリから実行されます。 関数の初期化は、services.functions.pathのようなワークスペースパッケージを選択する際に、packages/functionsも記録します。 フラットプロジェクトは既存の rayfin/functions 場所を利用できます。
関数の使用を参照してください。
構成には、次のキー フィールドが含まれます。
最上位レベルのフィールド
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
id |
string |
はい | Docker Compose のプロジェクト名および Fabric アイテム識別子として使用されるプロジェクトスラッグです。 |
name |
string |
はい | 人間が判読できるプロジェクトの表示名。 |
version |
string |
はい | プロジェクトのバージョン(semver)。 |
services |
object |
はい | サービス構成ブロック。 |
services.data
| フィールド | タイプ | デフォルト | 説明 |
|---|---|---|---|
enabled |
boolean |
false |
データ サービスを有効にします。 |
dialect |
string |
— | Fabric 内の SQL データベースにはmssqlを使います。 データが有効な場合は必須です。 |
path |
string |
— | プロジェクトルートに対するデータパッケージディレクトリ(例: packages/data)。 フラットテンプレートは rayfin/dataを使えます。 |
buildCommand |
string |
— | 設定されたデータ パッケージのビルド コマンド |
services.storage
| フィールド | タイプ | デフォルト | 説明 |
|---|---|---|---|
enabled |
boolean |
false |
リモートファイルストレージを有効にしてください。
services.data.enabled: true が必要です。 |
path |
string |
. |
アプリのrootからの相対的なストレージプロジェクトのroot たとえば、「 packages/storage 」のように入力します。 |
ストレージは開発中を含めてFabric上で動作します。
ローカルストレージサービスやエミュレーターは使っていません。
構成済みストレージプロジェクトのルートで rayfin/storage/ 配下のフォルダとそのアクセスポリシーを宣言してください。
セットアップ手順については「 ファイルの保存と管理」をご覧ください。
services.auth
| フィールド | タイプ | デフォルト | 説明 |
|---|---|---|---|
enabled |
boolean |
false |
認証サービスを有効にします。 |
expiryInMinutes |
number |
— | JWT トークンの有効期限 (分単位)。 |
customClaims |
Record<string, string> |
— | 発行された JWT に追加されたカスタム要求。 |
scopes |
string[] |
— | OAuth スコープ (たとえば、 ["read:data", "write:data"])。 |
refreshToken.lifetimeInDays |
number |
— | 更新トークンの有効期間 (日数)。 |
allowedRedirectUris |
string[] |
["http://localhost:5173"] |
認証コールバックに許可されたリダイレクト URI。 |
services.auth.password
| フィールド | タイプ | デフォルト | 説明 |
|---|---|---|---|
enabled |
boolean |
true |
ローカル開発で電子メールとパスワードの認証を有効にする |
services.auth.fabric
| フィールド | タイプ | デフォルト | 説明 |
|---|---|---|---|
enabled |
boolean |
false |
ブローカー認証Fabric有効にします (Microsoft Entra ID SSO)。 |
externalEntraExchange |
boolean |
— | ターゲット環境がサポートする場合、直接委任Entraトークン交換および外部親ホスト認証を有効にします。 |
services.staticHosting
| フィールド | タイプ | デフォルト | 説明 |
|---|---|---|---|
enabled |
boolean |
false |
静的コンテンツ ホスティングを有効にします。 |
path |
string |
— | プロジェクトルートから見たフロントエンドのパッケージディレクトリ |
root |
string |
— | フラット構成で使われるレガシーフロントエンドルート。 |
folder |
string |
"dist" |
解決済みのフロントエンドパスに対する、構築された静的アセットを含むディレクトリ。 |
buildCommand |
string |
— | パッケージ化する前に実行するシェル コマンド (たとえば、 npm run build)。 |
indexDocument |
string |
— | ルート パスに対して提供される既定のドキュメント (たとえば、 index.html)。 |
ヒント
すべての文字列値は、 ${VAR} 構文と ${VAR:-default} 構文を使用した環境変数補間をサポートします。 変数は、 rayfin/.env とシェル環境から解決されます。
rayfin/.env
rayfin/.envファイルにはアクティブなランタイムおよびデプロイメントの値が含まれており、補間を通じてrayfin.ymlに値を提供します。 CLIはアクティブバックエンドに対してフレームワーク中立の RAYFIN_PUBLIC_* 値を書き込みます。 そのプレフィックスを持つ変数のみが、生成されるフロントエンド環境ファイルに含まれます。 秘密をRAYFIN_PUBLIC_*変数に絶対に入れないでください。
ソース管理に rayfin/.env を含めないでください。
rayfin/.env.exampleを使って、期待される変数をプレースホルダーでドキュメント化しましょう。
rayfin/.deployments.json
デプロイレジストリは、プロジェクトのデプロイメントのためのバックエンドURL、ホスティングURL、アイテムID、ワークスペースIDを記録します。 フロントエンド環境ファイルではありません。 ソース管理から外しておきましょう。
npx rayfin up listを使って記録された展開を一覧表示し、npx rayfin up switch <name>を使ってアクティブな展開を切り替え、その環境値を再生成します。
rayfin/tsconfig.json
テンプレートはレイアウトのTypeScript設定を提供します。 ワークスペースパッケージは独自の設定とプロジェクト参照を持ち、フラットテンプレートは rayfin/tsconfig.jsonを通じてエンティティをコンパイルできます。 スキャフォールドの参照設定を保持し、単一のルートコンパイルを前提とするのではなく、ビルドスクリプトや型チェックスクリプトを使いましょう。
データ モデル ファイル
選択したレイアウトに合わせて、ランタイム登録とクライアント向けタイプを揃えてください。
ワークスペースエンティティと共有コントラクト
Universal Appでは、packages/data/src/ 配下のファイルは装飾されたエンティティクラスを定義しています。
schemaによってエクスポートされたpackages/data/src/index.ts配列にランタイムクラスを登録します。
UniversalAppSchemaで、一致するレコードインターフェースとpackages/shared/src/index.ts型を維持してください。 フロントエンドは装飾されたバックエンドクラスをインポートする代わりに、@rayfin-app/shared からこのコントラクトをインポートします。
フラット テンプレート エンティティ
フラットテンプレートでは、rayfin/data/*.ts はエンティティを定義し、rayfin/data/schema.ts は client.data.<Entity> 用にエンティティ名を型にマッピングします。 そのテンプレートで提供されている登録メカニズムに従ってください。
ストレージ ファイル
ストレージプロジェクトのルートにあるオプションの rayfin/storage/ フォルダには、クラスが @blob() で装飾され、それらを登録する schema.ts ファイルが入っています。
services.storage.pathを省略したり.に設定したら、これらのファイルをアプリのrayfin/storage/フォルダに追加してください。
例えば、services.storage.path: packages/storage これらのファイルを packages/storage/rayfin/storage/ 配下に配置します。
Fabricにデプロイするフォルダを一覧にしたschema配列をエクスポートします。
AppStorageSchemaタイプはフォルダ名を型付きクライアントアクセス用のクラスにマッピングします。
例については、ファイルの保存と管理を参照してください。
生成された成果物
rayfin/.temp/
rayfin/.temp/ フォルダーには、開発サーバーの実行時に作成されるバックエンド成果物が生成されます。 バックエンドが古いスキーマまたは構成を使用しているように見える場合は、開発スタックを停止して再起動して、これらのファイルを再生成します。
Important
.temp/ フォルダーをリポジトリにコミットしないでください。
.gitignore ファイルに追加します。
フロントエンド構造
デフォルトのフロントエンドは packages/frontend/src/です。 フラットテンプレートはルート src/を使うことができます。
services.staticHosting.path設定はフロントエンドパッケージを識別します。
アクティブ環境とフレームワークマッピング
rayfin dev と rayfin up は、.env.local からフレームワーク固有の rayfin/.env 値を生成します。 ネストされたフロントエンドの場合、ファイルは services.staticHosting.path 配下に書き込まれ、たとえば packages/frontend/.env.local のようになります。フラットプロジェクトはプロジェクトのルートを使用します。
ソース rayfin/.env |
Vite の出力 .env.local |
Next.js での出力 .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 |
生成されたファイルではなく、 rayfin/.envのソース値を編集してください。 デプロイせずに再生成するには:
npx rayfin env --framework vite
他の対応マッピングには --framework nextjs または --framework plain を使いましょう。
--output <dir>を使って出力ディレクトリを選択するか、--showで書き込みを行わずに公開マッピングを確認できます。 生成された .env.local ファイルはソース管理から除外してください。
古い環境レイアウトを移行
古いプロジェクトには .env.fabric ファイルや .env.fabric-<workspace> ファイルが含まれていることがあります。 これらのファイルは現在のレイアウトのアクティブな環境ファイルではありません。 現在の環境ワークフローを使うために npx rayfin up を実行してください。 移行メッセージを確認し、必要に応じてカスタム値を rayfin/.env にコピーしてください。 デプロイレジストリは、ワークスペースごとの環境ファイルを置き換えます。 新しいアプリがそれらに依存するように設定しないでください。