Edit in GitHubLog an issue

Load environment file

The load-env subcommand for the buildpack CLI command loads and validates the local .env file according to the variable declarations in the envVarDefinitions.json file. This includes any deprecated or changed settings. When loading from .env, buildpack does not override previously declared variables.

Command flags#

--core-dev-modeUsed only by the core PWA Studio repository for quick setups of the core dev environment.

The --core-dev-mode flag tells buildpack to run buildpack create-env-file --use-examples if an existing .env file does not exist in the given directory path.

Usage tips#

  • Use the load-env command in NPM scripts instead of directly invoking it with npx

  • Use a command, shell script, or spawned subprocess to override individual environment variables at start time.

  • The command does not require a .env file to be present.

    If a .env file is not present, the environment is still valid if another process or command sets the required variables. If the file is not present and the variable NODE_ENV is not set to production, buildpack logs a warning.

Programmatic API#

Adding the @magento/pwa-buildpack dependency to your project gives you access to the programmatic API for loading the .env file.

loadEnvironment(dirOrEnv, [logger])#

Loads a given directory's .env file and provides a configuration object.


Copied to your clipboard
1const { loadEnvironment } = require("@magento/pwa-buildpack");
3const configuration = await loadEnvironment(process.cwd());


NameData typeDescription
dirOrEnvstring path or process.env objectProvides a path to the project root.
loggerobjectAn optional logger object to use instead of the default console.

If the dirOrEnv parameter is a process.env object, it will not attempt to parse a .env file.

Return value#

The loadEnvironment() function returns a configuration object.

Configuration object#

Use the configuration object returned by loadEnvironment() as a single source of truth for configuration.


env-The raw environment object
isProductionisProdTrue if NODE_ENV=production
isDevelopmentisDevTrue if NODE_ENV=development
isTest-True if NODE_ENV=test


The configuration object provides methods that return settings in specific namespaces. This lets you pass smaller objects instead of a single, plain object full of global configuration values.

section(sectionName) : Returns a plain object with environment variables in the sectionName namespace. The property keys are camelCased for convenience.

sections(...sectionNames) : Returns a plain object with environment variables from the specified namespaces. The namespaces are assigned to different camelCased properties named after the section name.

all() : Returns the entire environment object, camelCased for convenience, with no namespace separations.

Full example script#

The following example is a script that starts an UPWARD-JS server using configuration values loaded from the environment and .env file in the project path.

Copied to your clipboard
1import { loadEnvironment } from "@magento/pwa-buildpack";
3// Give `loadEnvironment` the path to the project root.
4// If the current file is in project root, use the Node builtin `__dirname`.
5const configuration = await loadEnvironment("/Users/me/path/to/project");
7// `loadEnvironment` has now read the contents of
8// `/Users/me/path/to/project/.env` and merged it with any environment
9// variables that were alredy set.
11// Create an UPWARD server using env vars that begin with `UPWARD_JS_`
14// If these environment variables are set:
16// UPWARD_JS_HOST=https://local.upward/
17// UPWARD_JS_PORT=8081
19// then `configuration.section('upwardJs')` produces this object:
21// {
22// host: 'https://local.upward',
23// port: '8081'
24// }
26// No other environment variables are included in this object unless they begin
27// with `UPWARD_JS_` which is the equivalent of `upwardJs` camel-cased.
29// The .all() method turns the whole environment into an object, with all
30// CONSTANT_CASE names turned into camelCase names.
31const allConfig = configuration.all();
33// This object will have one property for each set environment variable,
34// including the UPWARD variables named above.
35// But `configuration.all()` does not namespace them, they have longer names:
37// {
38// upwardJsHost: 'https://local.upward',
39// upwardJsPort: '8081'
40// }
42// This huge object defeats the purpose of loadEnvironment() and should
43// only be used for debugging.
45// Instead, let's create an UPWARD server combining two environment variable
46// sections with hardcoded overrides to some values.
48 ...configuration.section("upwardJs"),
49 ...configuration.section("magento"),
50 bindLocal: true,
53// This uses JavaScript object spreading to combine several sections of
54// configuration and override a value.
55// If the environment contains these values:
57// UPWARD_JS_HOST=https://local.pwadev
60// MAGENTO_BACKEND_URL=https://local.magento
62// Then the above code passes the following object to `createUpwardServer`:
64// {
65// host: 'https://local.pwadev',
66// port: '443',
67// backendUrl: 'https://local.magento',
68// bindLocal: true
69// }
71// The `sections()` method can split an env object into named subsections:
72createUpwardServer(configuration.sections("upwardJs", "magento"));
74// Given the same environment variables as above, this code will pass the
75// following to `createUpwardServer`:
77// {
78// upwardJs: {
79// host: 'https://local.pwadev',
80// port: '443',
81// bindLocal: '' // the null string is used as a falsy value
82// },
83// magento: {
84// backendUrl: 'https://local.magento'
85// }
86// }
88// (The above is not the actual config object format for `createUpwardServer`,
89// but if it was, that's how you'd make it.)
91// Use the convenience properties `isProd` and `isDev` instead of testing
92// `process.env.NODE_ENV` directly:
93if (configuration.isDev) {
94 console.log("Development mode");
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.