Overview

Since v3.1, @cloudbase/js-sdk has a built-in Node.js adapter. You no longer need to install @cloudbase/node-sdk or @cloudbase/adapter-node separately to use the full CloudBase capabilities in Node.js environments (cloud functions, CloudBase Run, self-hosted servers, etc.).

Note

Node.js version >= 16.0 is required

Installation

# npm
npm install @cloudbase/js-sdk@next -S

# yarn
yarn add @cloudbase/js-sdk@next

Some server-side features depend on the following optional packages. Install them as needed:

Package	Purpose	When to Install
@cloudbase/signature-nodejs	Request signing (TC3-HMAC-SHA256)	When using secretId / secretKey auth
jsonwebtoken	Custom login ticket signing	When calling auth.createTicket
ws	WebSocket connection	When using real-time data push

# Install as needed
npm install @cloudbase/signature-nodejs jsonwebtoken ws

Initialization

Basic Usage

const cloudbase = require("@cloudbase/js-sdk");

const app = cloudbase.init({
  env: "your-env-id", // Replace with your environment ID
});

Initialization Parameters

Field	Type	Required	Description
env	string	No	TCB environment ID. If not specified in a cloud function environment, the current environment ID is used
accessKey	string	No	Cloudbase API Key, the highest priority authentication method. Can also be configured via the CLOUDBASE_APIKEY environment variable
auth	object	No	Authentication configuration, including secretId, secretKey, credentials, etc.
auth.secretId	string	No	Tencent Cloud API key pair. Generate at Tencent Cloud Console / API Key Management. Can also be configured via the TENCENTCLOUD_SECRETID environment variable
auth.secretKey	string	No	Tencent Cloud API key pair. Can also be configured via the TENCENTCLOUD_SECRETKEY environment variable
auth.credentials	object	No	Custom login private key, containing private_key, private_key_id, env_id, used for createTicket to issue login credentials. Download the private key from CloudBase Console / Authentication / Login Methods under "Custom Login"
context	object	No	The context parameter of the function-based CloudBase Run entry function, used for signature-free calls
timeout	number	No	Request timeout (ms), default 15000

Authentication

The server SDK can access CloudBase resources using different authentication methods. The following methods are supported (choose one):

Authentication Method	Description
Default (Cloud Function / CloudBase Run)	No parameters needed; credentials are automatically read from environment variables
API Key	Configure the server API Key in the CLOUDBASE_APIKEY environment variable; the SDK reads it automatically
Publishable Key	Pass accessKey in init to access with anonymous role identity
secretId + secretKey	Explicitly pass Tencent Cloud API key pair in init
context	In CloudBase Run, use the entry function's context parameter for signature-free calls

Authentication Examples

Cloud Function (Default Auth)

In a cloud function environment, the SDK automatically reads authentication info from environment variables. These are temporary credentials and require no manual configuration.

const cloudbase = require("@cloudbase/js-sdk");

const app = cloudbase.init({
  env: "your-env-id",
});

exports.main = async (event, context) => {
  // Use CloudBase capabilities directly
};

CloudBase Run

In a function-based CloudBase Run environment, pass the context parameter for signature-free calls.

💡 Note: If context is provided but env is not, the envID from context will be used as the environment ID.

const cloudbase = require("@cloudbase/js-sdk");

exports.main = async (event, context) => {
  const app = cloudbase.init({
    context,
  });
  // Use CloudBase capabilities
};

Publishable Key

For detailed information about Publishable Key, please refer to the documentation.

• User Permissions: Anonymous user permissions
• Validity: Long-term valid
• How to Obtain: Get it from CloudBase Console / ApiKey Management

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  accessKey: "your-publishable-key",
});

secretId + secretKey

Generate a key pair at Tencent Cloud Console / API Key Management.

const cloudbase = require("@cloudbase/js-sdk");

const app = cloudbase.init({
  env: "your-env-id",
  auth: {
    secretId: "your-secretId",
    secretKey: "your-secretKey",
  },
});

API Key

Configure via the CLOUDBASE_APIKEY environment variable. In cloud functions, enable API key settings and add CLOUDBASE_APIKEY; the SDK reads it automatically.

const cloudbase = require("@cloudbase/js-sdk");

// No need to pass explicitly; the SDK reads from environment variables automatically
const app = cloudbase.init({
  env: "your-env-id",
});

---

Environment Info

parseContext

app.parseContext(context: object): object

Parses the context parameter of the cloud function entry function, converting runtime environment variables into a structured object.

• Only effective in cloud function environments

参数

context

object

The context parameter of the cloud function entry function

返回

Return Value

Object

memory_limit_in_mb可选number

Cloud function memory limit

time_limit_in_ms可选number

Runtime limit

request_id可选string

Request ID

environ可选object

Environment variables object (including custom environment variables)

function_version可选string

Cloud function version

function_name可选string

Cloud function name

namespace可选string

Namespace

示例

---

Identity Authentication

In addition to the following server-specific APIs, the server SDK can also call all client-side authentication APIs, such as email login, phone login, username/password login, linked login, etc. See Authentication for details.

getUserInfo

auth.getUserInfo(): IGetUserInfoResult

Gets the current request's user information (synchronous method, reads from cloud function runtime environment variables).

• Synchronous method, no await needed
• Only effective in cloud function / CloudBase Run environments

参数

无参数

返回

IGetUserInfoResult

Object

openId可选string

WeChat openId, empty if not logged in via WeChat

appId可选string

WeChat appId, empty if not logged in via WeChat

uid可选string

User unique ID

customUserId可选string

Developer-defined custom user unique ID, empty if not using custom login

示例

---

getEndUserInfo

async auth.getEndUserInfo(uid?: string): Promise<IGetEndUserInfoResult>

Gets detailed end-user information.

• When uid is not provided, returns the current request user's information
• When uid is provided, calls the admin API to query the specified user
• No permission to call this API when using API Key or Publishable Key

参数

uid

string

CloudBase user identity. If not provided, reads the current user info from environment variables

返回

Promise

IGetEndUserInfoResult

userInfoEndUserInfo

CloudBase user information

openId

可选

string

WeChat openId, empty if not logged in via WeChat

appId

可选

string

WeChat appId, empty if not logged in via WeChat

uid

可选

string

User unique ID

customUserId

可选

string

Developer-defined custom user unique ID

envName

可选

string

CloudBase environment name

nickName

可选

string

User nickname

email

可选

string

User login email

username

可选

string

User login username

hasPassword

可选

boolean

Whether the user has set a password

gender

可选

"MALE" | "FEMALE" | "UNKNOWN"

User gender

country

可选

string

Geographic location (country)

province

可选

string

Geographic location (province)

city

可选

string

Geographic location (city)

avatarUrl

可选

string

User avatar URL

requestId可选string

Unique request identifier

示例

---

queryUserInfo

async auth.queryUserInfo(query: IUserInfoQuery): Promise<any>

Queries user information by conditions.

• Supports querying by uid, platform, and platformId
• If uid is specified, it takes priority
• No permission to call this API when using API Key or Publishable Key

参数

query

IUserInfoQuery

uid可选string

User unique ID. If specified, takes priority

platform可选string

Login type, supports PHONE, USERNAME, EMAIL, CUSTOM

platformId可选string

Login identifier, corresponding to platform: phone number, username, email, or custom login ID

返回

Promise

Object

userInfoEndUserInfo

CloudBase user information (same fields as getEndUserInfo)

requestId可选string

Unique request identifier

示例

---

getClientIP

auth.getClientIP(): string

Gets the client IP address.

• Synchronous method, reads from the TCB_SOURCE_IP environment variable
• Only effective in cloud function / CloudBase Run environments

参数

无参数

返回

Return Value

string

Client IP address

示例

---

createTicket

async auth.createTicket(uid: string, options?: ICreateTicketOpts): Promise<string>

Creates a custom login credential Ticket, signed as a JWT using an RSA private key. The client can exchange this Ticket for a login session.

• Requires auth.credentials (custom login private key) to be passed in init
• Download the private key file from CloudBase Console / Authentication / Login Methods under "Custom Login"
• Requires dependency: npm install jsonwebtoken

参数

uid

string

Developer-defined unique user ID (4-32 characters, supports letters, numbers, and some special characters)

options

ICreateTicketOpts

refresh可选number

access_token refresh interval (ms), default 3600000 (1 hour)

expire可选number

access_token expiration timestamp (ms), default 7 days from now

返回

Promise

string

Custom login credential Ticket, in the format "{private_key_id}/@@/{jwt_token}"

示例

---

CloudBase Capabilities

The server SDK shares the same API as the client SDK. The following CloudBase capabilities are called in the same way as on the client side. Please refer to the corresponding documentation:

Capability	Documentation Link
Cloud Functions	Cloud Functions
CloudBase Run	CloudBase Run
Cloud Storage	Cloud Storage
Document Database	Document Database
MySQL Database	MySQL Database
Data Models	Data Models
AI	AI
APIs	APIs

Note

When not using API Key or Publishable Key, the server uses admin permissions by default. Other than that, the API signatures, parameters, and return values are the same as the client side.

---

Notifications

sendTemplateNotification

app.sendTemplateNotification(params: object, opts?: object): Promise<object>

Sends a template message notification.

• Notification policies must be pre-configured in CloudBase Console / Notification Management
• Trigger method should be set to "Manual Trigger"

参数

params

Object

notifyIdstring

Notification policy ID

data可选Record<string, any>

Template variable key-value pairs

url可选string

URL to open when the user clicks the notification

opts

Object

timeout可选number

Request timeout (ms)

返回

Promise

Object

result可选any

Execution result

requestId可选string

Unique request ID for troubleshooting

示例

---

Complete Example

Here is an example that demonstrates the comprehensive use of various server-side capabilities in a cloud function:

const cloudbase = require("@cloudbase/js-sdk");

const app = cloudbase.init({
  env: "your-env-id",
  auth: {
    credentials: require("./tcb_custom_login.json"), // Optional: custom login private key
  },
});

const db = app.database();

exports.main = async (event, context) => {
  const { action } = event;

  switch (action) {
    // Identity Authentication (server-specific)
    case "getUserInfo": {
      return app.auth.getUserInfo();
    }
    case "getEndUserInfo": {
      return app.auth.getEndUserInfo(event.uid);
    }
    case "createTicket": {
      return app.auth.createTicket(event.customUserId, {
        refresh: 3600 * 1000,
      });
    }

    // Database Operations (same as client-side)
    case "dbQuery": {
      return db.collection("todos").where({ completed: false }).get();
    }

    // Cloud Function Invocation (same as client-side)
    case "callFunction": {
      return app.callFunction({
        name: "another-function",
        data: { key: "value" },
      });
    }

    // Cloud Storage (same as client-side)
    case "getTempFileURL": {
      return app.getTempFileURL({
        fileList: ["cloud://env-id.xxx/images/photo.png"],
      });
    }

    // Environment Info (server-specific)
    case "parseContext": {
      return app.parseContext(context);
    }

    // Notifications (server-specific)
    case "notify": {
      return app.sendTemplateNotification({
        notifyId: "xxx",
        data: event.notifyData,
        url: event.notifyUrl,
      });
    }

    default:
      return { error: `Unknown action: ${action}` };
  }
};