Modules

Buildpack/Utilities

Typedefs

EnvVarDefinitions : Object

Defines the global settings of the project as a list of typed environment variables. Includes a set of changes made to the environment variables in recent versions, to aid with migration and upgrades.

EnvVarDefinitions are used by loadEnvironment() to validate the currently defined values in the environment.

EnvVarDefinitions are also used by createDotEnvFile() to generate an extensively commented .env file for a project.

EnvVarDefsSection : Object

A list of related definitions concerning a particular functional area.

All defined variable names under a particular functional area should have the same prefix, to help namespace and organize configuration. For instance, all variable names in the "Custom local origin" section begin with CUSTOM_ORIGIN_.

EnvVarDefinition : Object

A definition of an environment variable that will be used somewhere else in the project, in the backend and/or the frontend.

Must define a name, type and description. Optionally, may define a default which is set implicitly, an example for documentation, and/or an array of choices to limit the valid values.

The recommended way to access the current environment values in build scripts and interceptors is through the Configuration object object returned by loadEnvironment().

Note: Any build environment will have hundreds of environment variables set, most of which are unrelated to the build process. Any environment variable during the build is accessible via process.env in NodeJS. However, only the variables defined by EnvVarDefinition entries will be available in the frontend, via the Webpack EnvironmentPlugin.

EnvVarDefsChange : Object

Describes a recent change to a particular environment variable. Can indicate that the environment variable was removed or renamed. Change objects can log informative warnings to developers to help with migration. They may also be used to make loadEnvironment() support the legacy name of a renamed variable.

Defines the global settings of the project as a list of typed environment variables. Includes a set of changes made to the environment variables in recent versions, to aid with migration and upgrades.

EnvVarDefinitions are used by loadEnvironment() to validate the currently defined values in the environment.

EnvVarDefinitions are also used by createDotEnvFile() to generate an extensively commented .env file for a project.

Properties

Name
Type
Description
sections
Array.<EnvVarDefsSection>
List of sections, or sub-lists of definitions grouped under a title.
changes
Array.<EnvVarDefsChange>
List of changes, or objects describing a recent change to a definition.

A list of related definitions concerning a particular functional area.

All defined variable names under a particular functional area should have the same prefix, to help namespace and organize configuration. For instance, all variable names in the "Custom local origin" section begin with CUSTOM_ORIGIN_.

Properties

Name
Type
Description
name
String
Title of the section, describing the functional area of the included variables.
variables
Array.<EnvVarDefinition>
List of variable definitions.

A definition of an environment variable that will be used somewhere else in the project, in the backend and/or the frontend.

Must define a name, type and description. Optionally, may define a default which is set implicitly, an example for documentation, and/or an array of choices to limit the valid values.

The recommended way to access the current environment values in build scripts and interceptors is through the Configuration object object returned by loadEnvironment().

Note: Any build environment will have hundreds of environment variables set, most of which are unrelated to the build process. Any environment variable during the build is accessible via process.env in NodeJS. However, only the variables defined by EnvVarDefinition entries will be available in the frontend, via the Webpack EnvironmentPlugin.

Properties

Name
Type
Description
name
String
Name of the environment variable. Must be in SCREAMING_SNAKE_CASE and contain only alphanumeric characters.
type
String
Type of the environment variable. Can be any type supported by the envalid library.
desc
String
Human-readable description of what the environment variable does.
[choices]
Array
An array of acceptable answers. All values in the array must be of the type specified in type.
default
String
Default value if the variable is not set in the environment.
example
String
Example value which will be displayed in inline documentation in the .env file.

Describes a recent change to a particular environment variable. Can indicate that the environment variable was removed or renamed. Change objects can log informative warnings to developers to help with migration. They may also be used to make loadEnvironment() support the legacy name of a renamed variable.

Properties

Name
Type
Description
type
String
removed or renamed
name
String
Name of the EnvVarDefinition that was recently changed. If the change is a rename, this must be the old variable name.
reason
String
Reason given for the change. Will be logged as a warning.
dateChanged
String | number
Date that the change was released, in ISO-8601 format (or any format parseable by JavaScript Date().)
[warnForDays]
number
Number of days after dateChanged to log a warning if the removed or renamed variable is still set in the environment. Default, and maximum, is 180 days.
[update]
String
New name of the variable. Required when the change is a rename.
[supportLegacy]
boolean
If the change is a rename, set this to true to support the old name (while logging a warning). If the old name is set and the new name is not, loadEnvironment will set the new variable name to the value of the old one.

Source Code: pwa-studio/packages/pwa-buildpack/lib/Utilities/getEnvVarDefinitions.js