Meteor Blaze

Blaze interfaces for Meteor 3

Blaze compiles Spacebars templates into JavaScript and updates small View regions when their reactive dependencies invalidate. Keep state, subscriptions, DOM effects, and async work owned by a template instance. Use public Template, Blaze, Spacebars, and Tracker APIs in application code.

Decision flow

1. For a new app, run meteor create --blaze <name>. Inspect the generated package.json, .meteor/packages, client entry, and rspack.config.js before changing packages or build settings.
2. Import each template's .html from the JavaScript module that registers its helpers, events, and lifecycle hooks. Import that module from the client entry graph.
3. Keep synchronous Minimongo reads in ordinary helpers. If a helper returns a Promise, render explicit pending, rejected, and resolved states.
4. Put ReactiveVar, ReactiveDict, this.autorun, and this.subscribe on the template instance. Put DOM initialization in onRendered and undo external effects in onDestroyed.
5. Pass named data and callbacks into reusable child templates. Keep publication and mutation authority on the server.
6. Identify the bundler before diagnosing refresh behavior. blaze-hot can replace templates in the Meteor-bundler graph; Rspack currently performs a full live reload for Blaze. Route general build, migration, database, or test-runner work to the owning skill.

Current scaffold

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

Meteor 3.4+ creates Blaze apps with Rspack by default. Earlier Meteor 3 releases may use the Meteor bundler. The current scaffold declares explicit client and server meteor.mainModule entries, imports .html from the client entry, enables the modern build stack, and includes blaze-html-templates, tracker, reactive-var, hot-module-replacement, blaze-hot, and rspack. Treat the generated files for the selected Meteor release as the baseline. Those packages do not enable Blaze HMR in the Rspack graph. Blaze edits there trigger a fast full page reload and reset page-local state. blaze-hot replacement behavior applies when the Meteor bundler owns the module.

Do not infer the installed Blaze runtime from the release name alone. Inspect .meteor/versions, then use the Blaze history for feature floors and compatibility changes.

Component scaffold

<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 and this.subscribe stop when the instance is destroyed. A cursor returned from a synchronous helper remains live through Minimongo. Authorization and field projection still belong in the publication.

Async helpers

Use #let when loading, rejection, and empty results must be distinct:

{{#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 stores the latest resolved value, not necessarily the result of the latest Promise. If reactive input can launch overlapping requests, use an abort signal, generation token, or serialized queue. Do not assume #let orders results. See references/spacebars-and-async.md.

Lifecycle ownership

Read references/lifecycle-and-components.md for data-context rules, callbacks, dynamic templates, DOM scoping, and cleanup patterns.

Routing boundaries

Use references/build-hmr-and-testing.md only for Blaze-specific entry imports, HMR ownership, and programmatic template tests.

Anti-patterns

• Return async Minimongo values from every helper. Prefer synchronous client reads unless the flow is already async or shared with the server.
• Read reactive data only after await without restoring the captured Tracker computation.
• Treat {{#each ...}}{{else}} as a loading indicator. The else branch also covers rejection and a resolved empty sequence.
• Pass implicit inherited contexts through reusable templates. Pass named data.
• Use global $() or document.querySelector for component DOM. Scope lookup to the template instance.
• Insert user-controlled content through triple braces or Spacebars.SafeString without trusted sanitization.
• Remove DOM nodes created by Blaze.render without calling Blaze.remove.
• Rely on private or removed UI-era APIs such as UI.body, Template.__define__, Template.__body__, Spacebars.TemplateWith, or Blaze.InOuterTemplateScope.

Authoritative resources

• Meteor Blaze tutorial
• Blaze guide
• Spacebars API
• Templates API
• Blaze programmatic API
• meteor/blaze source and tests
• references/spacebars-and-async.md
• references/lifecycle-and-components.md
• references/build-hmr-and-testing.md
• references/eval-cases.md