Initialization

@cloudbase/js-sdk enables you to access Cloudbase services and resources using JavaScript in Web environments, 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, see v1 documentation.

Install and Initialize

Install the SDK

Package Manager

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

# yarn
yarn add @cloudbase/js-sdk

Initialize the 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

latest means to use the latest version, but you can specify a fixed version instead

<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 to use the latest version, but you can specify a fixed version instead

<!-- Kernel -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.js"></script>
<!-- Login 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>
<!-- Model Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.model.js"></script>
<!-- Cloud Function Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.functions.js"></script>
<!-- Cloud Storage Module -->
<script src="https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.storage.js"></script>
<!-- Real-time Push Module, must be imported after the Database Module -->
<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 feature module
  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 kernel, and the login module must be imported.

The latest version number version can be found at 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	-	Authentication parameter for anonymous users, which can be exposed in browsers and is used to request publicly accessible resources

⚠️ Note: The region of the environment currently in use must match the currently specified region information!

Login Authentication

The js-sdk uses client-side user permissions and requires login to invoke TCB 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 browsers and is used to request publicly accessible resources. Publishable Key is essentially an anonymous user, which can effectively reduce MAU. For detailed information, see Documentation.

Obtain Publishable Key

You can go to TCB Platform/API Key Configuration to generate 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 long-term valid, cannot be deleted. Please keep it safe.

Anonymous Login

For details, see 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, see 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 Sample

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