Initialization

@cloudbase/js-sdk allows you to access CloudBase services and resources using JavaScript on the Web (such as PC Web pages, WeChat Official Account H5, etc.).

Note

The current @cloudbase/js-sdk@latest version has been upgraded to v2. If you need to use v1, please refer to the v1 documentation.

Select a prompt to start your AI-native development journey

Prerequisites

Configure Security Domains

Before using @cloudbase/js-sdk, you need to configure security domains first, otherwise you will encounter CORS errors. For details, please refer to: Security Sources

Configuration Steps:

1. Go to CloudBase Console/Environment Configuration/Security Settings
2. Add your website domain (e.g., www.example.com)
3. Configuration takes effect in approximately 10 minutes

💡 Note:

• Only domains in the security domain list can use CloudBase JS SDK, this is to protect your data security
• For local development, please add localhost or 127.0.0.1 to the security domain list
• If you encounter CORS errors, please check if the security domain configuration is correct

Install and Initialize

Install SDK

Package Manager

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

# yarn
yarn add @cloudbase/js-sdk

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
});

CDN Full Import

Note

latest means using the latest version, you can set it to a fixed version

<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/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>

CDN On-Demand Import

Note

latest means using the latest version, you can set it to a fixed version

<!-- Core -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.js"></script>
<!-- Auth Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.auth.js"></script>
<!-- Database Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.database.js"></script>
<!-- Data Model Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.model.js"></script>
<!-- Functions Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.functions.js"></script>
<!-- Storage Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.storage.js"></script>
<!-- Realtime Module, database module must be imported first -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.realtime.js"></script>
<!-- AI Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.ai.js"></script>
<script>
  // Register functional 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: Functional modules must be imported after the core, and the auth module must be imported

The latest version number can be found on NPM.

Initialization Parameters

Field	Type	Required	Default Value	Description
env	string	Yes	-	TCB environment ID
region	string	No	ap-shanghai	Region: ap-shanghai (default), ap-guangzhou, ap-singapore
lang	string	No	zh-CN	Language: zh-CN (default), en-US
accessKey	string	No	-	Anonymous user authentication parameter, can be exposed in browser for accessing public resources

⚠️ Note: The region of the environment you are using must match the specified region information!

Login Authentication

js-sdk uses client-side user permissions and requires login before calling CloudBase capabilities.

Publishable Key

Note

To use this feature, please 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 essentially an anonymous user, which can effectively reduce MAU. For detailed introduction, please refer to the documentation.

Get Publishable Key

Go to CloudBase Console/API Key Configuration 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 and is permanently valid and cannot be deleted, please keep it safe

Anonymous Login

For details, please refer to: Anonymous Login

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

const auth = app.auth();
await auth.signInAnonymously();

Account Login

For details, please refer to: Account Login

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

const auth = app.auth();

await auth.signIn({
  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",
});

Using English Prompts

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

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