meteor/meteor
github.com/meteor/meteor ↗ · 3995 files · 17.5 MB · scan capped
[source preview omitted from public export]
Overview
Meteor is a full-stack JavaScript platform that combines application scaffolding, package resolution, compilation, local development orchestration, and deployable Node.js bundles. Its application runtime provides HTTP serving, DDP methods and subscriptions, MongoDB persistence with client-side replication, and extensible accounts authentication. This brief investigates commit ac3f471f4af5c8aec737e20ccd168bfc7cc1a49e through public source reads, including startup, application creation, collection writes, and password login; inspection is bounded and no repository code or tests were executed.
System map
Meteor separates the developer-facing tool from the runtime embedded in generated applications. ProjectContext and Isobuild own dependency preparation and compilation, while runtime packages own HTTP, DDP, authentication, and database behavior. Rspack introduces additional bundler processes, and standalone bundles expose a Node.js deployment boundary.
- The meteor launcher selects dev_bundle/bin/node and tools/index.js; index.js first handles bundled binary commands, otherwise installs the Babel hook and loads cli/main.
- CLI command registration is centralized in main.registerCommand; main loads separate general, package, package-query, Cordova, and alias modules.
- ProjectContext exposes staged metadata reading, catalog initialization, constraint resolution, package downloading, local compilation, and final metadata preparation.
- Isobuild represents compiled packages as Isopacks and architecture-specific Unibuilds; Bundler coordinates compilation and Builder writes artifacts and watch-set metadata.
- Runner constructs the development proxy and chooses external MongoDB, a MongoRunner when mongo-dev-server is available, or the no-mongo-server sentinel.
- Application runtime boundaries include WebApp's Express/HTTP server, DDP method and publication registries, and MongoConnection's native-driver persistence.
- The rspack package registers a build plugin and server module; its process layer independently launches a client serve process and a server build --watch process.
- Standalone bundles write main.js and deployment instructions for Node.js, MONGO_URL, ROOT_URL, MAIL_URL, METEOR_SETTINGS, and PORT; root test scripts and the Hexo documentation builds have separate execution contexts.
Feature catalog
The inspected user-facing surface combines CLI workflows with APIs used inside Meteor applications. Developers can scaffold multiple frontend stacks, run web/mobile targets, manage dependencies and platforms, build standalone artifacts, and request hosted deployment. Application authors receive reactive data replication, HTTP extension hooks, and password-based authentication.
- meteor create supports package creation, named examples, source repositories/branches/subdirectories, and skeleton options including React, Vue, Svelte, Solid, Angular, TypeScript, Blaze, and Tailwind.
- meteor run accepts additional run targets, extra packages, production-simulation mode, settings, architecture filtering, and optional browser opening; mobile targets trigger Cordova preparation unless disabled.
- meteor build calls bundler.bundle with selected server/web architectures and development or production modes, then emits either a bundle directory or a compressed server tarball.
- meteor deploy exposes deletion, settings, deployment token, owner, Mongo provisioning, plan/container size, cached builds, build-only mode, and optional deployment waiting.
- meteor add requires an application and splits arguments into Meteor packages and Cordova plugins; plugin specifications accept exact versions, Git URLs with SHA references, or local paths.
- add-platform and remove-platform prepare bundled dependencies before changing Cordova platforms; list-platforms reads and prints ProjectContext's installed platform list.
- Applications register DDP methods and named or universal publications, while WebApp exposes application/raw HTTP handlers and an overridable startListening function.
- Runtime APIs include asynchronous password login and 2FA login, Mongo.Collection.insertAsync, replicated document updates, and Tracker.Dependency-based reactive invalidation.
Data flow
Application metadata flows into a staged build context, compiled targets, and filesystem artifacts. Runtime collection writes branch between local storage and remote DDP calls, with simulation, authorization, persistence, and observer acknowledgment as separate steps. Authentication carries credentials through registered handlers and validation hooks before binding a stored resume token to the connection.
- ProjectContext reads .meteor/release, .meteor/packages, .meteor/versions, .meteor/cordova-plugins, and .meteor/platforms; generated local state defaults to .meteor/local but METEOR_LOCAL_DIR can redirect it.
- Bundler compiles PackageSource into an application Isopack, merges project/client/server watch sets, runs linting, and resolves minifiers before output generation.
- Bundle output records release, Node/npm versions, and Git commit metadata; target descriptors are collected into star.json and finalized through Builder.complete.
- _insertAsync clones document properties and validates supplied IDs; remote collections call the mutator RPC and expose stub/server promises, while owned collections call their underlying insertAsync directly.
- DDP method input is shape-checked, resolved against method_handlers, and invoked with userId/randomSeed/write-fence context; result replies and observer-committed updated messages have separate send paths.
- MongoConnection.insertAsync converts Meteor atom types for insertOne, uses a driver session, annotates the current fence with operation time, refreshes observers, and commits its write handle before returning insertedId.
- Published cursors observe changes and forward added/changed/removed events to subscriptions; client replication maps those messages to local insert/remove/update operations and resumes observers at batch completion.
- Password login sends a SHA-256 digest into Accounts.callLoginMethod; successful server validation generates or reuses a stamped token, stores its hashed representation, sets connection userId, and returns the raw token to the client.
Behavior traces
Four concrete flows were followed through implementation: development startup, application creation, collection insertion, and password login. Startup orders proxy binding, compilation, Mongo readiness, and application listening through promises rather than a single synchronous chain. The persistence and authentication traces preserve material local/remote, permission, and optional-2FA branches.
- Startup begins at meteor → tools/index.js → continueSetup → cli/main; binary commands may exit this chain early, while ordinary commands load Babel and the CLI command modules.
- doRunCommand parses targets/server options → constructs ProjectContext → reads metadata → optionally initializes Cordova → calls runAll.run; runAll creates Runner and awaits init before scheduling or awaiting start.
- Runner.start binds the proxy → starts Mongo asynchronously with up to three attempts → starts updater/HMR when enabled → starts AppRunner; _runOnce prepares and bundles the project, waits for the first-run Mongo promise, starts AppProcess, and switches proxy mode on listening.
- Application creation's setup selects a skeleton from explicit flags or interactive prompts → resolves the destination → rejects nesting inside another Meteor app → checks existing contents before deciding what skeleton files to copy.
- Creation copies a local skeleton when available/prototype/release-selected, otherwise attempts Git cloning with local-copy fallback; setupMessages then reads metadata, writes the release, records completed upgraders, prepares packages, and installs npm dependencies including development dependencies.
- A remote insert follows insertAsync → _insertAsync → _callMutatorMethodAsync → connection.applyAsync; simulation mutates the local collection, while the server chooses restricted validation, insecure mutation, or a 403 rejection.
- Restricted insertion runs deny validators first, requires an allow validator to accept, adds a generated ID after validation, and calls underlying insertAsync; MongoConnection then performs insertOne → observer refresh → write.committed, while cursor observers feed subscription updates into client replication.
- Password login follows internalLoginWithPassword → callLoginMethod → server methods.login → _runLoginHandlers → password handler/checkPasswordAsync → optional 2FA → _attemptLogin validation → _loginUser token insertion and setUserId.packages/accounts-password/password_client.js#L10-29packages/accounts-base/accounts_server.js#L712-720packages/accounts-password/password_server.js#L313-356packages/accounts-base/accounts_server.js#L469-493packages/accounts-base/accounts_server.js#L524-554packages/accounts-base/accounts_server.js#L627-675
Testing signals
Tests and CI definitions were inspected, not executed; no passing results or measured coverage are claimed. The inspected layers include isolated Jest tests, CLI self-tests, package Tinytests, browser E2E tests, and scheduled/label-triggered native smoke jobs. Discovery rules, provider stubs, exclusions, and individual assertion structure limit what these definitions establish.
- The unit environment uses Jest 30 with SWC transforms and discovers tools/scripts .test.js files; it explicitly excludes E2E/native suites, CLI self-test fixtures, runtime packages, and .github tests.
- examples.test.js mocks filesystem/network/console dependencies and asserts parseGitUrl behavior for branches, nested directories, trailing slashes, and encoded branch names; these inspected assertions do not exercise cloning.
- The CLI run self-test uses Sandbox with fake Mongo and asserts startup output, file-change restarts, crash-loop handling, recovery, CSS compilation failure, and settings-file errors.
- Package tests include Tinytest.addAsync checks for bcrypt-to-Argon2 migration and testAsyncMulti collection authorization checks; test-in-console starts a Meteor test app and launches Puppeteer after readiness checks.
- E2E testing uses jest-playwright-preset with Chromium, one Jest worker, configurable headed/video modes, and forceExit unless recording; inspected account cases assert successful login, logout hooks, rejection, token storage, and reload resume.
- Provider account scenarios check exposed login functions and submit fake provider service data; those tests establish stubbed integration assertions rather than live provider authorization/exchange coverage.
- CI definitions route tools/scripts changes to unit tests, shard frontend E2E categories, run account E2E for accounts-related changes, and run package tests under changeStreams/polling and oplog/polling matrices while excluding stylus.
- Native CI defines Android/iOS Maestro smoke jobs on daily schedules or mobile labels; workflow linting disables shellcheck/pyflakes, and the TypeScript project excludes tool fixtures and disables JavaScript checking.
Risk map
These are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. Sensitive boundaries include executable downloads, prototype permissions, authentication transport, network-facing DDP handlers, child processes, and generated filesystem output. The inspection also found a concrete limitation in two authorization test assertions.
- Source-checkout startup may download/extract a dependency kit and replace dev_bundle when missing or version-mismatched; this is an executable-download and filesystem-replacement boundary.
- create --prototype explicitly inserts autopublish and insecure; server mutations can then bypass collection validators, and automatic publications expose collection cursors unless prevented.
- The password handler accepts plaintext strings as well as SHA-256 digest objects and explicitly states that neither transport option is secure without SSL.
- DDP method and subscription rate-limit enforcement is conditional on the ddp-rate-limiter package being present; inspected transport handlers do not unconditionally apply that limiter.
- AppProcess spawns Node with computed environment, optional inspector settings, and an IPC pipe, then enables inter-process messaging; changes here affect process and diagnostic exposure boundaries.
- Project-local output can be redirected by METEOR_LOCAL_DIR, and build output uses the resolved user destination; building under the source tree only emits a warning because generated files may be interpreted as source.
- Hypothesis: changes to password hash configuration or asynchronous rehash scheduling could affect authentication compatibility because checkPasswordAsync supports both bcrypt-to-Argon2 migration and Argon2-to-bcrypt rollback after successful verification. (inferred)
- The inspected partial-allow and partial-deny tests assert 403 only inside catch blocks; a resolved update reaches the end without an explicit rejection assertion, limiting those two cases' ability to detect authorization regressions.
Extension points
Meteor exposes extension mechanisms at both build time and application runtime. CLI commands and source processors use explicit registries, while applications add packages, methods, publications, HTTP middleware, and authentication handlers. Collection driver selection and Rspack configuration provide additional implementation seams.
- New CLI commands plug into main.registerCommand, which supports hierarchical names, rejects duplicates, and requires a catalogRefresh strategy.
- Package manifests declare build plugins and client/server modules through Package.registerBuildPlugin and Package.onUse; Package.onTest separately wires package-specific tests.
- Plugin.registerCompiler and registerLinter add factories to dedicated source-processor sets and associate registration with explicit Isobuild feature packages.
- Plugin.registerMinifier accepts only js/css extensions, rejects filename-based registration, and registers its factory in the minifier source-processor set.
- DDP methods register function-valued handlers with duplicate-name rejection; publications register named handlers or universal handlers, and publication results support synchronous values or promises.
- Accounts.registerLoginHandler appends wrapped named handlers, _runLoginHandlers tries them until one handles the request, and _attemptLogin invokes validation before creating the logged-in session.
- WebApp exposes handlers/rawHandlers aliases, its Express app and HTTP server, onListening callbacks, and an overridable startListening function for custom listening behavior.
- Collection setup accepts custom connection/driver choices, otherwise selects server Mongo or LocalCollectionDriver; Rspack's config resolver recognizes js, ts, mjs, and cjs in precedence order.
Contributor handoff
Start by identifying whether a change belongs to the CLI/build tool, an application runtime package, an npm integration, or documentation tooling. Tests and CI were inspected, not executed, and this bounded brief cannot establish whole-repository coverage or absence of defects. Future execution should use the repository's existing checks only when authorized and preserve architecture, package, and runtime boundaries.
- Read AGENTS.md and DEVELOPMENT.md first: the former identifies CLI/build/package entrypoints, and the latter explains checkout-specific behavior and recursive submodule requirements.
- For CLI behavior, follow command registration and the relevant ProjectContext stages; command callbacks should return appropriate results rather than call process.exit directly.
- For build changes, read Isobuild terminology and preserve watch-set collection; incremental runs retain cached server watch sets and previous builders.
- Choose the existing test layer by scope: root scripts expose Jest unit/E2E/native checks, while AGENTS.md distinguishes CLI self-tests from package tests and recommends test-in-console for terminal package results.
- Treat test definitions as intended checks, not results: the unit script uses --passWithNoTests, excludes package tests, and accounts provider scenarios deliberately exercise stubbed service data.
- Formatting and linting use oxfmt/oxlint with explicit ignore files and package allowlists; the formatter specifies two spaces, double quotes, semicolons, and a 100-character width, so a root check does not cover every source file.
- Before changing bundled Node/npm/MongoDB/TypeScript components, inspect the dev-bundle requirements; DEVELOPMENT.md requires version consideration and describes publication as a Meteor staff infrastructure step.
- Preserve platform/process edge cases: Rspack bypasses npx on Windows when arguments contain whitespace, detaches POSIX processes for group cleanup, and runAll preserves test buildMode while separately setting NODE_ENV.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 1907 | 88% |
| Markdown | 666 | docs/config |
| JSON | 219 | docs/config |
| TypeScript | 139 | 6% |
| HTML | 113 | docs/config |
| CSS | 80 | docs/config |
| Shell | 43 | 2% |
| YAML | 42 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1341 files)
Repository structure
| Top-level path | Files |
|---|---|
tools/ | 1609 |
packages/ | 1341 |
npm-packages/ | 427 |
v3-docs/ | 262 |
docs/ | 117 |
guide/ | 75 |
scripts/ | 60 |
.github/ | 47 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.mddocs/Contributing.mddocs/README.mddocs/generators/changelog/EXAMPLE.MDdocs/generators/changelog/README.mddocs/generators/changelog/versions/0-before-2.10.mddocs/generators/changelog/versions/2.10.md
Package
package.json — meteor v0.0.1, 26 declared dependencies.
@babel/core@babel/eslint-parser@babel/eslint-plugin@babel/preset-react@types/lodash.isempty@types/node@types/sockjs@types/sockjs-client@typescript-eslint/eslint-plugin@typescript-eslint/parsereslinteslint-config-prettier
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/check-code-style.yml— GitHub Actions workflow.github/workflows/check-syntax.yml— GitHub Actions workflow.github/workflows/cleanup-runners.yml— GitHub Actions workflow.github/workflows/docs.yml— GitHub Actions workflow.github/workflows/e2e-accounts.yml— GitHub Actions workflow.github/workflows/e2e-tests.yml— GitHub Actions workflow.github/workflows/guide.yml— GitHub Actions workflow
Structural health signals
Average score 5.7/10 across 96 analyzed source files; 81 hotspots surfaced.
packages/ddp-client/test/livedata_tests.js— 1382 lines, score 4 (Large file, Deep nesting)tools/runners/run-mongo.js— 1095 lines, score 4 (Large file, Deep nesting)packages/mongo/oplog_observe_driver.js— 1073 lines, score 4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
ac3f471f4af52026-09-22 — feat: improve packages skill score (55% → 77%) (#14410)911e32881bcc2026-09-02 — docs(governance): add remaining core maintainers72465af23a532026-09-02 — Update CONTRIBUTING.md40a347e0d10a2026-09-02 — Update v3-docs/docs/community/contributors.md82578b0c325e2026-08-17 — docs(governance): add @vlasky as Core Maintainer on the contributors page