Adding Environment Variables
Adding Environment Variables
To use an environment variable at runtime, it must be available at build time.
Local Development
For local development, define the variable in your local .env.local file at apps/numera-ui/.env.local:
NX_EXTERNAL_API_URL=https://externalapi.numera.dev
Note: Variables must be prefixed with
NX_for Nx to recognize them.
Refer to the Nx documentation on defining environment variables for more details.
To document required variables, also add them (without values) to apps/numera-ui/.env.example:
NX_EXTERNAL_API_URL=
The .env.example file is intentionally not git-ignored, making it easier to understand which environment variables are needed to set up a development environment.
The Vite dev server is configured to warn if a variable listed in
.env.exampleis not defined in your environment (e.g..env.local).
To enable type safety for your environment variables in TypeScript, you should declare them in the ImportMetaEnv interface within the env.d.ts file.
For example, to type a new variable NX_EXTERNAL_API_URL, add the following:
interface ImportMetaEnv {
// ...
readonly NX_EXTERNAL_API_URL: string | undefined;
}
Environment Variables During Deployment
Environment variables must also be available at build time during deployment. This is handled in the Build Numera UI composite GitHub Action.
To expose a variable at build time, write it to the special $GITHUB_ENV environment file:
echo "MY_STATIC_VAR=SomeValue" >> $GITHUB_ENV
AWS Parameter Store
Environment variable values are stored in AWS Parameter Store. There are two types of environment variables:
1. Variables Provided by AWS Resources
For example, the CopsService construct:
- Creates a parameter
- Grants read permission to the
NumeraUiDeployRole
This role is assumed by the Build Numera UI action. It retrieves the parameter and writes it to the environment like so:
API_COMPLIANCE_URL=$(aws ssm get-parameter --name /${{ inputs.ENV_NAME }}/ComplianceService/url --output text --query Parameter.Value 2>/dev/null || echo "")
echo "API_COMPLIANCE_URL=${API_COMPLIANCE_URL}" >> $GITHUB_ENV
Most environment variables are environment-specific. Use the
ENV_NAMEinput to build the correct parameter path.
2. Manually Created Parameters
These include third-party service configs such as client IDs or URLs.
- Create parameters via the AWS Console (as plain strings or SecureStrings).
- Use the naming convention:
/NumeraUi/{vendor}/{name}e.g.,/NumeraUi/Unleash/apiUrl
To read:
# String parameter
aws ssm get-parameter --name {name} --output text --query Parameter.Value
# SecureString parameter
aws ssm get-parameter --name {name} --output text --query Parameter.Value --with-decryption
Make sure to create the variable in all Numera AWS accounts (dev, stage, prod).
To grant the NumeraUiDeployRole permission, add the parameter to the return value of the collectAllAccessibleParams function in the NumeraUi stack.
For SecureString parameters use ssm.StringParameter.fromSecureStringParameterAttributes and for String parameters use ssm.StringParameter.fromStringParameterAttributes.
Adding Variables to build-cloud.sh
In the Build Numera UI GitHub Action, variables are defined without the NX_ prefix.
The build-cloud.sh script maps them to NX_ variables like so:
export NX_EXTERNAL_API_URL=${EXTERNAL_API_URL}
# ...
echo "NX_EXTERNAL_API_URL: '${EXTERNAL_API_URL}'"
Adding Variables to pull-env.sh
The pull-env.sh script allows you to copy environment variables for a specific (personal) environment to your local machine.
To add new variables:
echo "NX_EXTERNAL_API_URL=$(aws ssm get-parameter --name /NumeraUi/externalApiUrl --output text --query Parameter.Value)" >> ${env_path}