meteor-blaze

Meteor 3 向け Blaze インターフェース

Blaze は Spacebars テンプレートを JavaScript にコンパイルし、リアクティブな依存関係が無効になると、小さな View 領域を更新します。状態、サブスクリプション、DOM の副作用、非同期処理は、テンプレートインスタンスに所有させてください。アプリケーションコードでは、公開されている Template、Blaze、Spacebars、Tracker の API を使用してください。

判断の流れ

1. 新しいアプリの場合は、meteor create --blaze <name> を実行します。パッケージやビルド設定を変更する前に、生成された package.json、.meteor/packages、クライアントエントリ、rspack.config.js を確認してください。
2. 各テンプレートの .html を、そのヘルパー、イベント、ライフサイクルフックを登録する JavaScript モジュールからインポートします。そのモジュールをクライアントのエントリグラフからインポートしてください。
3. 同期的な Minimongo の読み取りは通常のヘルパーに置きます。ヘルパーが Promise を返す場合は、保留中、拒否、解決済みの状態を明示的に描画してください。
4. ReactiveVar、ReactiveDict、this.autorun、this.subscribe はテンプレートインスタンスに置きます。DOM の初期化は onRendered に置き、外部の副作用は onDestroyed で元に戻してください。
5. 再利用可能な子テンプレートには、名前付きデータとコールバックを渡します。公開と変更の権限はサーバー側に置いてください。
6. 更新動作を診断する前に、バンドラーを特定してください。blaze-hot は Meteor バンドラーのグラフ内でテンプレートを置き換えられますが、Rspack は現在、Blaze に対して完全なライブリロードを実行します。一般的なビルド、移行、データベース、テストランナーに関する作業は、それを担当するスキルに振り分けてください。

現在のスキャフォールド

meteor create --blaze my-app
cd my-app
meteor

Meteor 3.4 以降では、Blaze アプリはデフォルトで Rspack を使用して作成されます。それより前の Meteor 3 リリースでは、Meteor バンドラーが使われる場合があります。現在のスキャフォールドでは、クライアントとサーバーの meteor.mainModule エントリを明示的に宣言し、クライアントエントリから .html をインポートし、最新のビルドスタックを有効にして、blaze-html-templates、tracker、reactive-var、hot-module-replacement、blaze-hot、rspack を含めています。選択した Meteor リリースで生成されるファイルを基準にしてください。これらのパッケージは、Rspack のグラフ内で Blaze の HMR を有効にするものではありません。そこでの Blaze の編集は、ページ全体の高速なリロードを引き起こし、ページローカルの状態をリセットします。blaze-hot による置き換えの動作は、Meteor バンドラーがモジュールを管理している場合に適用されます。

リリース名だけから、インストール済みの Blaze ランタイムを推測しないでください。.meteor/versions を確認してから、機能の最低要件と互換性の変更について、Blaze の履歴を参照してください。

Meteor 3.6-beta.0 の meteor create --pwa <name> は、依存関係のないサービスワーカーを備えた、インストール可能な Blaze/Rspack ウェブアプリを提供します。オフライン時の Meteor データやネイティブバイナリは提供しません。キャッシュやスコープを変更する前に、PWA の境界をお読みください。

コンポーネントのスキャフォールド

<template name="taskList">
  <label>
    <input type="checkbox" class="js-show-done">
    Show completed
  </label>

  {{#if Template.subscriptionsReady}}
    {{#each task in tasks}}
      {{> taskRow task=task}}
    {{else}}
      <p>No tasks.</p>
    {{/each}}
  {{else}}
    <p>Loading...</p>
  {{/if}}
</template>

import { Template } from "meteor/templating";
import { ReactiveVar } from "meteor/reactive-var";
import { Tasks } from "/imports/api/tasks";
import "./task-list.html";

Template.taskList.onCreated(function () {
  this.showDone = new ReactiveVar(false);
  this.autorun(() => {
    this.subscribe("tasks.list", { showDone: this.showDone.get() });
  });
});

Template.taskList.helpers({
  tasks() {
    const showDone = Template.instance().showDone.get();
    return Tasks.find(showDone ? {} : { done: false }, {
      sort: { createdAt: -1 },
    });
  },
});

Template.taskList.events({
  "change .js-show-done"(event, instance) {
    instance.showDone.set(event.currentTarget.checked);
  },
});

this.autorun と this.subscribe は、インスタンスが破棄されると停止します。同期待ちのヘルパーが返すカーソルは、Minimongo を通じてライブ状態を維持します。認可とフィールドの射影は、引き続きパブリケーション側の責任です。

非同期ヘルパー

読み込み中、拒否、空の結果を区別する必要がある場合は、#let を使用します。

{{#let profile=loadProfile}}
  {{#if @pending "profile"}}<p>Loading...</p>{{/if}}
  {{#if @rejected "profile"}}<p>Could not load profile.</p>{{/if}}
  {{#if @resolved "profile"}}
    {{> profileCard profile=profile}}
  {{/if}}
{{/let}}

Spacebars が保持するのは、最新の Promise の結果とは限らず、最後に解決された値です。リアクティブな入力によって重複するリクエストが開始される可能性がある場合は、中止シグナル、世代トークン、または直列化キューを使用してください。#let が結果の順序を制御すると想定しないでください。references/spacebars-and-async.md を参照してください。

ライフサイクルの所有権

リソース	作成	破棄
ReactiveVar または ReactiveDict	onCreated	手動での破棄は不要
リアクティブな処理	this.autorun	インスタンスとともに自動で破棄
サブスクリプション	this.subscribe	インスタンスとともに自動で破棄
DOM ウィジェット	onRendered。多くの場合、Tracker.afterFlush の後	onDestroyed でウィジェット固有の後処理
ウィンドウ、ドキュメント、タイマー、オブザーバー	ライフサイクルコールバック	onDestroyed で明示的に削除、クリア、切断、または停止
プログラムによる Blaze View	Blaze.render または Blaze.renderWithData	Blaze.remove(view)

データコンテキストのルール、コールバック、動的テンプレート、DOM のスコープ設定、クリーンアップのパターンについては、references/lifecycle-and-components.md を参照してください。

ルーティングの境界

リクエスト	ルート
新規の Blaze UI、Spacebars、テンプレートのライフサイクル、非同期レンダリング	このスキル
Rspack または SWC の一般的なセットアップと設定ヘルパー	meteor-modern-build-stack
既存のアプリを Rspack に変換する	migrate-to-rspack
Meteor 2 から Meteor 3 への Blaze コードのアップグレード	migrate-to-meteor-3
パブリケーションの設計またはサブスクリプションの認可	meteor-pubsub
Mongo と Minimongo の API に関する判断	meteor-mongo-minimongo
Mocha ドライバー、ブラウザーランナー、または E2E のセットアップ	meteor-testing
CSP、サニタイズのレビュー、または広範なセキュリティ強化	meteor-security

references/build-hmr-and-testing.md は、Blaze 固有のエントリーポイントのインポート、HMR の所有権、プログラムによるテンプレートテストに限って使用してください。

アンチパターン

• すべてのヘルパーから非同期の Minimongo 値を返します。すでに非同期のフローである場合や、サーバーと共有している場合を除き、同期的なクライアント側の読み取りを優先してください。
• await の後にリアクティブデータを読み取る際、捕捉した Tracker 計算を復元しません。
• {{#each ...}}{{else}} を読み込みインジケーターとして扱います。else ブランチは、拒否された場合や、解決されたシーケンスが空の場合にも実行されます。
• 再利用可能なテンプレートに暗黙的な継承コンテキストを渡します。名前付きデータを渡してください。
• コンポーネントの DOM に対して、グローバルな $() や document.querySelector を使用します。検索範囲をテンプレートインスタンス内に限定してください。
• 信頼できるサニタイズを行わずに、三重波括弧や Spacebars.SafeString を使ってユーザーが制御するコンテンツを挿入します。
• Blaze.render で作成した DOM ノードを、Blaze.remove を呼び出さずに削除します。
• UI.body、Template.__define__、Template.__body__、Spacebars.TemplateWith、Blaze.InOuterTemplateScope など、非公開または削除済みの旧 UI 時代の API に依存します。

信頼できるリソース

• Meteor Blaze チュートリアル
• Blaze ガイド
• Spacebars API
• Templates API
• Blaze プログラム API
• meteor/blaze のソースとテスト
• references/spacebars-and-async.md
• references/lifecycle-and-components.md
• references/build-hmr-and-testing.md
• references/eval-cases.md