Quickstart (Node.js)

Install

npm install @secrefs/node

pnpm add @secrefs/node

yarn add @secrefs/node

Try it without a vault

The local provider reads a gitignored JSON file, so you can see the mechanism work before wiring up AWS or Bitwarden.

Create a mock vault

.secrefs.local.json

{ "demo-db": { "password": "hunter2", "user": "postgres" } }

Add .secrefs.local.json to your .gitignore. It holds real values — it is the one file in this workflow that does.

Write a reference instead of a value

.env

PORT=3000
DB_PASSWORD=sec://local/demo-db#password

This file is safe to commit.

Run your app through SecRefs

npx secrefs run -- node server.js

secrefs: resolved 1 secret reference(s): DB_PASSWORD

Your app reads process.env.DB_PASSWORD exactly as before. Nothing downstream changes.

Point it at a real vault

Swap the provider segment. Nothing else about your app changes:

.env

DB_PASSWORD=sec://aws/prod/db#password

SecRefs uses the credentials you already have — the AWS credential chain, a Bitwarden machine account token, VAULT_TOKEN. It never asks you to put a credential in its own config. See AWS, Bitwarden, and Vault.

Use it as a library

import { secRefs } from "@secrefs/node";

// Expand everything in process.env, once, at boot.
await secRefs.init();

// Or resolve a single reference at the point of use.
const key = await secRefs.expandString("sec://aws/prod/stripe#key");

Check before you deploy

check validates every reference it can see and never returns a plaintext value, so it is safe to run in CI:

npx secrefs check

It catches a typo’d path before it pages someone at 3am.

Load time vs use time

init() and expandString() behave differently when a secret rotates. The difference matters — read this before choosing.

Getting started

Providers

Guides

Reference

Quickstart (Node.js)

Install

Try it without a vault

Point it at a real vault

Use it as a library

Check before you deploy

Load time vs use time

​Install

​Try it without a vault

​Point it at a real vault

​Use it as a library

​Check before you deploy

Load time vs use time

Install

Try it without a vault

Point it at a real vault

Use it as a library

Check before you deploy