Nacos Node.js SDK

Starting from version 2.6.3, the SDK supports multiple methods for Aliyun RAM identity configuration. All methods resolve to AccessKeyId, AccessKeySecret, and an optional SecurityToken. The SDK then generates the necessary Nacos authentication fields for Config and Naming clients.

Supported Methods

1. Legacy AK/SK: Use accessKey/secretKey for NacosConfigClient or ak/sk for NacosNamingClient.
2. Static STS Credentials: Provide alibabaCloudAccessKeyId, alibabaCloudAccessKeySecret, and alibabaCloudSecurityToken in the client options.
3. Environment Variables: Set ALIBABA_CLOUD_ACCESS_KEY_ID, ALIBABA_CLOUD_ACCESS_KEY_SECRET, and ALIBABA_CLOUD_SECURITY_TOKEN.
4. Credentials URI: Provide an alibabaCloudCredentialsUri pointing to a JSON endpoint returning credentials.
5. Security Credentials JSON: Provide a stringified JSON object via securityCredentials (compatible with Java client keys).
6. Security Credentials URL & ECS RAM Role: Use securityCredentialsUrl (with cacheSecurityCredentials and timeToRefreshInMillisecond) or ramRoleName for ECS environments.
7. Custom Providers: For RoleArn, OIDC/RRSA, or KMS rotation, implement an aliyunCredentialsProvider or alibabaCloudCredentialsProvider function that returns the credential object.

// Example: Static STS credentials
const clientOptions = {
  serverAddr: '127.0.0.1:8848',
  alibabaCloudAccessKeyId: 'AccessKeyId',
  alibabaCloudAccessKeySecret: 'AccessKeySecret',
  alibabaCloudSecurityToken: 'SecurityToken',
};

The NacosNamingClient allows you to register service instances, query them, and subscribe to changes.

Basic Usage Example

const { NacosNamingClient } = require('nacos');

const client = new NacosNamingClient({
  logger: console,
  serverList: '127.0.0.1:8848',
  namespace: 'public',
});
await client.ready();

const serviceName = 'nodejs.test.domain';

// Register an instance
await client.registerInstance(serviceName, {
  ip: '1.1.1.1',
  port: 8080,
});

// Subscribe to instance changes (push notification)
client.subscribe(serviceName, hosts => {
  console.log(hosts);
});

// Query all instances
const hosts = await client.getAllInstances(serviceName);

// Select healthy instances only
const healthy = await client.selectInstances(serviceName);

// Deregister instance
await client.deregisterInstance(serviceName, {
  ip: '1.1.1.1',
  port: 8080,
});

const { NacosNamingClient } = require('nacos');

const client = new NacosNamingClient({
  logger: console,
  serverList: '127.0.0.1:8848',
  namespace: 'public',
});
await client.ready();

const serviceName = 'nodejs.test.domain';

// register instance
await client.registerInstance(serviceName, {
  ip: '1.1.1.1',
  port: 8080,
});

// subscribe to instance changes (push notification)
client.subscribe(serviceName, hosts => {
  console.log(hosts);
});

// query all instances
const hosts = await client.getAllInstances(serviceName);
console.log(hosts);

// select healthy instances only
const healthy = await client.selectInstances(serviceName);
console.log(healthy);

// deregister instance
await client.deregisterInstance(serviceName, {
  ip: '1.1.1.1',
  port: 8080,
});

To use the Nacos configuration service, instantiate NacosConfigClient. You can use two different connection modes:

1. Addressing Mode (寻址模式): Used for cloud environments (like Aliyun ACM). Requires endpoint, namespace, accessKey, and secretKey.
2. Direct Connection Mode (直连模式): Used for connecting directly to a Nacos server instance. Requires serverAddr (IP and port).

Common options include requestTimeout (defaults to 6000ms).

import {NacosConfigClient} from 'nacos'; // TypeScript
// OR
const {NacosConfigClient} = require('nacos'); // JavaScript

// Addressing Mode
const configClient = new NacosConfigClient({
  endpoint: 'acm.aliyun.com',
  namespace: '***************',
  accessKey: '***************',
  secretKey: '***************',
  requestTimeout: 6000,
});

// Direct Connection Mode
const configClient = new NacosConfigClient({
  serverAddr: '127.0.0.1:8848',
});

The NacosConfigClient allows you to manage remote configurations, including publishing, retrieving, and subscribing to changes.

Basic Usage Example

const { NacosConfigClient } = require('nacos');

const configClient = new NacosConfigClient({
  serverAddr: '127.0.0.1:8848',
  namespace: 'public',
});
await configClient.ready();

// Publish config
await configClient.publishSingle('test', 'DEFAULT_GROUP', 'hello=world');

// Get config
const content = await configClient.getConfig('test', 'DEFAULT_GROUP');

// Subscribe to config changes
configClient.subscribe({ dataId: 'test', group: 'DEFAULT_GROUP' }, content => {
  console.log('config changed:', content);
});

// Remove config
await configClient.remove('test', 'DEFAULT_GROUP');

const { NacosConfigClient } = require('nacos');

const configClient = new NacosConfigClient({
  serverAddr: '127.0.0.1:8848',
  namespace: 'public',
});
await configClient.ready();

// publish config
await configClient.publishSingle('test', 'DEFAULT_GROUP', 'hello=world');

// publish config with CAS (compare-and-set):
// succeeds only when the md5 of the current server-side config equals casMd5
const crypto = require('crypto');
const currentContent = await configClient.getConfig('test', 'DEFAULT_GROUP');
const casMd5 = crypto.createHash('md5').update(currentContent || '').digest('hex');
const published = await configClient.publishConfigCas('test', 'DEFAULT_GROUP', 'hello=nacos', casMd5);
console.log('cas publish:', published); // false when casMd5 mismatched

// get config
const content = await configClient.getConfig('test', 'DEFAULT_GROUP');
console.log('content:', content);

// subscribe to config changes (push notification)
configClient.subscribe({ dataId: 'test', group: 'DEFAULT_GROUP' }, content => {
  console.log('config changed:', content);
});

// remove config
await configClient.remove('test', 'DEFAULT_GROUP');

To use service discovery, instantiate NacosNamingClient with a serverList and namespace. You must call await client.ready() before performing operations. The client allows you to register service instances, subscribe to changes in service instances, and deregister instances.

'use strict';

const NacosNamingClient = require('nacos').NacosNamingClient;
const logger = console;

const client = new NacosNamingClient({
  logger,
  serverList: '127.0.0.1:8848', // replace to real nacos serverList
  namespace: 'public',
});
await client.ready();

const serviceName = 'nodejs.test.domain';

// registry instance
await client.registerInstance(serviceName, {
  ip: '1.1.1.1',
  port: 8080,
});
await client.registerInstance(serviceName, {
  ip: '2.2.2.2',
  port: 8080,
});

// subscribe instance
client.subscribe(serviceName, hosts => {
  console.log(hosts);
});

// deregister instance
await client.deregisterInstance(serviceName, {
  ip: '1.1.1.1',
  port: 8080,
});

To prevent overwriting changes made by other clients, use publishConfigCas. This method succeeds only if the MD5 hash of the current server-side configuration matches the casMd5 you provide.

const crypto = require('crypto');

// 1. Get current content
const currentContent = await configClient.getConfig('test', 'DEFAULT_GROUP');

// 2. Calculate MD5 of current content
const casMd5 = crypto.createHash('md5').update(currentContent || '').digest('hex');

// 3. Attempt to publish with the MD5
const published = await configClient.publishConfigCas('test', 'DEFAULT_GROUP', 'new_content', casMd5);

if (published) {
  console.log('Update successful');
} else {
  console.log('Update failed: MD5 mismatch (someone else updated the config)');
}

const crypto = require('crypto');
const currentContent = await configClient.getConfig('test', 'DEFAULT_GROUP');
const casMd5 = crypto.createHash('md5').update(currentContent || '').digest('hex');
const published = await configClient.publishConfigCas('test', 'DEFAULT_GROUP', 'hello=nacos', casMd5);
console.log('cas publish:', published); // false when casMd5 mismatched