meteor-react

React interfaces for Meteor 3

React owns rendering and local UI state; Meteor owns reactive data and the build handoff. Components consume authorized data and invoke methods. Publications and methods remain the server authority.

Decision flow

1. For a new JavaScript app, run meteor create --react <name>; React is also

the default skeleton. For TypeScript and TSX, run meteor create --typescript <name>.

1. Inspect package.json, .meteor/packages, .meteor/versions, the client

entry, and rspack.config.*. Skeletons and react-meteor-data versions can change independently of this skill.

1. Mount one React root from Meteor.startup with createRoot.
2. Pick one react-meteor-data surface for a component:

• Classic hooks for explicit loading UI and synchronous Minimongo reads.
• Suspense hooks only when an upstream Suspense fallback and rejection

boundary already own the pending and error states.

1. Use useSubscribe for readiness, useFind for reactive lists with stable

document references, and useTracker for other Tracker values.

1. Keep React-specific Rspack rules here. Route aliases, loaders, code

splitting, cache, output, or migration work to the build skills.

1. Test UI behavior in a browser-backed client suite and always unmount the

rendered root so Tracker computations and subscriptions can stop.

Current scaffold

meteor create --react my-app
cd my-app
meteor

Current Meteor 3.4+ scaffolds use Rspack and react-meteor-data. Inspect .meteor/versions: Meteor 3 requires 3.0.0+, these examples target 4.0.1, and references/react-meteor-data.md records feature floors.

import { Meteor } from "meteor/meteor";
import { createRoot } from "react-dom/client";
import { App } from "/imports/ui/App";
import "/imports/ui/styles.css";

Meteor.startup(() => {
  const container = document.getElementById("react-target");
  if (!container) throw new Error("Missing #react-target");
  createRoot(container).render(<App />);
});

TypeScript uses client/main.tsx, a tsconfig.json, and usually rspack.config.ts. Meteor discovers that TypeScript config directly.

Reactive data selection

Classic list scaffold:

import { useFind, useSubscribe } from "meteor/react-meteor-data";
import { Tasks } from "/imports/api/tasks";

export function TaskList({ listId }) {
  const isLoading = useSubscribe("tasks.byList", listId);
  const tasks = useFind(
    () => Tasks.find({ listId }, { sort: { createdAt: -1 } }),
    [listId],
  );

  if (isLoading()) return <p>Loading...</p>;
  if (tasks.length === 0) return <p>No tasks.</p>;
  return <ul>{tasks.map((task) => <li key={task._id}>{task.title}</li>)}</ul>;
}

useFind owns cursor observation and updates only changed document references. Use useTracker when a transformed aggregate is clearer. Read references/react-meteor-data.md before tuning dependencies or skipUpdate.

Suspense and async reactivity

Suspense imports change signatures; they are not drop-in replacements:

import { Suspense } from "react";
import { useFind, useSubscribe } from "meteor/react-meteor-data/suspense";
import { Tasks } from "/imports/api/tasks";

function TaskList({ listId }) {
  useSubscribe("tasks.byList", listId);
  const tasks = useFind(Tasks, [
    { listId },
    { sort: { createdAt: -1 } },
  ], [listId]);
  return <ul>{tasks.map((task) => <li key={task._id}>{task.title}</li>)}</ul>;
}

export function TaskScreen({ listId }) {
  return (
    <AppErrorBoundary>
      <Suspense fallback={<p>Loading...</p>}>
        <TaskList listId={listId} />
      </Suspense>
    </AppErrorBoundary>
  );
}

Treat Suspense useSubscribe as a suspension-only call. In the currently audited package, its declared return type and runtime value disagree, so do not consume the return. Read references/suspense-and-async.md for stable keys, rejections, SSR, and Tracker.withComputation after await.

Build and refresh ownership

Rspack detects React from the app's npm dependencies, enables JSX or TSX SWC parsing, and installs and injects React Refresh for client development. A normal React Rspack app does not add the refresh plugin manually.

Keep rspack.config.* minimal. The generated JavaScript skeleton demonstrates an optional SVGR rule; the TypeScript skeleton demonstrates type checking. Compose custom rules through defineConfig from @meteorjs/rspack without replacing Meteor's SWC defaults.

For React Compiler, the Meteor 3.6-beta.0 pairing supports SWC; older pairings can retain Babel. Read compiler setup for React-version targets and runtime requirements.

If edits reload the page or reset component state, first determine which bundler compiled the module. In a Rspack client graph, inspect React Refresh boundaries and avoid a second react-fast-refresh stack. In a Meteor-bundler graph, verify hot-module-replacement and the bundled React Fast Refresh integration. See references/build-refresh-and-testing.md.

Mutations and tests

Call Meteor.callAsync from event handlers, model pending and rejection in React state, and leave validation and authorization inside the method. Do not write sensitive collections directly from a component.

For tests, separate a presentational component that accepts data as props from the hook-owning container. Unit-test the former with the project's existing React test library. Test the latter in a browser client with controlled Minimongo or a real publication. Assert rendered behavior, not the number of reactive-function calls, because React can discard work and invoke initial render logic more than once.

Anti-patterns

• Treat classic isLoading as a boolean. It is a function and must be called.
• Pass Tasks.find().fetch() to useFind. Return the cursor.
• Put a subscription inside a useFind factory. Subscribe separately.
• Call React state setters, methods, analytics, or arbitrary effects inside a

useTracker reactive function.

• Force every classic component onto Suspense. Both surfaces remain useful.
• Reuse a generic Suspense key for unrelated mounted computations.
• Read a Tracker source only after await without restoring the computation.
• Add @rspack/plugin-react-refresh to project config when Meteor already

injected it.

• Replace all Rspack SWC options to add one React transform. Extend them.
• Mock away all Meteor data behavior in a component integration test.

Authoritative resources

• Meteor React tutorial
• `react-meteor-data` documentation
• `meteor/react-packages` source and changelog
• Meteor Rspack integration
• React `createRoot`
• React Suspense
• references/eval-cases.md