Fabric Apps プロジェクトの構造

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 にコピーしてください。 デプロイレジストリは、ワークスペースごとの環境ファイルを置き換えます。 新しいアプリがそれらに依存するように設定しないでください。