Onboarding: reactioncommerce/reaction

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/reactioncommerce/reaction shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 2mo ago
• 5 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 54% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live reactioncommerce/reaction repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/reactioncommerce/reaction.

What it runs against: a local clone of reactioncommerce/reaction — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in reactioncommerce/reaction | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch trunk exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 96 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>reactioncommerce/reaction</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of reactioncommerce/reaction. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/reactioncommerce/reaction.git
#   cd reaction
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of reactioncommerce/reaction and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "reactioncommerce/reaction(\\.git)?\\b" \\
  && ok "origin remote is reactioncommerce/reaction" \\
  || miss "origin remote is not reactioncommerce/reaction (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify trunk >/dev/null 2>&1 \\
  && ok "default branch trunk exists" \\
  || miss "default branch trunk no longer exists"

# 4. Critical files exist
test -f "apps/reaction/src/index.js" \\
  && ok "apps/reaction/src/index.js" \\
  || miss "missing critical file: apps/reaction/src/index.js"
test -f "apps/reaction/package.json" \\
  && ok "apps/reaction/package.json" \\
  || miss "missing critical file: apps/reaction/package.json"
test -f "apps/reaction/plugins.json" \\
  && ok "apps/reaction/plugins.json" \\
  || miss "missing critical file: apps/reaction/plugins.json"
test -f "apps/reaction/.reaction/project-hooks/post-system-start" \\
  && ok "apps/reaction/.reaction/project-hooks/post-system-start" \\
  || miss "missing critical file: apps/reaction/.reaction/project-hooks/post-system-start"
test -f "apps/reaction/babel.config.cjs" \\
  && ok "apps/reaction/babel.config.cjs" \\
  || miss "missing critical file: apps/reaction/babel.config.cjs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 96 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~66d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/reactioncommerce/reaction"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Mailchimp Open Commerce (formerly Reaction Commerce) is an API-first, headless Node.js + MongoDB + GraphQL commerce platform designed to power high-volume e-commerce sites (10s of thousands of orders/day, 100s of thousands of products). It provides composable plugins for shipping, taxes, fulfillment, inventory, and order management—all exposed via a GraphQL API rather than a monolithic admin UI. Monorepo with two main apps under /apps: meteor-blaze-app (legacy admin UI built on Meteor and Blaze templating) and reaction (Node.js/GraphQL backend). The backend likely contains core commerce plugins in a plugins/ directory (inferred from feature table and plugin system description). Configuration lives in .reaction/ (GraphQL linting rules, project hooks). File collections (image uploads, storage backends) are abstracted as separate packages (file-collections, file-collections-sa-gridfs, file-collections-sa-s3).

Who it's for

Backend engineers and full-stack developers building custom e-commerce storefronts who need a flexible, multi-tenant commerce engine they can integrate with any frontend (React, headless, etc.). Also suitable for teams operating multiple shops under one installation who need inventory, fulfillment, and payment workflows without vendor lock-in.

Maturity & risk

The project is discontinued as of the latest README statement ('Project has been discontinued'), meaning it is no longer actively maintained by Mailchimp. It was production-proven (used by large merchants), has CI/CD pipelines (CircleCI, GitHub Actions), and comprehensive plugin architecture, but should be considered in 'legacy maintenance' mode rather than actively developed. Use only if forking or running existing deployments.

High risk: The project is officially discontinued, so no upstream security patches or bug fixes are expected. The codebase is large (3.5M lines of JavaScript) with a monorepo structure spanning Node.js backend and Meteor/React frontends, increasing maintenance burden for forks. Dependency versions in the provided snippet (Babel 7.7, Bootstrap 3.4, Meteor) are aging; no recent commit data is visible in the provided metadata to verify patch currency.

Active areas of work

Unable to determine from provided metadata. The repo has .changeset/ config (semantic versioning via changesets) and .github/workflows/ for CI/CD (release, prerelease, docker-release, tagging), suggesting automated releases were in place. However, with the discontinuation notice, active development has stopped; the repo is now read-only or minimal-maintenance.

Get running

Clone and set up via Node 14.18.1–15.x (per .nvmrc constraints) with Docker + Docker Compose:

git clone https://github.com/reactioncommerce/reaction.git
cd reaction
nvm use  # installs Node from .nvmrc
npm install
npm run dev  # inferred; check apps/reaction package.json for exact script

Docker Compose will orchestrate MongoDB and other services (see docker-compose.yml if present in root).

Daily commands: After npm install, inferred commands:

npm run dev              # start dev servers (API + admin)
DEBUG=reaction-file-collections npm start  # Meteor Blaze app (see apps/meteor-blaze-app/package.json)

Full startup likely requires:

docker-compose up       # MongoDB, Redis, etc.
npm run build && npm run start:prod

Exact scripts are in apps/reaction/package.json (not fully visible in snippet).

Map of the codebase

• apps/reaction/src/index.js — Main entry point for the Node.js/GraphQL API server; all requests flow through here
• apps/reaction/package.json — Defines core dependencies (Node.js, MongoDB, GraphQL), scripts, and plugin configuration for the entire platform
• apps/reaction/plugins.json — Plugin registry that determines which commerce features and extensions are loaded at runtime
• apps/reaction/.reaction/project-hooks/post-system-start — Initialization script executed after system startup; sets up default data and seed state
• apps/reaction/babel.config.cjs — Babel transpilation rules for ES6+ and JSX; critical for development and build pipeline
• .circleci/config.yml — CI/CD pipeline configuration for automated testing, Docker builds, and Kubernetes deployments
• apps/reaction/Dockerfile — Container image definition; production deployment artifact for Docker and Kubernetes

How to make changes

Add a New GraphQL Mutation

1. Create a .graphql file in tests/integration/api/mutations1/{NewMutationName}/ with mutation definition and input types (apps/reaction/tests/integration/api/mutations1/addAccountAddressBookEntry/AddAccountAddressBookEntryMutation.graphql)
2. Write integration test in the same directory to verify mutation behavior and validation (apps/reaction/tests/integration/api/mutations1/addAccountAddressBookEntry/addAccountAddressBookEntry.test.js)
3. Implement resolver logic in a plugin (via plugins.json) that registers the mutation in the schema (apps/reaction/plugins.json)
4. Add types to GraphQL schema if needed; update src/mockTypes.graphql for type definitions (apps/reaction/src/mockTypes.graphql)

Create a New Plugin or Feature

1. Register the plugin in plugins.json with metadata, version, and entry point (apps/reaction/plugins.json)
2. Create plugin entry point that exports resolvers, mutations, queries, and hooks (apps/reaction/package.json)
3. Use post-system-start hook for database seeding or initialization logic (apps/reaction/.reaction/project-hooks/post-system-start)
4. Add integration tests following the pattern in tests/integration/api/ (apps/reaction/tests/integration/api/mutations1/)

Deploy to Docker/Kubernetes

1. Build Docker image using the provided Dockerfile with multi-stage Node.js build (apps/reaction/Dockerfile)
2. Push image via GitHub Actions workflow which automates tagging and registry publication (.github/workflows/docker-release.yml)
3. Configure CircleCI or GitHub Actions to trigger Kubernetes deployment pipeline (.circleci/config.yml)

Add a New Linting or Quality Rule

1. Define ESLint rules in .eslintrc.cjs for general codebase; tests/.eslintrc.cjs for test files only (.eslintrc.cjs)
2. Configure custom GraphQL linting rules in .reaction/graphql-linter/rules/ (apps/reaction/.reaction/graphql-linter/rules/relay_connection_arguments_spec_custom.cjs)
3. Apply Husky git hooks via .husky/commit-msg to enforce rules before commits (.husky/commit-msg)

Why these technologies

• Node.js + GraphQL — API-first architecture enables headless commerce; GraphQL provides flexible, client-driven queries
• MongoDB — Document-based storage scales for large product catalogs (100k+ products) and flexible schema evolution
• Docker + Kubernetes — Production deployments require stateless, containerized services that auto-scale for high-order-volume traffic
• Plugin System (plugins.json) — Composable architecture allows merchants to enable/disable features without modifying core; reduces coupling
• Meteor Blaze (Legacy) — Historical UI layer; present for backward compatibility but deprecated in favor of headless frontends

Trade-offs already made

• Headless API-first design (no built-in admin UI)

  • Why: Enables flexibility: merchants can build custom admin dashboards or use third-party tools; decouples frontend iteration
  • Consequence: Requires external admin UI or adoption of community tools; steeper initial setup for non-technical users

• Plugin registry (plugins.json) instead of monolithic codebase

  • Why: Reduces core complexity; plugins can be developed independently; scales feature addition across teams
  • Consequence: Runtime overhead from plugin loading; harder to trace execution flow across plugin boundaries

• GraphQL over REST

  • Why: Clients request exact fields needed; reduces over-fetching; supports real-time subscriptions
  • Consequence: Steeper learning curve for developers; requires schema version management; N+1 query risks without proper resolvers

• Support both legacy Meteor Blaze and modern Node.js APIs

  • Why: Maintains backward compatibility for existing deployments during migration
  • Consequence: Dual maintenance burden; two parallel codebases increase testing surface area; eventual deprecation required

Non-goals (don't propose these)

• Does not provide a built-in storefront (headless by design; frontends are separate)
• Does not include real-time inventory sync across fulfillment partners (integrations required via plugins)
• Does not support offline-first or client-side database replication
• Not a SaaS; designed for self-hosted deployment via Docker/Kubernetes

Traps & gotchas

Version lock: .nvmrc pins Node 14.18.1–15.x; modern npm/Node may have compatibility issues. Meteor incompatibility: Meteor Blaze app uses old patterns (Meteor v1.x era); integrating modern React is non-trivial. MongoDB URI required: Apps expect MONGO_URL env var (not shown in snippets but standard for Node+Mongo). GridFS/S3 drivers: File collections require either GridFS (bundled in MongoDB) or explicit S3 credentials; misconfiguring storage breaks image uploads. GraphQL schema validation: Custom linter rules must pass or API will not start. Multi-shop context: Queries must specify shopId; missing it will silently fail or return wrong tenant's data. No visible test config: No jest/mocha/test setup in provided files; test infrastructure may be missing or located elsewhere.

Architecture

Concepts to learn

• Headless Commerce — Reaction decouples the commerce engine (API) from the storefront UI, allowing any frontend (React, Vue, custom) to consume the GraphQL API; critical for understanding its architecture
• GraphQL Schema-First Design — The API is designed around a GraphQL schema (visible via .reaction/graphql-linter); understanding schema-driven development is essential for extending Reaction
• Multi-Tenancy — Reaction isolates data per shop/tenant within a single installation; understanding shopId context is critical to avoid data leaks and cross-shop queries
• Plugin Architecture — Shipping, tax, fulfillment, and payment logic are pluggable; contributors must understand how to hook into core events and override default behavior
• Semantic Versioning with Changesets — .changeset/ config automates changelog and version bumping across the monorepo; contributors must document changes in .changeset files
• Relay Connection Specification — The custom GraphQL linter rule (relay_connection_arguments_spec_custom.cjs) enforces cursor-based pagination; essential for building scalable list queries
• Storage Abstraction Layer — File collections support pluggable backends (GridFS, S3, custom); understanding the adapter pattern is key for deploying to different infrastructure

Related repos

• medusajs/medusa — Modern headless commerce engine in Node.js with plugin architecture, GraphQL API, and multi-tenant support; actively maintained successor to the Reaction ecosystem
• saleor/saleor — Python/GraphQL headless commerce platform; similar API-first philosophy and plugin extensibility, alternative if you prefer Python
• vtex/faststore — VTEX's headless commerce storefront framework; integrates with any commerce backend via REST/GraphQL, showing modern Reaction-like architecture
• elastic/enterprise-search — Search infrastructure often used in Reaction deployments for product discovery; complements the core commerce engine
• reactioncommerce/reaction-admin — Separate React admin UI repo (if it exists); would be the modern admin replacement for the Meteor Blaze app

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for GraphQL custom linter rules

The repo has a custom GraphQL linter rule at .reaction/graphql-linter/rules/relay_connection_arguments_spec_custom.cjs but no visible test coverage. Given this is an API-first platform with GraphQL at its core, adding comprehensive tests would ensure schema compliance and prevent regressions in relay connection specs.

• [ ] Create apps/reaction/tests/graphql-linter/ directory
• [ ] Add test suite for relay_connection_arguments_spec_custom.cjs with valid/invalid schema examples
• [ ] Integrate tests into Jest configuration (apps/reaction/jest.config.cjs)
• [ ] Add test step to .circleci/config.yml or GitHub workflow for linter validation

Add Docker multi-stage build optimization and security scanning workflow

The Dockerfile at apps/reaction/Dockerfile and docker-release.yml workflow exist but there's no visible security scanning (Snyk, Trivy) or multi-stage optimization in the CI/CD pipeline. For a containerized platform deployed via Kubernetes, automated vulnerability scanning in the release workflow is critical.

• [ ] Enhance .github/workflows/docker-release.yml to include Snyk or Trivy image scanning step
• [ ] Refactor apps/reaction/Dockerfile to use multi-stage builds (builder → runtime) to reduce image size
• [ ] Add build cache optimization using Docker buildx in the workflow
• [ ] Document image security policies in SECURITY.md

Implement end-to-end test suite for file collections storage adapters

The repo has three file collection storage adapters (gridfs, s3, base) referenced in meteor-blaze-app/package.json but no visible E2E tests validating upload/download/deletion across different storage backends. This is critical for a headless commerce platform where file handling affects product images and assets.

• [ ] Create apps/meteor-blaze-app/tests/e2e/ directory with test suite for each storage adapter
• [ ] Add tests for S3, GridFS, and base adapter covering: upload, download, delete, error handling
• [ ] Configure test environment using Docker compose to spin up MongoDB and mock S3 (localstack)
• [ ] Integrate E2E tests into .circleci/config.yml with separate job for storage adapter validation

Good first issues

• Add TypeScript definitions for the file-collections package exports. The packages/file-collections/ and related storage adapters lack .d.ts files, making integration with TypeScript frontends difficult.: Low-risk, high-value: improves DX for downstream users without changing runtime behavior: packages/file-collections/index.js,packages/file-collections-sa-base/index.js,packages/file-collections-sa-gridfs/index.js,packages/file-collections-sa-s3/index.js
• Document the plugin system with a worked example. The README mentions 'flexible plugin system' and 'composable' integrations, but no example plugin is shown (shipping, tax, or fulfillment).: Critical docs gap: potential contributors cannot understand how to extend commerce logic without reading source code: README.md,CONTRIBUTING.md,apps/reaction/plugins/ (inferred location)
• Create a migration guide from Meteor Blaze to modern React for the admin UI. The apps/meteor-blaze-app/ is legacy; no clear path is documented to move e-commerce operations to a React-based admin panel.: Unblocks modernization efforts for forks; Blaze is unmaintained and a significant technical debt: apps/meteor-blaze-app/imports/client/,apps/reaction/ (inferred React integration points)

Top contributors

• @sujithvn — 54 commits
• @vanpho93 — 37 commits
• @brent-hoover — 6 commits
• @vanguyen28 — 2 commits
• @github-actions[bot] — 1 commits

Recent commits

• b04166d — Merge pull request #6854 from reactioncommerce/ci-resource-xlarge (brent-hoover)
• e403668 — fix: update ci config with both mutation tests (sujithvn)
• 6c787e8 — fix: split integration mutation into 2 jobs (sujithvn)
• d19cc2d — fix: upgrade max-old-space-size to 12G (sujithvn)
• d4b75c4 — fix: upgrade ci resource xlarge (sujithvn)
• 8aaf479 — Merge pull request #6852 from reactioncommerce/changeset-release/trunk (brent-hoover)
• 5ba67f7 — feat: update pnpm-lock (sujithvn)
• bca754e — Version Packages (github-actions[bot])
• 7150eba — Merge pull request #6851 from reactioncommerce/pnpm-version-pin7.11 (brent-hoover)
• 48a4bf0 — fix: pin pnpm to 7.11.0 in action scripts (sujithvn)

Security observations

• High · Outdated Node.js Target Version — apps/meteor-blaze-app/package.json - babel.presets. The Babel configuration targets Node.js 8, which reached end-of-life on December 31, 2019. Node.js 8 has known security vulnerabilities and no longer receives security updates. Fix: Update Babel target to Node.js 14 or higher (preferably 16+). Update .nvmrc file to match a supported LTS version.
• High · Vulnerable Dependencies - sharp Package — apps/meteor-blaze-app/package.json - dependencies.sharp. The sharp package version ^0.30.7 may have known vulnerabilities. The caret (^) allows patch and minor updates, but the package should be regularly audited and updated to the latest version. Fix: Run 'npm audit' to identify vulnerabilities. Update sharp to the latest stable version and establish a regular dependency update schedule.
• High · Deprecated tus-node-server Package — apps/meteor-blaze-app/package.json - dependencies.tus-node-server. The tus-node-server package version ~0.3.2 is outdated and may contain security vulnerabilities. The tilde (~) restricts updates to patch versions only, potentially missing important security fixes. Fix: Update tus-node-server to the latest stable version. Review the package's maintenance status and consider alternatives if the package is no longer actively maintained.
• Medium · Insecure Babel Runtime Version — apps/meteor-blaze-app/package.json - dependencies.@babel/runtime-corejs2. @babel/runtime-corejs2 version ^7.7.6 is significantly outdated (from 2019). This may contain security vulnerabilities in the runtime environment. Fix: Update to the latest @babel/runtime version and consider removing corejs2 polyfill if targeting modern Node.js versions.
• Medium · Environment Configuration Exposed — apps/reaction/.env.example. The presence of .env.example file suggests environment variable usage. If actual .env files are committed or environment secrets are logged, this poses a security risk. Fix: Ensure .env files are in .gitignore. Use secrets management tools (e.g., HashiCorp Vault, AWS Secrets Manager). Never log environment variables.
• Medium · MongoDB Replica Set Without Authentication — docker-compose.yml - mongo service. The docker-compose.yml shows MongoDB is configured without explicit authentication credentials. The replica set initiation lacks auth configuration, potentially allowing unauthorized access. Fix: Enable MongoDB authentication with MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD. Configure connection strings with credentials. Use MongoDB Atlas or managed services for production.
• Medium · Unrestricted Container Port Access — docker-compose.yml - mongo.ports. Port 27017 (MongoDB) is exposed to the host without network restrictions. This allows direct access from any machine that can reach the host. Fix: Remove port exposure for MongoDB or restrict to localhost only (127.0.0.1:27017:27017). Use internal Docker networking only. For production, use managed database services.
• Medium · API Service Port Exposure — docker-compose.yml - api.ports. Port 3000 is exposed without explicit security considerations. No mention of HTTPS/TLS configuration visible in the docker-compose setup. Fix: Configure HTTPS/TLS with proper certificates. Use environment-specific configurations. Consider reverse proxy (nginx/traefik) with SSL termination.
• Medium · Outdated Dependency - node-fetch — apps/meteor-blaze-app/package.json - dependencies.node-fetch. node-fetch version ^2.6.6 is from 2021. Current versions are significantly newer and contain security fixes. Fix: Update node-fetch to version 3.x or latest. Review changelog for breaking changes. Consider using native Node.js fetch API in Node.js 18+.
• Low · Query String — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.