Jets Dotenv Files

Jets supports dotenv files. Jets uses the dotenv files in the config/jets/env folder only for the AWS Lambda Function environment variables.

Note: Jets 6, dotenv files support work differently from Jets 5 since Jets 6 allows you to Bring Your Own Framework. Jets env files designed only for deployment. Also, the JETS_ENV_REMOTE concept has been removed.

How It Works

Here’s an example to show how it works.

.env
config/jets/env/.env

A framework like Rails using the dotenv library loads the .env file. That is used locally only. Usually, these .env files are gitignored and not checked into version control.

Jets use files like config/jets/env/.env, and their values are assigned to the AWS Lambda Function environment variables.

Environment Specific Variables

You can set environment-specific variables. Let’s say you have a Jets project with the following dotenv files:

config/jets/env/.env
config/jets/env/.env.dev
config/jets/env/.env.prod

The .env file is always loaded. The other .env files will be loaded based on the JETS_ENV value. So:

  • JETS_ENV=dev jets deploy uses config/jets/env/.env.dev
  • JETS_ENV=prod jets deploy uses config/jets/env/.env.prod

Though you can use separate env files, it’s recommended to keep things even simpler by using SSM and conventions in the .env file.

Convention Path Loading

For the most part, you do not need config/jets/env files to explicitly declare the values. Jets can conventionally load env vars by conventional SSM path, IE: /demo/dev or /demo/prod. Here’s an example.

❯ aws ssm describe-parameters | jq -r '.Parameters[].Name' | grep '/demo/dev/' | sort
/demo/dev/DATABASE_URL
/demo/dev/SECRET_KEY_BASE

Since the DATABASE_URL and SECRET_KEY_BASE parameters are underneath the /demo/dev/ SSM Parameter path, they will be load automatically. Here’s what the file would look like

config/jets/env/.env

DATABASE_URL=SSM
SECRET_KEY_BASE=SSM

Thanks to conventions, .env file above is optional. You only need a .env file if you have non-conventional parameters paths. To see what SSM values config/jets/env files will resolve to you can use.

> jets dotenv:list
DATABASE_URL=mysql2://user:pass@host.com/dbname?pool=5

If you want to learn more about the SSM conventions including how to control the behavior see: Jets Dotenv SSM Conventions.

Dotenv File Precedence

The naming convention for these files is .env.. Here's an example with `JETS_ENV=dev` to explain the dotenv files precedence, from highest to lowest.

  1. config/jets/env/.env.dev.beta (highest) - Loaded when JETS_EXTRA=beta is set
  2. config/jets/env/.env.dev
  3. config/jets/env/.env - (lowest) - Always loaded

Command: jets dotenv:list

You can use the jets dotenv:list command to show the resolved values. This can be useful for debugging.

❯ jets dotenv:list --reveal
DATABASE_URL=mysql2://user:pass@host.com/dbname?pool=5

Function Env Variables

The config/jets/env names and values are added to the Lambda Function Env Variables as part of deployment. Related: SSM Design Thoughts.

In this section: