Dotenv (.env)
Create .env and .env.sample files pre-populated with Nova-related environment variables.
Why Use This Command?
- Generates
.envand.env.samplefor every app that declaresenvironment.appsvalues, so each app in a monorepo gets its own files. - Pre-populates Nova CLI logger settings and Node.js defaults so contributors know which variables are available.
- Keeps sensitive values out of version control while documenting the expected shape.
- Reads each app's environment values from
nova.config.jsonso the same keys and defaults apply on every run. - Preserves the values already filled into an existing
.env, so regenerating never overwrites a real secret.
Requirements
- Node.js runtime — Use any Node.js LTS release.
- Project root — Run the command from the directory containing the top-level
package.json.
Usage
Options
| Flag | Description |
|---|---|
-d, --dry-run | Run without writing any files. |
-r, --replace-file | Overwrite the existing file instead of creating a .nova-backup copy. |
Config Fields
Declare app environment values under environment.apps.<path>.variables in nova.config.json, keyed by the app's workspace path. An app without an environment.apps entry is skipped; the root workspace still receives the reserved-key template.
| Field | Description |
|---|---|
environment.apps.<path>.variables | The variables appended to that app's generated .env files. See Value Fields. |
This command reads only each variable's key and defaultValue. A variable may also declare secret and buildOnly, which this command ignores — the publish workflow uses them to deliver each value to the build or the running server. A non-secret defaultValue seeds .env.sample; the .env entry is always left blank so real secrets stay out of version control.
The NODE_ENV, LOG_LEVEL, and LOG_TIME keys are reserved. The template manages them, so declaring any of them under environment.apps.<path>.variables is rejected when the config loads, with a warning naming the reserved key.
Output Files
The command writes these files into each app directory that declares environment.apps values, and the root workspace directory for the reserved-key template.
| File | Description |
|---|---|
.env | Local environment values, preserving any already filled in. |
.env.sample | Shareable template documenting each key with its config default. |
How It Works
The command is non-interactive. It reads nova.config.json, then generates .env and .env.sample for every app that declares environment.apps values, writing both files into each app directory without prompting. When no app declares environment values, it writes only the reserved-key template for the root workspace.
To change an app's variables, edit its environment.apps entry directly in nova.config.json.
This command writes the double-quoted values; the Dotenv Suite verifies them, so a hand-edited file that drifts from the convention is caught during testing.
Template Output
Each generated file starts from a built-in template that ships three reserved keys with sensible defaults and an inline comment listing their valid values: NODE_ENV (development | production | test, default development), LOG_LEVEL (debug | info | warn | error | auto, default auto, where auto derives the level from NODE_ENV), and LOG_TIME (true | false, default false). Each variable under environment.apps.<path>.variables is appended as KEY="" to .env and KEY="<defaultValue>" to .env.sample.
When an app declares no variables, the generator emits the template only.
Value Preservation
For .env, the generator reads any existing file in the workspace first and keeps the values already filled in for every declared key — including the reserved NODE_ENV, LOG_LEVEL, and LOG_TIME keys. Only newly-added keys are written blank as KEY="", so regenerating after editing the config never overwrites a real secret. The .env.sample file is always rebuilt from the config defaults, since it holds no secrets.