Configuration

Configure the env key in miso.json as an array of entries — one per app or .env file. Each entry defines its own path and validation rules, so variables are always checked against the file they belong to.

>miso.json

{
"env": [
  {
    "label": "web",
    "path": "apps/web/.env.local",
    "required": "all",
    "variables": {
      "PORT": "port",
      "DATABASE_URL": "url",
      "NODE_ENV": {
        "type": "enum",
        "values": ["development", "production", "test"],
        "optional": true
      }
    }
  },
  {
    "label": "api",
    "path": "apps/api/.env",
    "required": "all",
    "variables": {
      "REDIS_URL": {
        "type": "url",
        "schemes": ["redis", "rediss"]
      }
    }
  }
]
}

Miso validates each entry in order, stopping at the first failure and including the entry’s label in the error message.

`label`

An optional name for this entry, used in log output and error messages. If omitted, Miso falls back to the entry’s path value.

Using a label is recommended in any project with more than one env file — it makes errors immediately actionable:


api: missing required variable: REDIS_URL

`path`

The path to the .env file for this entry, relative to the project root.

If omitted, Miso falls back to the same discovery order used when no env config is present at all:

.env.local
.env.production
.env.development
.env

`required`

Controls which variables in this entry must be present:

"all"

Default

Every variable must be present unless marked optional: true on that variable.

"none"

No variables are required — only type-check those that exist.

string[]

Only the listed keys are required; others may be absent.

`variables`

Defines the variables to validate for this entry. Accepts either an object (type validation) or an array (presence only).

Object form — each key is a variable name, each value is a type shorthand string or full VarConfig:

>miso.json

{
"variables": {
  "PORT": "port",
  "DATABASE_URL": "url",
  "APP_NAME": {
    "type": "string",
    "optional": true
  }
}
}

Array form — only checks that the listed variables exist, no type validation:

>miso.json

{
"variables": ["DATABASE_URL", "API_KEY", "REDIS_URL"]
}

Use the array form when you only care about presence (e.g. in CI) and don’t need format validation.

Single-app projects

If you only have one .env file, you still use an array — just with a single entry:

>miso.json

{
"env": [
  {
    "path": ".env.local",
    "variables": {
      "PORT": "port",
      "DATABASE_URL": "url"
    }
  }
]
}