Initialization

@cloudbase/js-sdk lets you use JavaScript to access CloudBase services and resources on the Web (such as PC webpages, WeChat public platform H5) and Node.js server.

Note

The @cloudbase/js-sdk v3 next version is now available. This version is fully compatible with v2 and aligns with the HTTP API.

If you need to use the Node.js server-side SDK, refer to the Node.js SDK documentation.

If you need to use v2, refer to the v2 documentation.

Installation and Initialization

Installing the SDK

Package Manager

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

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

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

3.x.x indicates the next version. You can pin it to a fixed version number.

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

CDN On-demand Import

Note

3.x.x indicates the next version. You can pin it to a fixed version number.

<!-- Core -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.js"></script>
<!-- Auth module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.auth.js"></script>
<!-- Database module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.database.js"></script>
<!-- Data model module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.model.js"></script>
<!-- Cloud Function module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.functions.js"></script>
<!-- Cloud Storage module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.storage.js"></script>
<!-- Realtime module — must be imported after the database module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.1/cloudbase.realtime.js"></script>
<!-- AI module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/3.0.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 module, and the auth module must always be included.

For the latest version number, visit NPM.

Initialization Parameters

Field	Type	Required	Default	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 key, safe to expose in the browser for public resource access

Note

The region of the current environment must match the region value specified during initialization.

Login Authentication

js-sdk uses client-side user permissions. You must log in before calling CloudBase features.

Publishable Key

Note

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

Publishable Key can be safely exposed in the browser for requesting publicly accessible resources. It represents an anonymous user and can effectively reduce MAU. For more details, refer to the documentation.

Get Publishable Key

Go to CloudBase Platform / 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

A Publishable Key can only be generated once. It 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 Prompts

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

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