フロントエンド

サーバーサイドでレンダリングされる BXM ビュー、小さな Alpine.js コンポーネント、そして Vite でコンパイルされる SCSS/JS パイプライン。

フロントエンド

全体の構成

フロントエンドはサーバーサイドレンダリングと Alpine.js のハイブリッドアプリケーションです - SPA でも、クライアントサイドルーターでもありません。

Alpine.js アーキテクチャ

App.js (entry)
  ├── Registers all Alpine stores + components
  ├── Imports Bootstrap JS + Phosphor icons + Tippy.js
  │
  ├── Stores ($store.*)
  │   ├── theme.js     → dark/light mode, syncs data-bs-theme + localStorage
  │   └── sidebar.js   → collapse/open, mobile overlay, localStorage persistence
  │
  └── Components (x-data)
      ├── auth/        → AuthForm, RegisterForm, ForgotPasswordForm, PasswordResetForm
    ├── security/     → AuditLogForm, PermissionsForm, RolesForm, UserDetailForm, UsersForm
    ├── profile/      → PasskeyOnboarding, PreferencesForm, ProfileForm
    ├── settings/     → SettingsForm, SettingsRegistryForm
    └── ui/           → Drawer, GlobalProgress, GlobalToast, Logo, MessageBox, PasswordMeter, PasswordStrength, Switch

各コンポーネントは、Alpine の x-data オブジェクトを返す単独のモジュールです。

export default () => ( {
    visible: true,
    init() {
        setTimeout( () => this.visible = false, 5000 );
    }
} );

<div x-data="messageBox" x-show="visible" x-transition>
    <!-- alert content -->
</div>

SCSS 構造

app.scss
  ├── _variables.scss   Bootstrap variable overrides
  ├── bootstrap          Full Bootstrap 5.3 import
  ├── _base.scss         CSS custom properties (light/dark theme)
  ├── components/        9 component partials
  ├── layouts/            Admin + Auth layout partials
  └── views/              Page-specific styles

Vite の設定

vite.config.mjs は coldbox-vite-plugin の coldbox() プラグインを使用しています。

• エントリポイント: resources/assets/scss/app.scss と resources/assets/js/App.js
• refresh: appRefreshPaths — ハンドラー/ビューの変更時に自動フルリロード
• publicDirectory: "public/includes" — ビルド済みアセットの出力先
• 新しい Dart Sass 向けの silenceDeprecations フラグ(import、global-builtin、color-functions、if-function)を持つ SCSS プリプロセッサ

npm run dev        # Vite dev server with HMR
npm run build      # Production build → public/includes/
npm run lint       # ESLint check on resources/assets/js
npm run lint:fix   # ESLint auto-fix
npm run lint:scss  # Stylelint on resources/assets/scss

サーバーサイドレンダリングのビューコンポーネント

これらの BXM パーシャルは app/views/_components/ 配下にあり、ColdBox の view() ヘルパーでレンダリングされます。意図的にプレゼンテーションに特化しており、args 構造体で値を渡し、ビジネスロジックはハンドラーやサービスに置いてください。

アプリケーションシェル

認証パーシャル

UI パーシャル

Alpine コンポーネントとストア

resources/assets/js/App.js は、以下の名前を Alpine にグローバルに登録します。BXM ビュー内では x-data="name" または x-data="name(...)" として使用してください。フォームコンポーネントは対応するハンドラールートへリモートリクエストを行い、そのビューから供給される CSRF トークンが fetchWithCsrf() を通じて送信されることを想定しています(ミューテーションを行うリクエストにおける CSRF を参照)。

アプリケーションシェルと認証

管理・プロフィールフォーム

UI コンポーネントとグローバル API

ソースには Header.js、Sidebar.js、TopBarNotifications.js、Logo.js も含まれています。これらのエクスポートはローカルインポートとして利用可能ですが、現在 App.js には登録されていません。グローバルな x-data コンポーネントとして使用する前に、Alpine.data() で登録してください。

ストア、ユーティリティ、マジックプロパティ

AlpinePlugins.js は Collapse、Focus、Mask、Persist をインストールします。passkeys.js はブラウザ側の WebAuthn 連携を提供します。新しく再利用可能なブラウザ API は、ここに文書化し、グローバルなものであれば App.js に登録/インポートを追加してください。

ミューテーションを行うリクエストにおける CSRF

非 GET リクエストを送信するすべてのコンポーネントアクションは、fetch() を直接呼び出すのではなく、fetchWithCsrf()(utils/csrf.js)を通ります。これは、ミューテーションを行うリクエストが構築される唯一のカプセル化された場所であり、トークン復旧の挙動 - そして後で追加されるかもしれないもの(リクエスト/レスポンスフック、グローバルヘッダー、テレメトリ)- は、状態を変更するたびにたまたま遭遇したコンポーネントごとに変更するのではなく、ここだけを変更すれば済みます。

そもそもなぜ復旧が必要なのか。 コンポーネントの csrfToken は、そのビューがレンダリングされたときに一度だけ埋め込まれます。ページが開いたままの間に、サーバーはそれを無効化できます。cbcsrf 自身のドキュメントが挙げている 2 つの方法によってです。csrfField()(すべての非表示 csrf 入力の背後にあるミックスイン)は、リクエストごとの初回使用時にセッションのトークンを強制的にローテーションするため、それをレンダリングするページ(Settings、パスキー必須ページ、認証ページ)は、開いている他のすべてのタブに座っているトークンを静かに無効化します。また、トークンはページが読み込まれてからではなく、作成されてから一定時間で期限切れになるため、トークンの寿命の終盤にレンダリングされたページは、残り数秒しかないトークンを渡される可能性があります。いずれにせよ、コンポーネントに埋め込まれたトークンは、ユーザーが入力を終える前に古くなることがあります。

契約:

export async function fetchWithCsrf( component, url, method, buildRequest ) { /* ... */ }
export async function refreshCsrfToken( component ) { /* ... */ }

• component は Alpine コンポーネントのインスタンスです(this を渡します)。可変な csrfToken プロパティを公開している必要があります - fetchWithCsrf() はそれを読み取ってリクエストを構築し、トークンが古い場合の再試行時には、refreshCsrfToken() 経由でセッションの現在のトークンで上書きします。
• buildRequest( csrfToken ) は、与えられたトークンに対するメソッド固有の RequestInit フィールド(headers、body、credentials など)を返します。再試行時にも再度呼び出されるため、一度だけ計算した値をクロージャで保持するのではなく、毎回ボディを新しく構築する必要があります - これにより、同じヘルパーが URLSearchParams、JSON.stringify()、FormData のいずれのボディも同じように扱えます。
• 403 が返された場合、fetchWithCsrf() は refreshCsrfToken() を呼び出し、実際に新しいトークンを取得できた場合は、buildRequest() を再度呼び出してリクエストを 1 回だけ再送します。2 回目の 403(例えば実際の認可失敗や、完全に期限切れになったセッション)はそのまま返されます - この場合、呼び出し元は依然として通常のエラーハンドリングを必要とします。

const response = await fetchWithCsrf( this, "/permissions", "POST", ( csrf ) => ( {
	headers : { "Content-Type": "application/x-www-form-urlencoded" },
	body    : new URLSearchParams( { permission: this.form.permission, csrf } ),
} ) );

const response = await fetchWithCsrf( this, form.action, "POST", ( csrf ) => {
	const formData = new FormData( form );
	formData.set( "csrf", csrf );
	return { body: formData, credentials: "same-origin", headers: { Accept: "application/json" } };
} );

GET/HEAD の読み取りだけが fetchWithCsrf() をスキップして fetch() を直接呼び出します - これらは CSRF トークンを持たず、それが原因で 403 になることもありません。一部の cbSecurity モジュールのエンドポイント(WebAuthn パスキーのセレモニールート)も、プレーンな fetch() で呼び出されます。これらは WebAuthn セレモニー自体を通じて認証を行い、このアプリの CSRF トークンは使わないため、このヘルパーの対象外です。resources/assets/js/components/ 内のそれ以外のすべてのミューテーションは fetchWithCsrf() を通ります。サーバーの状態を変更するリクエストを追加する新しいフォームコンポーネントでも、これと一貫性を保ってください。

アバターとブランディングロゴ

ユーザーのアバターとアプリケーションのブランディングロゴは、非公開の cbfs assets ディスク(設定 を参照)に保存され、静的ファイルとして配信されるのではなく Assets.bx(ハンドラーとルーティング を参照)によってストリーミング配信されます。

• 表示は _components/ui/avatar パーシャルを通じて行われます。hasAvatar が true のときに <img src="/avatars/:userId/:size"> をレンダリングし、そうでなければイニシャルの <span> にフォールバックします。サイドバー、トップバー、Users 一覧テーブル(サーバー側で投影される hasAvatar フィールド)に組み込まれており、Users 詳細ページではインラインで使われます(そのページのアバターは静的パーシャルではなく Alpine 駆動のサマリーカード内にあるため、user.hasAvatar に応じた x-show/x-cloak の切り替えを行います)。
• 現在のユーザー自身のアバターのアップロード/削除はプロフィールページにあり、profileForm(ProfileForm.js)が所有します。非表示のファイル入力が選択された画像を base64 データ URI として読み込み(readFileAsDataUrl())、それを POST /profile/avatar に送信します。DELETE /profile/avatar で削除します。どちらも version カウンターを増加させ、ファイルパス自体はアップロード間で変わらないため、ストリーミング配信される URL のキャッシュ無効化用クエリパラメータとして使用されます。
• ブランディングロゴは、Settings ページで logoUploader コンポーネント(LogoUploader.js)を介し、POST/DELETE /settings/logo に対して同様のアップロード/削除の扱いを受けます。アップロード時には cbAppLogo 設定のテキスト入力値をストリーミングパス(/branding/logo/lg)に置き換え、削除時には設定済みのデフォルト値を復元します — 手動の URL テキスト入力とライブ <img> プレビューは、代わりに cbAppLogo を外部 URL に向けたい人のために、これまでどおり動作し続けます。
• 両方のアップロードエンドポイントは同じ形式を受け付けます。画像はサーバー側で BaseSecureHandler.decodeDataUri() によってデコードされ、ImageService(app/models/system/ImageService.bx)によって sm/lg の JPEG(アバター)または PNG(ロゴ)バリアントにリサイズ/クロップされます。