Registry / database / wx-server-sdk

wx-server-sdk

JSON →
library3.0.4jsnpmunverified

The `wx-server-sdk` is the official Software Development Kit for interacting with WeChat Mini Program Cloud Development services from within Cloud Functions. It provides a comprehensive set of APIs for accessing cloud resources such as Cloud Database (MongoDB-like), Cloud Storage (object storage), and invoking other Cloud Functions. The SDK is designed to run in a Node.js environment, specifically within the WeChat Cloud Function runtime. The current stable version is 3.0.4, last published approximately two months ago (as of early 2026). While there isn't a strict, publicly defined release cadence, updates are regularly issued to introduce new features, improve performance, and address bugs. Its primary differentiation lies in its deep integration with the WeChat ecosystem, offering seamless backend support for Mini Programs without needing to manage traditional servers.

npm install wx-server-sdk
INSTALL
IMPORT
SIG · WX-SERVER-SDK
W
wx-server-sdk
databasejavascriptv3.0.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

cloud
import cloud from 'wx-server-sdk';
import { cloud } from 'wx-server-sdk';
The primary `cloud` object is typically imported as a default export or through `import * as cloud from 'wx-server-sdk;'` for full module access. CommonJS `require` pattern also returns the full `cloud` object.
init
import cloud from 'wx-server-sdk'; cloud.init({ env: 'your-env-id' });
const { init } = require('wx-server-sdk'); init();
The `init` function is a method of the main `cloud` object and must be called after importing `cloud`.
DB.command
import cloud from 'wx-server-sdk'; const db = cloud.database(); const _ = db.command;
import { command } from 'wx-server-sdk';
Database commands (`db.command`) are accessed via the `db` instance obtained from `cloud.database()`, not directly from the SDK root.
Cloud
import * as Cloud from 'wx-server-sdk'; // Use Cloud.init(), Cloud.database(), etc.
This pattern provides full access to all exported members of the SDK under the `Cloud` namespace, suitable for TypeScript environments or when a single named import is insufficient.

This quickstart demonstrates initializing the SDK, performing basic database operations (add and query), and invoking another Cloud Function within a WeChat Cloud Function. It highlights best practices for error handling and accessing user context.

import cloud from 'wx-server-sdk'; // Initialize the cloud environment cloud.init({ env: process.env.WX_CLOUD_ENV_ID ?? '', // Ensure environment ID is configured traceUser: true, // Enable user tracking for logging }); const db = cloud.database(); const _ = db.command; // Cloud Function entry point export async function main(event: any, context: any) { try { // Example: Add a new record to a 'todos' collection const addResult = await db.collection('todos').add({ data: { description: 'Learn wx-server-sdk', completed: false, createdDate: new Date(), _openid: event.userInfo.openId, // Automatically available in Cloud Function event }, }); console.log('Added todo:', addResult); // Example: Query records from 'todos' collection const queryResult = await db.collection('todos') .where({ _openid: event.userInfo.openId, completed: false, }) .orderBy('createdDate', 'desc') .limit(10) .get(); console.log('Queried todos:', queryResult.data); // Example: Call another Cloud Function (replace 'anotherFunction' with actual function name) const callFunctionResult = await cloud.callFunction({ name: 'anotherFunction', data: { message: 'Hello from main function' }, }); console.log('Called another function:', callFunctionResult.result); return { statusCode: 200, body: 'Operation successful', addResult, queryResult: queryResult.data, callFunctionResult: callFunctionResult.result }; } catch (e: any) { console.error('Operation failed:', e); return { statusCode: 500, body: `Operation failed: ${e.message}`, }; } }
Debug
Known issues
breakingVersion 3.0.1 introduced a breaking change regarding BigInt serialization. Native `JSON.stringify` will serialize the SDK's built-in `BigInt` (implemented via `bigint.js`) as a string, not a number, potentially impacting existing code expecting numeric `BigInt` values in JSON output.
fix
Review any code that serializes BigInt values from database queries or other SDK operations to JSON. Adjust parsing logic to handle BigInts as strings or use custom serialization/deserialization logic if numeric representation is strictly required. For example, convert BigInt to `Number()` if within safe integer limits before JSON.stringify.
affects: >=3.0.1
gotchaCloud Functions run in a Node.js environment and are granted unrestricted read/write access to Cloud Database and Cloud Storage by default. This powerful access model requires careful security consideration to prevent data breaches or unintended modifications.
fix
Implement robust access control policies (ACLs) at the database collection level, use database security rules, and strictly validate all incoming data and user permissions within your Cloud Functions. Never trust client-side input directly.
affects: >=0.1.0
gotchaThe `wx-server-sdk` must be installed within the specific Cloud Function's directory, not just at the project root level. Failing to do so will result in 'Cannot find module' errors at runtime.
fix
Navigate to your Cloud Function's directory (e.g., `cloudfunctions/myFunction`) and run `npm install --save wx-server-sdk@latest`. Ensure each function requiring the SDK has its own `node_modules` with the dependency.
affects: >=0.1.0
gotchaThe `cloud.init()` method must be called exactly once at the entry point of your Cloud Function before any other cloud operations are performed. Forgetting this will lead to errors when attempting to use database, storage, or other cloud APIs.
fix
Ensure `cloud.init()` is the first cloud-related call in your Cloud Function's `main` entry point, ideally configuring the `env` parameter with your Cloud Development environment ID (e.g., `cloud.init({ env: 'your-env-id' })`).
affects: >=0.1.0
Errors
Common errors & fixes
Error: Cannot find module 'wx-server-sdk'
The `wx-server-sdk` package has not been installed in the specific Cloud Function's `node_modules` directory.
fix
Navigate into the `cloudfunctions/<your-function-name>` directory and run `npm install --save wx-server-sdk`.
TypeError: Cannot read properties of undefined (reading 'database')
The `cloud.init()` method was not called or failed, meaning the `cloud` object was not properly initialized before attempting to access its properties like `database`.
fix
Add `cloud.init({ env: 'your-environment-id' });` at the beginning of your Cloud Function's `main` function.
Error: 'collection' must be a string
The `collection()` method of the database was called without providing a valid string for the collection name.
fix
Ensure `db.collection('your_collection_name')` passes a non-empty string as the collection identifier.
SyntaxError: 'await' is only valid in async functions and the top level bodies of modules
Using `await` inside a Cloud Function without declaring the function `async`.
fix
Declare your Cloud Function's entry point `export async function main(event: any, context: any) { ... }`.
Upgrade
Version history
3.0.4latest on npm
Audit
Dependencies
@cloudbase/node-sdkrequiredInternal dependency for interacting with Tencent Cloud Base services, which underpins WeChat Cloud Development.
Agent activity
42 hits · last 30 days
node
34
OpenAI (training)
1
Resources
wx-server-sdk — npm install wx-server-sdk · libregistry