compose-env-vault

HashiCorp Vault KV v2 source adapter for compose-env.

Installation

npm install compose-env-vault

compose-env must also be installed in your project. No other runtime dependencies are required — the adapter uses the native fetch API (Node.js 18+).

Usage

import { defineConfig, source } from 'compose-env'
import { vaultSource } from 'compose-env-vault'

const config = await defineConfig(
  {
    DATABASE_URL: { type: 'url',    required: true, secret: true },
    API_KEY:      { type: 'string', required: true, secret: true },
    PORT:         { type: 'port',   default: 3000 },
  },
  {
    sources: [
      vaultSource('myapp/config'),
      source.env(),
    ],
  },
)

The adapter reads the secret at GET {VAULT_ADDR}/v1/{mount}/data/{secretPath} and returns all key-value pairs stored in it directly as env vars.

Authentication

Set the following environment variables before running your application:

VAULT_ADDR=https://vault.example.com
VAULT_TOKEN=s.xxxxxxxxxxxxxxxx

Or pass them directly in options:

vaultSource('myapp/config', {
  address: 'https://vault.example.com',
  token: process.env.VAULT_TOKEN,
})

Options

| Option | Type | Default | Description | |-----------|----------|--------------------------------|-----------------------------------------------------| | address | string | process.env.VAULT_ADDR | Vault server URL. | | token | string | process.env.VAULT_TOKEN | Vault token for authentication. | | mount | string | 'secret' | KV v2 mount path. Change if your mount is named differently (e.g. 'kv'). |

Custom Mount Path

If your KV v2 engine is mounted at a path other than secret:

vaultSource('myapp/config', { mount: 'kv' })
// Reads from: GET {VAULT_ADDR}/v1/kv/data/myapp/config

Error Handling

The adapter throws descriptive errors for common failure cases:

| Situation | Error message | |-----------|---------------| | VAULT_ADDR not set | Vault address not configured. Set the VAULT_ADDR environment variable... | | VAULT_TOKEN not set | Vault token not configured. Set the VAULT_TOKEN environment variable... | | Secret path not found | Secret not found at 'myapp/config' (mount: 'secret') | | Permission denied | Permission denied reading 'myapp/config'. Check your Vault token. |

Source Priority

Sources are resolved in order. Place vaultSource before or after source.env() depending on which should take precedence:

// Vault overrides local .env files
sources: [source.env(), vaultSource('myapp/config')]

// Local .env files override Vault (useful for local development)
sources: [vaultSource('myapp/config'), source.env()]