{"id":16658,"library":"node-vault-client","title":"Node.js HashiCorp Vault Client","description":"node-vault-client is a pure JavaScript client library designed for interacting with HashiCorp Vault, specifically tailored for Node.js environments. Currently at version 1.0.2, this library provides core functionalities for reading, listing, and writing secrets, as well as managing authentication tokens. It supports various Vault Auth Backends, including AWS IAM, AppRole, and Token-based authentication, and crucially handles the automatic renewal of issued auth tokens to maintain session validity. While its release cadence appears intermittent, recent updates address critical issues, indicating ongoing maintenance. A key differentiator is its explicit focus on pure JavaScript implementation and built-in token lease renewal, which simplifies common operational patterns for Node.js applications integrating with Vault. It requires Node.js version 14 or higher and has a peer dependency on the `config` package.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/namecheap/node-vault-client","tags":["javascript"],"install":[{"cmd":"npm install node-vault-client","lang":"bash","label":"npm"},{"cmd":"yarn add node-vault-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-vault-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for managing application configuration; required as a peer dependency.","package":"config","optional":false}],"imports":[{"note":"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.","wrong":"import VaultClient from 'node-vault-client';","symbol":"VaultClient","correct":"const VaultClient = require('node-vault-client');"},{"note":"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.","wrong":"import { boot } from 'node-vault-client';","symbol":"VaultClient.boot","correct":"const VaultClient = require('node-vault-client');\nconst vaultClientInstance = VaultClient.boot('main', { /* ...options */ });"},{"note":"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.","wrong":"import type { VaultClient } from 'node-vault-client';","symbol":"VaultClient (TypeScript)","correct":"// Install @types/node-vault-client if available, or rely on inferred types."}],"quickstart":{"code":"const VaultClient = require('node-vault-client');\n\n// Initialize the Vault client. The 'boot' method handles singleton instance management.\n// Ensure VAULT_APP_ROLE_ID and VAULT_APP_ROLE_SECRET_ID environment variables are set.\nconst vaultClient = VaultClient.boot('main', {\n    api: { url: 'https://vault.example.com:8200/' }, // Replace with your Vault server URL\n    auth: {\n        type: 'appRole', // Supports 'appRole', 'token', 'iam', 'kubernetes'\n        config: {\n            role_id: process.env.VAULT_APP_ROLE_ID ?? 'your-approle-role-id',\n            secret_id: process.env.VAULT_APP_ROLE_SECRET_ID ?? 'your-approle-secret-id' // Required for AppRole\n        }\n    },\n    // Optional: Pass 'false' to disable logging, or a custom logger object.\n    logger: console\n});\n\n// Read a secret from a specified path in Vault\nvaultClient.read('secret/data/my-application/config')\n    .then(response => {\n        console.log('Successfully read secret:', response.data.data); // Vault K/V v2 stores data in .data.data\n    })\n    .catch(e => {\n        console.error('Error reading secret:', e.message);\n        // Implement robust error handling, e.g., retry logic, specific Vault error codes.\n    });\n\n// Example of writing a secret to Vault\nvaultClient.write('secret/data/my-application/settings', { value: 'some_setting', enabled: true })\n    .then(() => console.log('Successfully wrote secret.'))\n    .catch(e => console.error('Error writing secret:', e.message));","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade to `node-vault-client@0.6.1` or any subsequent version to ensure proper token handling.","message":"Versions 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.","severity":"breaking","affected_versions":"<0.6.1"},{"fix":"Upgrade 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.","message":"Attempting 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.","severity":"gotcha","affected_versions":"<1.0.1"},{"fix":"Explicitly 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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your project's Node.js runtime is version 14.0.0 or newer. Update your Node.js installation if necessary.","message":"This 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.","severity":"gotcha","affected_versions":"<14.0.0 (Node.js)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Upgrade `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).","cause":"In versions prior to 0.6.1, the Vault token might not have been correctly included in request headers.","error":"Error: Unauthorized (or similar authentication failure messages)"},{"fix":"Upgrade 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.","cause":"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.","error":"Error: Client with name 'my-client' already booted."},{"fix":"Install the `config` package: `npm install config` or `yarn add config`.","cause":"The `config` package is a peer dependency and was not installed in your project.","error":"Error: Cannot find module 'config'"},{"fix":"Change 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.","cause":"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.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}