Related Pages

Related topics: Lib

Overview

Project Purpose

Reaction is an open-source, API-first e-commerce platform built using Node.js, Express, MongoDB, and GraphQL. The repository hosts a Yarn workspaces monorepo that bundles the storefront/admin app, the legacy Blaze admin app, and a collection of reusable npm packages. The current major release is v5.0.0, which marks a major version bump in the API core. Source: README.md:1-40

The platform targets headless commerce use cases and exposes its functionality through GraphQL mutations and queries rather than through the older Meteor pub/sub model. The goal of this transition is to make the API server runnable as a standalone Node application, decoupled from Meteor's runtime. Source: README.md:30-60

Repository Structure

The monorepo is organized into two top-level directories: apps/ and packages/. Workspaces are declared at the root and glued together with a shared package.json and shared Node engine constraint.

The root package.json declares the workspace glob, the engine pin to Node, and the scripts that orchestrate building, linting, and testing across all workspaces. Source: package.json:1-40 The api-core package README documents how plugins register and how the core Express/GraphQL server is assembled. Source: packages/api-core/README.md:1-30

Applications

`apps/reaction`

This is the primary application. Its package.json declares the dependency on @reactioncommerce/api-core and other workspace packages, and it is the entry point the CLI and reaction-cli bootstrap. The project-hooks directory contains scripts that run during install/upgrade to seed configuration and copy fixtures into the project. Source: apps/reaction/.reaction/project-hooks/README.md:1-20 The app's package.json exposes scripts such as start, build, lint, and test. Source: apps/reaction/package.json:1-60

`apps/meteor-blaze-app`

The Blaze app is the legacy administration interface. It is a Meteor application and is being phased out in favor of the modern admin built into the main apps/reaction application. Its package.json declares Meteor-specific dependencies such as meteor-node-stubs and Blaze templating libraries. Source: apps/meteor-blaze-app/package.json:1-60

Architecture and Migration

The codebase has historically run on Meteor, both for the client (Blaze) and the server (publications and methods). Community issue #4996 ("[EPIC] Moving the API off Meteor") tracks the effort to extract the API server so it can boot as a plain Node process. Source: README.md:30-60

In parallel, issue #5747 ("GQL: All the things") tracks the conversion of remaining Meteor methods, publications, and direct MongoDB writes into GraphQL operations. Sub-tasks for catalog and core have been completed. Source: README.md:30-60

graph LR
  A[apps/reaction] --> C[Express + GraphQL API]
  C --> D[(MongoDB)]
  C --> E[packages/api-core]
  C --> F[plugins/* packages]
  B[apps/meteor-blaze-app] -->|legacy admin| D
  G[CLI / reaction-cli] --> A
  G --> B

Packages and Plugins

packages/api-core is the keystone of the API server. It exports the bootstrap function that wires Express, GraphQL, the plugin loader, and the context factory used by resolvers. Plugins register themselves by name, register GraphQL schemas, register mutations/queries, and add startup hooks. Source: packages/api-core/README.md:10-40

Other workspace packages typically live next to api-core and follow the same plugin conventions so they can be composed into a single API instance at startup. The root package.json workspace glob is what makes these packages resolvable to the apps via standard node_modules symlinks. Source: package.json:1-30

Developer Tooling

The root scripts delegate to Yarn workspaces to run lifecycle tasks across every workspace. Common scripts include lint, test, build, and clean, each of which fans out to the matching script defined in every workspace's package.json. Source: package.json:20-50 The main app defines scripts for running the API, seeding the database, and building distribution bundles. Source: apps/reaction/package.json:10-50 The Blaze app's scripts use Meteor's CLI under the hood, reflecting its distinct runtime. Source: apps/meteor-blaze-app/package.json:5-40

Known Operational Issues

Community-reported friction often centers on three areas. First, CLI install problems — issue #6856 documents cases where dependencies fail to publish to npm and break the local CLI install. Second, runtime image-upload failures — issue #6298 reports an exception during product image upload in the admin UI, traced to a runtime error in the asset pipeline. Third, overall performance, tracked in the long-standing #3233 epic, which benchmarks and improves request latency, Meteor startup time, and MongoDB query performance. Source: README.md:30-60

Together these define the practical scope of the project today: a multi-app monorepo whose API server is being moved off Meteor, whose data access is being standardized on GraphQL, and whose plugin model lives in packages/api-core. New contributors should start by reading README.md, then packages/api-core/README.md, and then the package.json of the application they intend to modify.

Related Pages

Related topics: Overview, Src

Lib

Overview and Scope

The lib directory inside packages/api-utils/ is the implementation heart of the Reaction Commerce @reactioncommerce/api-utils package. It groups together the static reference data and small, pure helper functions that are reused by the GraphQL API layer, plugins, and admin UI without depending on the wider app context (database, accounts, etc.). All exports are intended to be dependency-free and side-effect free, which makes them safe to import from server-only contexts as the project continues migrating off Meteor (tracked in #4996).

The folder is split into two thematic groups:

• Reference data — countries, currencies, and languages, each exposed both as raw definitions and as pre-shaped "options" consumable by UI select inputs.
• Generic utilities — small helpers such as arrayJoinPlusRemainingQuery that operate on plain JavaScript values.

Source: packages/api-utils/lib/CountryDefinitions.js, packages/api-utils/lib/CurrencyDefinitions.js, packages/api-utils/lib/LanguageOptions.js

Reference Data Files

Country Data

CountryDefinitions.js provides the canonical list of supported countries used by shop, address, and tax-related resolvers. Adjacent to it, CountryOptions.js projects those definitions into the lightweight { value, label } shape required by admin dropdowns and GraphQL enum-adjacent inputs. Keeping the two files separate lets server code depend on rich definitions while UI surfaces depend only on the slimmed-down options.

Source: packages/api-utils/lib/CountryDefinitions.js, packages/api-utils/lib/CountryOptions.js

Currency Data

CurrencyDefinitions.js mirrors the country pattern but for ISO 4217 currencies. It is the source of truth for currency codes, symbols, and display formatting that the catalog, cart, and pricing logic rely on. CurrencyOptions.js then reshapes those records into the same { value, label } option list, ensuring UI components and GraphQL inputs share a single normalized shape.

Source: packages/api-utils/lib/CurrencyDefinitions.js, packages/api-utils/lib/CurrencyOptions.js

Language Data

LanguageOptions.js follows the same conventions as the country and currency option files, exposing a uniform list of supported languages. This uniformity is what allows the admin UI to render country, currency, and language pickers with identical components and the same data contract.

Source: packages/api-utils/lib/LanguageOptions.js

Generic Utility Functions

`arrayJoinPlusRemainingQuery`

arrayJoinPlusRemainingQuery.js is a small string-building helper. It joins the first *n* items of an array with a separator and appends the remaining count in a query-string form (for example, "a, b, c and 2 more"). The function is intentionally framework-agnostic so it can be reused in URL construction, log lines, or human-readable summaries produced by GraphQL resolvers without pulling in extra dependencies.

Source: packages/api-utils/lib/arrayJoinPlusRemainingQuery.js

Conventions Inside the Directory

Every file in lib/ follows two consistent conventions that downstream consumers can rely on:

This pairing pattern means consumers should import Definitions when they need fields beyond a label, and Options when they only need an id/label pair. Adopting this rule keeps bundle size small on the client and avoids leaking data the UI does not render.

Source: packages/api-utils/lib/CountryDefinitions.js, packages/api-utils/lib/CountryOptions.js, packages/api-utils/lib/CurrencyDefinitions.js

Relationship to the Broader Migration

Because the items in this directory are pure data and pure functions, they are among the easiest modules to migrate off Meteor. They are referenced indirectly by the GraphQL conversion epic (#5747) because every country, currency, or language field exposed through GraphQL ultimately points back at the option lists defined here. Maintaining a single source for these values is what prevents drift between server validation and UI pickers — a frequent source of bugs in earlier versions where the data was duplicated across plugins.

Source: packages/api-utils/lib/CountryOptions.js, packages/api-utils/lib/CurrencyOptions.js, packages/api-utils/lib/LanguageOptions.js

Related Pages

Related topics: Lib, Src

Src

The src directory in a Reaction Commerce plugin (e.g., packages/api-plugin-accounts/src) is the canonical location for all executable, declarative, and locale-specific source code belonging to that plugin. Every API plugin in the Reaction monorepo follows the same src/ layout so that the platform's plugin loader can resolve entry points, mutations, queries, schemas, and translation strings uniformly. Source: packages/api-plugin-accounts/src/index.js:1-40

Role and Scope

src/ is where plugin authors place the JavaScript modules, GraphQL schemas, JSON translation files, and helper functions that make up a plugin's runtime behavior. The top-level src/index.js typically registers the plugin with the Reaction API, including its name, GraphQL type definitions, resolvers, mutations, queries, and any background functions. Source: packages/api-plugin-accounts/src/index.js:1-80 The directory intentionally excludes build artifacts, tests, and fixtures, which live in sibling folders.

Within the plugin, src/ is subdivided into thematic subdirectories that group related concerns:

Source: packages/api-plugin-accounts/src/mutations/createAccount.js:1-50, packages/api-plugin-accounts/src/queries/roles.js:1-40, packages/api-plugin-accounts/src/schemas/accounts.js:1-30

Common Code Patterns

Entry Point and Plugin Registration

src/index.js exports a default plugin descriptor that the API runtime consumes. It wires together the GraphQL schemas from schemas/, the mutation resolvers from mutations/, the query resolvers from queries/, and the registration helpers from registration/. This is the file imported by node_modules/@reactioncommerce/api-plugin-accounts at runtime. Source: packages/api-plugin-accounts/src/index.js:20-120

Configuration

src/config.js exports static, non-secret configuration (such as default session ages or password policy thresholds) as JavaScript objects. Mutations and queries read from this file rather than embedding magic numbers. Source: packages/api-plugin-accounts/src/config.js:1-60

Mutations, Queries, and Resolvers

Mutation modules export async functions that accept a GraphQL context and resolved input, then perform database writes through the context's collections. Query modules export analogous functions for reads. The naming convention is verb-first (createAccount, inviteShopMember). Source: packages/api-plugin-accounts/src/mutations/createAccount.js:10-90

GraphQL Schemas

src/schemas/*.js files export tagged template literals written with the @graphly/dapper/apollo template tag, defining GraphQL type extensions, input types, and the mutations/queries themselves. The plugin's index.js references these to compose its public API surface. Source: packages/api-plugin-accounts/src/schemas/accounts.js:1-80

Account Lifecycle Helpers

src/registration/setupAccount.js and similar files encapsulate reusable workflows used by multiple mutations, keeping mutation files thin and delegating the orchestration logic. Source: packages/api-plugin-accounts/src/registration/setupAccount.js:1-50

Internationalization (i18n)

The src/i18n/ subdirectory contains locale-specific JSON catalogs, one file per language (en.json, fr.json, vi.json, ar.json, etc.). Each file exports an object whose keys map to string identifiers used by the plugin's UI surfaces. Adding a new language is a matter of dropping a new JSON file with translated values; the API loader picks them up automatically based on the active shop locale. Source: packages/api-plugin-accounts/src/i18n/en.json:1-200, packages/api-plugin-accounts/src/i18n/fr.json:1-200, packages/api-plugin-accounts/src/i18n/vi.json:1-200, packages/api-plugin-accounts/src/i18n/ar.json:1-200

This locale layout is particularly important because account-related strings (validation messages, email subjects, invitation copy) are surfaced in many places; centralizing them in src/i18n/ avoids duplication. Community issue #6856 reported broken CLI workflows that prevented dependable dependency resolution — when packages fail to publish, the i18n JSON files are sometimes the first assets dropped, so the loader's tolerant behavior matters in practice. Source: packages/api-plugin-accounts/src/i18n/en.json:1-50

Architectural Summary

flowchart TD
  A["src/index.js (plugin descriptor)"] --> B["mutations/"]
  A --> C["queries/"]
  A --> D["schemas/"]
  A --> E["registration/"]
  A --> F["config.js"]
  A --> G["i18n/*.json"]
  B --> H["context.collections, context.account"]
  C --> H
  D --> I["GraphQL SDL strings"]
  E --> J["workflow helpers"]

Source: packages/api-plugin-accounts/src/index.js:30-100, packages/api-plugin-accounts/src/mutations/createAccount.js:1-60, packages/api-plugin-accounts/src/queries/roles.js:1-40, packages/api-plugin-accounts/src/schemas/accounts.js:1-50, packages/api-plugin-accounts/src/registration/setupAccount.js:1-40, packages/api-plugin-accounts/src/config.js:1-50

Practical Notes for Contributors

• New mutations belong in src/mutations/ and must be referenced from src/index.js under the plugin's mutations field to be exposed on the GraphQL gateway. Source: packages/api-plugin-accounts/src/index.js:40-90
• Keep config.js free of environment-specific secrets — secrets live in the platform's configuration loader, while config.js holds defaults. Source: packages/api-plugin-accounts/src/config.js:1-40
• When adding a string visible to users, prefer reusing an existing i18n key in src/i18n/en.json; if a new key is required, supply translations for all supported locales to avoid fallback warnings. Source: packages/api-plugin-accounts/src/i18n/en.json:1-100
• The src/ boundary mirrors the public package boundary — anything exported from src/index.js should be considered a stable surface, while internal helpers (e.g., in registration/) may change. Source: packages/api-plugin-accounts/src/registration/setupAccount.js:1-30

Because the Reaction platform emphasizes moving "all the things" to GraphQL (#5747) and decoupling from Meteor (#4996), the structure of src/ is intentionally narrow and explicit: each plugin ships its own src/ with a predictable shape, which makes it feasible to compose the platform from independently publishable npm packages while preserving a uniform developer experience.

Doramagic Pitfall Log

Found 11 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/reactioncommerce/reaction/issues/6866

2. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/reactioncommerce/reaction/issues/6484

3. Maintenance risk: Maintenance risk requires verification

• Severity: high
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/reactioncommerce/reaction/issues/6869

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/reactioncommerce/reaction/issues/6871

5. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/reactioncommerce/reaction/issues/6400

6. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/reactioncommerce/reaction

7. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/reactioncommerce/reaction

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/reactioncommerce/reaction

9. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/reactioncommerce/reaction

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/reactioncommerce/reaction

11. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/reactioncommerce/reaction

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using reaction with real data or production workflows.

• Add Error Handling Examples for /users/info in Documentation - github / github_issue
• Password "ASDF1234" gives: Password must contain at least one number or - github / github_issue
• Keep Get 'It looks like you have not run npm install in this directory - github / github_issue
• Validate Plugin Object/Function - github / github_issue
• Limited Signup option - github / github_issue
• Reinstate ability to register an endpoint - github / github_issue
• v5.0.0 - github / github_release
• [email protected] - github / github_release
• @reactioncommerce/[email protected] - github / github_release
• @reactioncommerce/[email protected] - github / github_release
• @reactioncommerce/[email protected] - github / github_release
• @reactioncommerce/[email protected] - github / github_release