Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VaultClient
✓ const VaultClient = require('node-vault-client');
✗ import VaultClient from 'node-vault-client';
This library is primarily distributed as a CommonJS module. Use `require()` for standard Node.js environments. Direct `import` syntax will typically fail in ESM projects without specific configuration.
VaultClient.boot
✓ const VaultClient = require('node-vault-client');
const vaultClientInstance = VaultClient.boot('main', { /* ...options */ });
✗ import { boot } from 'node-vault-client';
The `boot` method is a static function accessed via the `VaultClient` object, not a top-level named export. It's the primary way to initialize and retrieve a client instance.
VaultClient (TypeScript)
✓ // Install @types/node-vault-client if available, or rely on inferred types.
✗ import type { VaultClient } from 'node-vault-client';
As a pure JavaScript library, explicit TypeScript type exports are not directly provided by the package itself. Users relying on TypeScript might need `@types/node-vault-client` or leverage TypeScript's inference capabilities.
This quickstart demonstrates how to initialize the Vault client using AppRole authentication, read a secret, and write data to Vault. It uses environment variables for sensitive credentials.
const VaultClient = require('node-vault-client');
// Initialize the Vault client. The 'boot' method handles singleton instance management.
// Ensure VAULT_APP_ROLE_ID and VAULT_APP_ROLE_SECRET_ID environment variables are set.
const vaultClient = VaultClient.boot('main', {
api: { url: 'https://vault.example.com:8200/' }, // Replace with your Vault server URL
auth: {
type: 'appRole', // Supports 'appRole', 'token', 'iam', 'kubernetes'
config: {
role_id: process.env.VAULT_APP_ROLE_ID ?? 'your-approle-role-id',
secret_id: process.env.VAULT_APP_ROLE_SECRET_ID ?? 'your-approle-secret-id' // Required for AppRole
}
},
// Optional: Pass 'false' to disable logging, or a custom logger object.
logger: console
});
// Read a secret from a specified path in Vault
vaultClient.read('secret/data/my-application/config')
.then(response => {
console.log('Successfully read secret:', response.data.data); // Vault K/V v2 stores data in .data.data
})
.catch(e => {
console.error('Error reading secret:', e.message);
// Implement robust error handling, e.g., retry logic, specific Vault error codes.
});
// Example of writing a secret to Vault
vaultClient.write('secret/data/my-application/settings', { value: 'some_setting', enabled: true })
.then(() => console.log('Successfully wrote secret.'))
.catch(e => console.error('Error writing secret:', e.message));
Debug
Known issues
breakingVersions prior to `0.6.1` had a critical bug where the Vault token was not correctly passed in request headers, leading to authentication failures or unauthorized access attempts.fixUpgrade to `node-vault-client@0.6.1` or any subsequent version to ensure proper token handling.
affects: <0.6.1
gotchaAttempting to call `VaultClient.boot()` multiple times with the same instance `name` in versions prior to `1.0.1` could lead to unexpected behavior or errors related to client re-initialization.fixUpgrade to `node-vault-client@1.0.1` or newer, which addresses this issue. Alternatively, ensure `VaultClient.boot()` is called only once per unique client name in older versions.
affects: <1.0.1
gotchaThe package lists `config` as a peer dependency with a wide range (`>=1 <4`). While flexible, this means the `config` package must be manually installed by the user, and major version changes within that range could introduce subtle incompatibilities if not tested.fixExplicitly install the `config` package (`npm install config` or `yarn add config`) in your project. It is recommended to pin a specific major version of `config` if stability is critical.
affects: >=0.1.0
gotchaThis library requires Node.js version 14 or higher. Running it on older Node.js environments will result in runtime errors due to unsupported syntax or APIs.fixEnsure your project's Node.js runtime is version 14.0.0 or newer. Update your Node.js installation if necessary.
affects: <14.0.0 (Node.js)
Errors
Common errors & fixes
Error: Unauthorized (or similar authentication failure messages)
In versions prior to 0.6.1, the Vault token might not have been correctly included in request headers.
fixUpgrade `node-vault-client` to version `0.6.1` or later. Also, double-check your authentication configuration (e.g., AppRole `role_id` and `secret_id`, or token validity).
Error: Client with name 'my-client' already booted.
You are calling `VaultClient.boot()` with the same name multiple times without clearing it in older versions, or a previous instance was not properly managed.
fixUpgrade to `node-vault-client@1.0.1` or newer. If upgrading isn't an option, ensure `VaultClient.boot()` is called only once for a given name, or use `VaultClient.get()` to retrieve an existing instance.
Error: Cannot find module 'config'
The `config` package is a peer dependency and was not installed in your project.
fixInstall the `config` package: `npm install config` or `yarn add config`.
SyntaxError: Cannot use import statement outside a module
You are attempting to use ES module `import` syntax in a Node.js environment configured for CommonJS, or the `node-vault-client` package is being treated as CommonJS.
fixChange your import statement to use CommonJS `require()`: `const VaultClient = require('node-vault-client');`. If you must use ESM, consider a transpiler or a dynamic `import()` call if `node-vault-client` doesn't provide ESM entry points. Audit
Dependencies
configrequiredUsed for managing application configuration; required as a peer dependency.