Initialize

@cloudbase/js-sdk allows you to use JavaScript to access CloudBase services and resources on the web, such as PC Web pages and WeChat public platform H5.

Note

The @cloudbase/js-sdk latest version is now v3, which supports browser, Node.js, React Native, and other general JavaScript runtime environments. Please refer to the v3 documentation.

Finish MCP setup first, then select a prompt to start your AI-native development journey

Prerequisites

Configure the Secure Domain Name

Before using @cloudbase/js-sdk, you need to configure the secure domain name, otherwise you will encounter a CORS error. For details, refer to: Secure Source

Configuration Steps:

1. Go to CloudBase Platform / Environment Configuration / Security Configuration
2. Add a website domain name (for example: www.example.com)
3. Takes effect about 10 minutes after configuration

💡 Note:

• Only domain names in the secure domain name list can use the CloudBase JS SDK to protect your data security
• For local development, add localhost or 127.0.0.1 and the port to the secure domain name list
• If you encounter a CORS error, please check whether the secure domain name configuration is correct

Install and Initialize

Install the SDK

Package Manager

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

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

Initialize SDK

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id", // Replace with your environment ID
  region: "ap-shanghai", // Defaults to Shanghai region if not specified
});

Full CDN Import

Note

Please specify a 2.x.x version number (the current latest points to v3). You can pin it to a fixed version.

<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.full.js"></script>
<script>
  const app = cloudbase.init({
    env: "your-env-id", // Replace with your environment ID
    region: "ap-shanghai", // Defaults to Shanghai region if not specified
  });
</script>

On-demand CDN Import

Note

Please specify a 2.x.x version number (the current latest points to v3). You can pin it to a fixed version.

<!-- Core -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.js"></script>
<!-- Auth module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.auth.js"></script>
<!-- Database module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.database.js"></script>
<!-- Data Model module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.model.js"></script>
<!-- Cloud Function module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.functions.js"></script>
<!-- Cloud Storage module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.storage.js"></script>
<!-- Real-time push module — must be imported after the database module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.realtime.js"></script>
<!-- AI module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/2.27.1/cloudbase.ai.js"></script>
<script>
  // Register feature modules
  registerAuth(cloudbase);
  registerDatabase(cloudbase);
  registerModel(cloudbase);
  registerFunctions(cloudbase);
  registerStorage(cloudbase);
  registerRealtime(cloudbase);
  registerAi(cloudbase);

  const app = cloudbase.init({
    env: "your-env-id", // Replace with your environment ID
    region: "ap-shanghai", // Defaults to Shanghai region if not specified
  });
</script>

💡 Note: Feature modules must be imported after the core, and the auth module must be included.

The latest version number can be viewed at NPM.

Initialization Parameters

Field	Type	Required	Default	Description
env	string	Yes	-	CloudBase environment ID
region	string	No	ap-shanghai	Region: ap-shanghai (default), ap-guangzhou, ap-singapore
lang	string	No	zh-CN	Specified language: zh-CN (default), en-US
accessKey	string	No	-	Anonymous user authentication parameter, can be exposed in the browser, used to access public resources

⚠️ Note: The region of the currently used environment must match the specified region.

Login Authentication

js-sdk uses end-user permissions. You must log in before calling CloudBase capabilities.

Publishable Key

Note

To use this feature, upgrade @cloudbase/js-sdk to version 2.21.0 or later.

Publishable Key can be exposed in the browser for requesting publicly accessible resources. Publishable Key is actually an anonymous user, which can effectively reduce MAU. For details, refer to the documentation.

Get Publishable Key

Go to CloudBase Platform / API Key Settings to generate a Publishable Key.

Use Publishable Key

const app = cloudbase.init({
  env: "your-env-id", // Replace with your environment ID
  accessKey: "Publishable Key", // Fill in the generated Publishable Key
});

⚠️ Note: Publishable Key can only be generated once, is permanently valid and cannot be deleted. Keep it safe.

Anonymous Login

For details, see: Anonymous Login

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

const { data, error } = await app.auth.signInAnonymously();

Account Login

For details, see: Account Login

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

const { data, error } = await app.auth.signInWithPassword({
  username: "your username",
  password: "your password",
});

Initialization Examples

Singapore Region

import cloudbase from "@cloudbase/js-sdk";

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

Use English Prompt

import cloudbase from "@cloudbase/js-sdk";

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