SDK Node.js

Carrega secrets directament en una aplicació Node.js en iniciar-se.

Node.js SDK

Carrega secrets directament a la teva aplicació Node.js a l'inici. API asíncrona amb façana d'una línia o constructor fluent per a control total.

📦 npm v1.1.0

Instal·lació

npm install @envilder/sdk

Inici ràpid: una línia

Carrega secrets des d'un fitxer de mapeig i injecta'ls a 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;

Resoldre sense injectar

Obté secrets com un Map sense modificar l'entorn:

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

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

Constructor fluent amb sobreescriptures

Sobreescriu la configuració del proveïdor de manera programàtica amb l'API fluent:

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();

Càrrega basada en entorn

Recomanat per a aplicacions multi-entorn. Mapeja cada entorn al seu fitxer de secrets:

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ó de secrets

Validació opcional que assegura que tots els secrets resolts tenen valors no buits:

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

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

Validació del contracte del fitxer de mapatge

Comprova, sense carregar res i sense fer servir ni mostrar cap valor, que el fitxer de mapatge és vàlid i que cada secret declarat existeix amb les credencials actuals: la mateixa comprovació que envilder validate. Els errors de validació esperats es retornen al resultat en lloc de llançar-se; un fitxer de mapatge inexistent sí que llança un error. Cada clau informa exists, missing, access_denied, authentication_failed o provider_error:

Consulta la referència d'envilder validate per als estats i els permisos que necessita la comprovació →

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}`);
  }
}

Per fer fallar la càrrega, activa la validació del contracte al builder. La comprovació s'executa una vegada abans de resoldre i l'error anomena les claus que fallen, mai els seus valors. Està desactivada per defecte, així que una càrrega normal no fa cap crida extra al proveïdor. A diferència de la validació de secrets, que revisa els valors resolts, revisa el fitxer de mapatge i les claus abans de resoldre:

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

💡

Exemples executables. Un projecte Vitest amb Testcontainers i un AppHost d'Aspire en TypeScript que resolen un fitxer de mapeig contra AWS SSM i Azure Key Vault (emulats amb LocalStack i Lowkey Vault) i passen els valors als contenidors, sense cap fitxer .env: typescript-testcontainers · typescript-aspire

Documentació completa →