{"id":17188,"library":"cloud-config-client","title":"Node.js Spring Cloud Config Client","description":"The `cloud-config-client` library provides a Node.js implementation for connecting to and consuming configuration from a Spring Cloud Config Server. Currently at version 1.6.2, it enables Node.js applications to fetch dynamic configurations, supporting application names, profiles, and labels as defined by the Spring Cloud specification. It handles property resolution based on Spring's hierarchy rules and offers a simple API for retrieving values by key, including context-based substitutions. The library provides both Promise-based and Node.js-style callback interfaces for configuration loading and ships with TypeScript types for enhanced developer experience. It differentiates itself by offering a direct, opinionated integration with the Spring Cloud Config ecosystem within Node.js environments, rather than a generic key-value store client.","status":"active","version":"1.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/victorherraiz/cloud-config-client","tags":["javascript","Spring Cloud Config","configuration","client","typescript"],"install":[{"cmd":"npm install cloud-config-client","lang":"bash","label":"npm"},{"cmd":"yarn add cloud-config-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add cloud-config-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"`client` is the default export (an object containing the `load` function) for ESM consumption.","wrong":"import { client } from 'cloud-config-client';","symbol":"client","correct":"import client from 'cloud-config-client';"},{"note":"This is the primary CommonJS import style shown in the README. The `client` object contains the `load` function.","wrong":"const { load } = require('cloud-config-client');","symbol":"client","correct":"const client = require('cloud-config-client');"},{"note":"Used for type hinting the configuration object returned by `client.load()` in TypeScript.","symbol":"Config","correct":"import { Config } from 'cloud-config-client';"}],"quickstart":{"code":"import client, { Config } from 'cloud-config-client';\nimport * as https from 'https';\n\nasync function fetchConfig() {\n  try {\n    // Ensure CONFIG_SERVER_URL, CONFIG_USERNAME, CONFIG_PASSWORD are set in environment\n    const config: Config = await client.load({\n      endpoint: process.env.CONFIG_SERVER_URL ?? 'http://localhost:8888',\n      name: 'my-application', // 'application' is deprecated, use 'name'\n      profiles: ['development', 'aws'],\n      label: 'main',\n      auth: {\n        user: process.env.CONFIG_USERNAME ?? 'configuser',\n        pass: process.env.CONFIG_PASSWORD ?? 'configpassword'\n      },\n      // Reject unauthorized (self-signed) certificates in production, allow in dev\n      rejectUnauthorized: process.env.NODE_ENV === 'production',\n      // Provide environment variables as context for placeholder substitution\n      context: {\n        ...process.env,\n        APP_VERSION: '1.0.0' // Custom context value\n      },\n      headers: {\n        'X-Trace-ID': 'my-app-trace-123'\n      },\n      agent: process.env.HTTPS_PROXY ? new https.Agent({ proxy: process.env.HTTPS_PROXY }) : undefined\n    });\n\n    console.log('Configuration loaded successfully!');\n\n    const databaseUrl = config.get('database.url');\n    console.log(`Database URL: ${databaseUrl}`);\n\n    const welcomeMessage = config.get('app.message', 'key01'); // Example with prefix\n    console.log(`Welcome Message: ${welcomeMessage}`);\n\n    // Iterate over all properties (excluding overridden by default)\n    console.log('\\nAll properties:');\n    config.forEach((key, value) => {\n      console.log(`  ${key}: ${value}`);\n    });\n\n    // Access raw properties if needed\n    // console.log('\\nRaw config properties:', config.raw);\n\n  } catch (error: any) {\n    console.error('Failed to load configuration:', error.message);\n    if (error.response) {\n      console.error('Server response status:', error.response.status);\n    }\n  }\n}\n\nfetchConfig();\n","lang":"typescript","description":"Demonstrates fetching configuration asynchronously, including basic authentication, profile and label usage, context-based substitutions, and handling of self-signed certificates."},"warnings":[{"fix":"Use the 'name' parameter instead of 'application' for specifying the application name: `{ name: 'your-app-name' }`.","message":"The 'application' parameter in `client.load()` options is deprecated. It may be removed in a future major version.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Set `rejectUnauthorized: false` in the `client.load()` options when connecting to servers with self-signed certificates (caution: only for non-production environments).","message":"By default, the client rejects unauthorized (self-signed) SSL certificates when connecting to the Spring Cloud Config Server over HTTPS. This can cause connection issues in development environments or with custom certificate authorities.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure your Node.js environment is updated to version 10 or newer.","message":"The library requires Node.js version 10 or higher. Running on older Node.js versions may lead to unexpected errors or unsupported syntax, particularly with async/await and newer language features.","severity":"gotcha","affected_versions":"<10.0.0"},{"fix":"Do not attempt to use SpEL syntax within context references; provide simple key-value pairs in the `context` option for direct string substitution.","message":"Context references in configuration properties (e.g., '${KEY:DEFAULT}') are a simple string substitution mechanism and do NOT support Spring Expression Language (SpEL) features. Attempting to use SpEL syntax will not work as expected.","severity":"gotcha","affected_versions":">=1.4.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Replace `application` with `name` in the `client.load()` options: `{ name: 'your-app-name' }`.","cause":"Using the deprecated `application` parameter in `client.load()` options.","error":"Parameter 'application' is deprecated. Use 'name' instead."},{"fix":"For development/testing, set `rejectUnauthorized: false` in the `client.load()` options. For production, ensure a valid, trusted certificate is used or properly configured on the server.","cause":"Attempting to connect to a Spring Cloud Config Server over HTTPS with a self-signed or untrusted certificate, while `rejectUnauthorized` is true (default).","error":"Error: self-signed certificate in certificate chain"},{"fix":"Provide correct `auth` object in `client.load()` options (e.g., `{ auth: { user: 'username', pass: 'password' } }`) or embed credentials directly in the `endpoint` URL (`http://user:pass@localhost:8888`).","cause":"Missing or incorrect basic authentication credentials for accessing the Spring Cloud Config Server.","error":"Config server responded with 401 Unauthorized"},{"fix":"For CommonJS: `const client = require('cloud-config-client');`. For ESM/TypeScript: `import client from 'cloud-config-client';`.","cause":"Incorrectly importing the `client` object, e.g., using named import syntax for a default export in CommonJS or destructuring directly.","error":"TypeError: client.load is not a function"}],"ecosystem":"npm","meta_description":null}