---
title: "env-spec syntax"
description: "Every decorator, type and default rule envSchema accepts in .env.example, and the syntax it rejects."
canonical_url: "https://nuxt-safe-runtime-config.onmax.me/reference/env-spec"
---
# env-spec syntax

> Every decorator, type and default rule envSchema accepts in .env.example, and the syntax it rejects.

`envSchema` reads a `.env.example` written in the `env-spec-v1` profile: the [@env-spec syntax](https://varlock.dev/env-spec/reference/) with a small set of [Varlock decorators](https://varlock.dev/reference/item-decorators/). It is not the full Varlock runtime. The file declares names, types, descriptions, defaults, and whether each value is required and public. It never reads `.env`, fetches secrets or evaluates expressions.

```dotenv [.env.example]
# @defaultRequired=true @defaultSensitive=true
# ---

# Database connection supplied by the deployment.
# @type=url @example="https://database.example.test"
NUXT_DATABASE_URL=

# @type=number(min=1, max=65535, isInt=true)
NUXT_SMTP_PORT=587

# @type=enum(debug, info, warn, error) @public
NUXT_PUBLIC_LOG_LEVEL=info

# @optional @public
NUXT_PUBLIC_BANNER=
```

[.env.example as schema](https://nuxt-safe-runtime-config.onmax.me/guide/env-schema) shows how the module maps these entries to runtime config.

## Header

An optional header sets defaults for every entry and ends with `# ---`. It accepts two decorators, both `true` by default:

<table>
<thead>
  <tr>
    <th>
      Decorator
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @defaultRequired=false
      </code>
    </td>
    
    <td>
      Entries are optional unless marked <code>
        @required
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @defaultSensitive=false
      </code>
    </td>
    
    <td>
      Entries are public unless marked <code>
        @sensitive
      </code>
    </td>
  </tr>
</tbody>
</table>

## Entries

A name matches `[A-Za-z_][A-Za-z0-9_]*` and is at most 256 characters. Duplicate names fail, and so do `__proto__`, `prototype` and `constructor` in any case.

The comment lines right above an entry become its description. A blank line or a divider ends it, and a comment that looks like a disabled assignment, such as `# OLD_KEY=1`, is left out. Decorators can share a comment line.

<table>
<thead>
  <tr>
    <th>
      Decorator
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @type=…
      </code>
    </td>
    
    <td>
      The value's type. See <a href="#types">
        Types
      </a>
      
      . Without it, the value is a string.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @required
      </code>
      
      , <code>
        @required=false
      </code>
    </td>
    
    <td>
      The value must be present and not empty.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @optional
      </code>
      
      , <code>
        @optional=false
      </code>
    </td>
    
    <td>
      The inverse of <code>
        @required
      </code>
      
      . Use one or the other.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @sensitive
      </code>
      
      , <code>
        @sensitive=false
      </code>
    </td>
    
    <td>
      The value must stay private.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @public
      </code>
      
      , <code>
        @public=false
      </code>
    </td>
    
    <td>
      The inverse of <code>
        @sensitive
      </code>
      
      . Use one or the other. A key still needs the <code>
        NUXT_PUBLIC_
      </code>
      
       prefix to reach the browser.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @example="sample"
      </code>
    </td>
    
    <td>
      Documentation. It never becomes a default.
    </td>
  </tr>
</tbody>
</table>

A repeated decorator, an unknown one, or a conflicting pair such as `@required @optional` fails with the file and line.

## Types

<table>
<thead>
  <tr>
    <th>
      <code>
        @type
      </code>
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      A string. Optional bounds: <code>
        string(minLength=1, maxLength=80)
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      A finite number. Optional bounds: <code>
        number(min=0, max=100, isInt=true)
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       or <code>
        false
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        enum(debug, info, error)
      </code>
    </td>
    
    <td>
      One of the listed strings. Quote a choice that looks like a number or a boolean.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      An absolute URI, checked with the JSON Schema <code>
        uri
      </code>
      
       format. The value stays a string.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        array
      </code>
      
      , <code>
        array(string)
      </code>
    </td>
    
    <td>
      A JSON array, with an optional item type.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        object
      </code>
      
      , <code>
        object(enabled=boolean, retries=number)
      </code>
    </td>
    
    <td>
      A JSON object. With properties, it must have exactly those. Bare <code>
        object
      </code>
      
       accepts any JSON object, and <code>
        object()
      </code>
      
       only an empty one.
    </td>
  </tr>
</tbody>
</table>

Types nest, as in `array(object(name=string, roles=array(enum(read, write))))`, up to 16 levels.

The assigned value never sets the type. `TOKEN=00123` and `FLAG=true` are both strings unless `@type` says otherwise.

## Defaults

<table>
<thead>
  <tr>
    <th>
      Written as
    </th>
    
    <th>
      Means
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        KEY=value
      </code>
    </td>
    
    <td>
      <code>
        value
      </code>
      
       is the default
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        KEY=
      </code>
    </td>
    
    <td>
      No default
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        KEY=""
      </code>
    </td>
    
    <td>
      The default is an empty string
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        KEY='["read"]'
      </code>
    </td>
    
    <td>
      A JSON default for an array or object, in quotes
    </td>
  </tr>
</tbody>
</table>

This is stricter than the usual tools. [dotenv-safe](https://www.npmjs.com/package/dotenv-safe) treats example values as documentation, and dotenv reads `KEY=` as an empty string. Here an assigned value ships as a real default, so a placeholder like `changeme` belongs in `@example`.

Each default is checked against its type when the module reads the file, and a bad one fails with the file, line and key:

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Accepted default
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Anything. It keeps its exact content, including leading zeros and whitespace inside quotes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      Decimal notation, with exponents. Not hexadecimal, <code>
        NaN
      </code>
      
       or <code>
        Infinity
      </code>
      
      . Surrounding whitespace is trimmed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
      , <code>
        false
      </code>
      
      , <code>
        1
      </code>
      
       or <code>
        0
      </code>
      
      . Surrounding whitespace is trimmed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        enum
      </code>
    </td>
    
    <td>
      One of the listed choices.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      A URI exactly as written, with no surrounding whitespace. Use Punycode for international hostnames, such as <code>
        https://xn--r8jz45g.xn--zckzah
      </code>
      
       for <code>
        https://例え.テスト
      </code>
      
      , and percent-encode spaces and non-ASCII path characters. The same rule applies at server start.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        array
      </code>
      
      , <code>
        object
      </code>
    </td>
    
    <td>
      Quoted JSON whose members already match their types. Members are never converted, so <code>
        "false"
      </code>
      
       fails a <code>
        boolean
      </code>
      
       property.
    </td>
  </tr>
</tbody>
</table>

## Empty values

On a required entry, `KEY=""` fails when the module reads the file, and an empty value at server start fails validation. An optional string keeps `""`. For any other optional type, empty means unset, so starting the server with `NUXT_REQUEST_LIMIT=` for an `@optional @type=number` entry gives `undefined`.

## Rejected syntax

The module rejects anything it can't check statically, instead of declaring a type it can't enforce:

- `$VAR` and `${VAR}` references. Single quotes or `\$` make them literal text.
- `$(command)` substitutions and calls such as `fetchSecret(ref)`
- unquoted `[a, b]` and `{key=value}` values. Quote JSON defaults instead.
- dynamic decorator values such as `@required=forEnv(production)`
- custom types and unknown type arguments
- JSON nested deeper than 64 levels, and the keys `__proto__`, `prototype`, `constructor` and `__envSchemaUnset` in any JSON object

Error messages give the file, line, key and reason. They never include an assigned value.


## Sitemap

See the full [sitemap](https://nuxt-safe-runtime-config.onmax.me/sitemap.md) for all pages.
