Mailchimp Developer LogoMailchimp Developer Wordmark

Plugins and Environment Variables

The basics

All of Mailchimp Open Commerce's features are provided by plugins, either first-party or third-party. This structure gives you complete control over what plugins and features are active in your installation. First-party Open Commerce services are distributed as Docker images, or can be customized and then built into your own Docker image.

Much of the platform-wide configuration of Open Commerce is set via environment variables—either to pass information from one service to another or simply to customize the platform to meet your needs. Some environment variable values are required, while others are optional. Each plugin should supply sensible defaults for required values, and the development platform's make scripts automatically set up required .env files for you.

This documentation outlines the plugins included in the development platform, as well as common environment variables and their functions. For more information about making data available throughout your Open Commerce installation, see the Sharing Code Between Plugins doc.

Plugins

A wide range of first-party plugins covers all the basic platform features, including the API core, handling backend services, shop configuration, and the shopper experience. You can view a list of the plugins active in your instance in the admin dashboard under Settings > System Information.

The plugins included with the development platform are:

PluginDescription
api-plugin-accountsManages internal accounts for shop operators and shoppers.
api-plugin-address-validationValidates shopper addresses during checkout.
api-plugin-address-validation-testA template for creating a new address validation plugin.
api-plugin-authenticationConnects the Identity service to the Open Commerce API.
api-plugin-authorization-simpleChecks account permissions to allow or deny actions.
api-plugin-cartsHandles shopping cart objects.
api-plugin-catalogsHandles product catalogs.
api-plugin-discountsHandles discounting products.
api-plugin-discounts-codesEnables discount codes that shoppers can enter at checkout.
api-plugin-emailSends transactional emails.
api-plugin-email-smtpManages the SMTP connection for outgoing transactional emails.
api-plugin-email-templatesProvides transactional email templates that shop operators can customize.
api-plugin-filesManages file uploads for a shop.
api-plugin-i18nHandles internationalization options for a shop.
api-plugin-inventoryTracks inventory counts for product variants.
api-plugin-inventory-simpleDetermines product availability status based on inventory counts.
api-plugin-job-queueManages job queuing and execution.
api-plugin-navigationAllows for the creation of hierarchical navigation in a shop.
api-plugin-notificationsSends messages about order statuses.
api-plugin-ordersHandles orders, including fulfillment groups.
api-plugin-paymentsManages all payment methods for a shop.
api-plugin-payments-exampleA template for creating a new payment handler.
api-plugin-payments-stripeProcesses payments with Stripe.
api-plugin-pricing-simpleEnables setting prices on product variants.
api-plugin-productsCreates products and manages their information.
api-plugin-settingsManages shop settings like those available in the admin dashboard.
api-plugin-shipmentsHandles shipment types, including allowing or denying shipment methods for products or orders that meet certain criteria.
api-plugin-shipments-flat-rateHandles shipment types that always cost the same amount.
api-plugin-shopsAllows creation and management of shops within an Open Commerce instance.
api-plugin-simple-schemaImplements SimpleSchema to validate data for MongoDB documents.
api-plugin-sitemap-generatorCreates sitemap files for search engines at a specified time interval.
api-plugin-surchargesAllows applying surcharges to a cart.
api-plugin-system-informationProvides information about the running instance of Open Commerce, including registered plugins.
api-plugin-tagsHandles tag creation and organization.
api-plugin-taxesManages tax rates based on location, product type, and more.
api-plugin-taxes-flat-rateAllows for setting a single tax rate.
api-plugin-translationsSupplies translations of terms used in the API in over 20 languages.

Environment variables

You can set variables in each service's .env file, which is used by Docker Compose when starting the system and loading plugins. Each Open Commerce repo contains a .env.example file that lists the environment variables and default values for that project. You can run the bin/setup script within the project to automatically copy the contents of .env.example to .env (although it will not overwrite existing values). Your .env files will contain personalized and potentially sensitive information, so you should never commit them to a public GitHub repo.

In some cases, projects may look for additional environment variables that are not listed in .env.example because they are optional and have default values set in the code. You can find these optional variables by searching for cleanEnv within a Node project.

The following tables detail the environment variables used by the API core, storefront, and admin services.

API

Variable NameDescriptionDefault
GRAPHQL_INTROSPECTION_ENABLEDAllow introspection of the GraphQL API.true
GRAPHQL_PLAYGROUND_ENABLEDServe the GraphQL Playground at /graphql.true
MONGO_URLThe MongoDB connection string URL, including the name of the database you want to use.mongodb://localhost:27017/reaction
MONGO_USE_UNIFIED_TOPOLOGYMongoDB’s useUnifiedTopology option.true
PORTPort to serve the API on.3000
REACTION_LOG_LEVELControl how much is printed in the logs. Possible values, from most to least verbose: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.DEBUG
REACTION_APOLLO_FEDERATION_ENABLEDEnable Apollo Federation support.false
REACTION_ADMIN_PUBLIC_ACCOUNT_REGISTRATION_URLThe registration URL to be used in new account invitation emails.http://localhost:4080
REACTION_GRAPHQL_SUBSCRIPTIONS_ENABLEDEnable GraphQL subscriptions over WebSockets.true
REACTION_SHOULD_INIT_REPLICA_SETAutomatically initialize a MongoDB replica set on startup if one isn’t found.true
REACTION_WORKERS_ENABLEDEnable background job workers. If set to false, features that require background jobs, such as emailing and file uploads, won't work.true
VERBOSE_JOBSEnable logging of jobs to the console.false
ROOT_URLThe root URL (including protocol) for the API.http://localhost:3000
STRIPE_API_KEYThe secret key from your Stripe account dashboard. Required for using Stripe payments.YOUR_PRIVATE_STRIPE_API_KEY
MAIL_URLAn SMTP URL (e.g. smtp://user:pass@example.com:465) that is used to send all transactional emails from the email-smtp plugin.none
EMAIL_DEBUGEnable email plugin logging.false
REACTION_SHOULD_ENCODE_IDSTransform internal IDs to opaque IDs using the encodeOpaqueId function.true
STORE_URLThe URL for the storefront.http://localhost:4000

Example Storefront

Variable NameDescriptionDefault
CANONICAL_URLThe canonical root public URL for your storefront.none
BUILD_GRAPHQL_URLA URL for creating a build outside of CI/CD.none
EXTERNAL_GRAPHQL_URLThe public GraphQL API URL used by Next.js.none
INTERNAL_GRAPHQL_URLThe URL used by the frontend server to reach GraphQL for the build process.none
NODE_ENVNode environment designation, usually production or development.none
PORTPort to run the storefront server on.4000
SESSION_MAX_AGE_MSThe maximum age in milliseconds for the storefront session cookie, which is used for authentication.86400000 (24 hours)
SESSION_SECRETA unique key for cookie session verification.none
STRIPE_PUBLIC_API_KEYThe public/client key from your Stripe dashboard.none
SITEMAP_MAX_AGEThe max-age value in seconds for the Cache-Control header included when serving the sitemap.xml file.43200 (12 hours)
IS_BUILDING_NEXTJSIf true, serve the API from BUILD_GRAPHQL_URL; if false, serve the API from INTERNAL_GRAPHQL_URL.false

Admin

Variable NameDescriptionDefault
PUBLIC_GRAPHQL_API_URL_HTTPAn API URL that is accessible from browsers and accepts GraphQL POST requests over HTTP.none
PUBLIC_GRAPHQL_API_URL_WSAn API URL that is accessible from browsers and accepts GraphQL WebSocket connections. Enables GraphQL subscriptions on the client. The location is usually the same as PUBLIC_GRAPHQL_API_URL_HTTP but using the ws protocol instead of http.none
PUBLIC_FILES_BASE_URLA full public URL that has /assets/uploads and /assets/files endpoints for uploading and downloading files. Usually the same as the API service root URL.none
PUBLIC_I18N_BASE_URLRequired. A full public URL that has /locales/namespaces.json and /locales/resources.json endpoints for loading translations. Usually the same as the API service root URL.none
PUBLIC_STOREFRONT_HOME_URLRequired. The URL for the storefront home page. This is only used as fallback if a storefront URL isn’t set within the admin dashboard.none
ROOT_URLThe canonical root public URL for the admin server.none
PORTThe port to run the Node server on. We recommend using 4080.none
MONGO_ALLOW_DISK_USEAllow MongoDB to use temporary files on disk.false
Improve our docs onGitHub