SDK Node.js

Carga secretos directamente en una aplicación Node.js al iniciarse.

Node.js SDK

Carga secretos directamente en tu aplicación Node.js al inicio. API asíncrona con fachada de una línea o constructor fluido para control total.

📦 npm v1.1.0

Instalación

npm install @envilder/sdk

Inicio rápido: una línea

Carga secretos desde un archivo de mapeo e inyéctalos en process.env:

import { Envilder } from '@envilder/sdk';

// Resolve secrets and inject into process.env
await Envilder.load('envilder.json');

const dbPassword = process.env.DB_PASSWORD;

Resolver sin inyectar

Obtén secretos como un Map sin modificar el entorno:

import { Envilder } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
const dbPassword = secrets.get('DB_PASSWORD');

Constructor fluido con sobreescrituras

Sobreescribe la configuración del proveedor de forma programática con la API fluida:

import { Envilder, SecretProviderType } from '@envilder/sdk';

const secrets = await Envilder.fromMapFile('envilder.json')
  .withProvider(SecretProviderType.Azure)
  .withVaultUrl('https://my-vault.vault.azure.net')
  .resolve();

// Or inject directly
await Envilder.fromMapFile('envilder.json')
  .withProfile('staging')
  .inject();

Carga basada en entorno

Recomendado para aplicaciones multi-entorno. Mapea cada entorno a su archivo de secretos:

import { Envilder } from '@envilder/sdk';

const env = process.env.APP_ENV ?? 'development';

await Envilder.load(env, {
  production: 'prod-secrets.json',
  development: 'dev-secrets.json',
  test: null,  // no secrets loaded
});

Validación de secretos

Validación opcional que asegura que todos los secretos resueltos tienen valores no vacíos:

import { Envilder, validateSecrets } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
validateSecrets(secrets); // throws SecretValidationError if any value is empty

Validación del contrato del fichero de mapeo

Comprueba, sin cargar nada y sin usar ni mostrar ningún valor, que el fichero de mapeo es válido y que cada secreto declarado existe con las credenciales actuales: la misma comprobación que envilder validate. Los errores de validación esperados se devuelven en el resultado en lugar de lanzarse; un fichero de mapeo inexistente sí lanza un error. Cada clave informa exists, missing, access_denied, authentication_failed o provider_error:

Consulta la referencia de envilder validate para los estados y los permisos que necesita la comprobación →

import { Envilder } from '@envilder/sdk';

const result = await Envilder.fromMapFile('envilder.json').validateContract();
if (!result.isValid) {
  for (const error of result.mapFileErrors) {
    console.log(`${error.key}: ${error.message}`);
  }
  for (const key of result.keys.filter((k) => k.status !== 'exists')) {
    console.log(`${key.variable} (${key.path}): ${key.status}`);
  }
}

Para que la carga falle, activa la validación del contrato en el builder. La comprobación se ejecuta una vez antes de resolver y el error nombra las claves que fallan, nunca sus valores. Está desactivada por defecto, así que una carga normal no hace ninguna llamada extra al proveedor. A diferencia de la validación de secretos, que revisa los valores resueltos, revisa el fichero de mapeo y las claves antes de resolver:

await Envilder.fromMapFile('envilder.json')
  .withContractValidation()
  .inject(); // throws ContractValidationError

💡

Ejemplos ejecutables. Un proyecto Vitest con Testcontainers y un AppHost de Aspire en TypeScript que resuelven un archivo de mapeo contra AWS SSM y Azure Key Vault (emulados con LocalStack y Lowkey Vault) y pasan los valores a los contenedores, sin ningún archivo .env: typescript-testcontainers · typescript-aspire

Documentación completa →