Skip to main content

Initialization

@cloudbase/js-sdk enables you to access Cloudbase services and resources using JavaScript on the Web (e.g., PC web pages, WeChat Official Account H5, etc.).

Note

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

Installation​

Option 1: Import via package manager​

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

Option 2: Include via CDN​

There are two methods to include via CDN:

Importing the Full SDK​

<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.full.js"></script>
<script>
  const app = cloudbase.init({
    env: "your-env-id",
    clientId: "xxxx", // Application ID
  });
</script>

Importing Feature Modules On Demand​

<!-- Kernel -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.js"></script>
<!-- Login module -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.auth.js"></script>
<!-- Cloud function module -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.functions.js"></script>
<!-- Cloud storage module -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.storage.js"></script>
<!-- Cloud Database module -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.database.js"></script>
<!-- Real-time push module, which must be imported after the Cloud Database module is imported. -->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.realtime.js"></script>
<!-- Ad reporting module-->
<script src="//static.cloudbase.net/cloudbase-js-sdk/${version}/cloudbase.analytics.js"></script>
<script>
  const app = cloudbase.init({
    env: "your-env-id",
    clientId: "xxxx", // Application ID
  });
</script>
Note

Feature modules must be imported after the kernel, and the login module must be imported.

The latest version number can be found at NPM.

Usage​

After installing @cloudbase/js-sdk via a package manager, there are two ways to import it in the project source code:

Method 1: Import the full SDK​

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

const app = cloudbase.init({
  env: "your-env-id",
  clientId: "xxxx", // Application ID
});

Method 2: Import feature modules on demand​

// Kernel.
import cloudbase from "@cloudbase/js-sdk/app";
// Login module.
import "@cloudbase/js-sdk/auth";
// Cloud function module.
import "@cloudbase/js-sdk/functions";
// Cloud storage module.
import "@cloudbase/js-sdk/storage";
// Database module.
import "@cloudbase/js-sdk/database";
// Real-time push module, which should be imported after the database module is imported.
import "@cloudbase/js-sdk/realtime";
// Ad reporting module.
import "@cloudbase/js-sdk/analytics";

const app = cloudbase.init({
  env: "your-env-id",
});
Note

Feature modules must be imported after the kernel, and the login module must be imported.

Please note: The feature module import method demonstrated in the above code is only valid in browser environments. For JavaScript runtimes in non-browser environments, you must manually register modules after importing feature modules, as shown in the following code:

// Kernel.
import cloudbase from "@cloudbase/js-sdk/app";
// Login module.
import { registerAuth } from "@cloudbase/js-sdk/auth";
// Cloud function module.
import { registerFunctions } from "@cloudbase/js-sdk/functions";
// Cloud storage module.
import { registerStorage } from "@cloudbase/js-sdk/storage";
// Database module.
import { registerDatabase } from "@cloudbase/js-sdk/database";
// Real-time push module, which should be imported after the database module is imported.
import { registerRealtime } from "@cloudbase/js-sdk/realtime";
// Data model module.
import { registerModel } from "@cloudbase/js-sdk/model";
// AI module.
import { registerAi } from "@cloudbase/js-sdk/ai";

// Feature module registration
registerAuth(cloudbase);
registerFunctions(cloudbase);
registerStorage(cloudbase);
registerDatabase(cloudbase);
registerRealtime(cloudbase);
registerModel(cloudbase);
registerAi(cloudbase);

const app = cloudbase.init({
  env: "your-env-id",
  clientId: "xxxx", // Application ID
});

Region​

During initialization, you can specify the region, which defaults to Shanghai (ap-shanghai). For the list of currently supported regions, see.

Example: There are environments in the Shanghai region: env-shanghai, and in the Guangzhou region: env-guangzhou.

The correct initialization method is:

// If region is not specified, it defaults to Shanghai region, ensuring consistency.
const app = cloudbase.init({
  env: "env-shanghai",
  clientId: "xxxx", // Application ID
});
// The env region is consistent with the region.
const app = cloudbase.init({
  env: "env-shanghai",
  clientId: "xxxx", // Application ID
  region: "ap-shanghai",
});
// The env region is consistent with the region.
const app = cloudbase.init({
  env: "env-guangzhou",
  clientId: "xxxx", // Application ID
  region: "ap-guangzhou",
});
Note

The region of the current environment must match the specified region!

More Friendly Error Logs​

@cloudbase/js-sdk prints errors encountered when calling APIs to the console in a more user-friendly manner during development, as shown in the figure below:

The error shown in the figure indicates that the current login type is restricted by the function's security rules, resulting in no permission to invoke the function. The error message consists of two parts:

  1. The black text in the upper section contains the error information returned by the backend API and some solution suggestions based on this error;
  2. The red text in the lower section is the optimized error stack. Since the original error stack was too deeply nested, making debugging extremely difficult, the first entry in the error stack printed here points directly to the SDK source code, while the second entry points to the business source code that called the erroneous API.

Optimized error messages are only used in development environments, determined based on process.env.NODE_ENV. Additionally, locating the SDK source code requires SourceMap.

The above two points rely on specific features of build tools and are currently only supported in Webpack and Rollup.

Webpack​

In Webpack 4+, you can set the mode option to development as follows:

module.exports = {
  mode: "development",
};

For older versions of Webpack, you need to use DefinePlugin:

const webpack = require("webpack");

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      "process.env.NODE_ENV": JSON.stringify("development"),
    }),
    // ...other plugins
  ],
  // ...other configurations
};

Then add source map preprocessing to the JavaScript compilation options. Here you need to use source-map-loader:

module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        enforce: "pre",
        use: ["source-map-loader"],
      },
      // ...other rules
    ],
  },
  // ...other configurations
};

After completing the configuration, start webpack-dev-server.

Rollup​

Rollup requires two plugins:

The configuration is as follows:

import sourcemaps from "rollup-plugin-sourcemaps";
import replace from "rollup-plugin-replace";
export default {
  plugins: [
    sourcemaps(),
    replace({
      "process.env.NODE_ENV": JSON.stringify("development"),
    }),
    // ...other plugins
  ],
  // ...other configurations
};

After completing the configuration, use rollup-plugin-serve to start the dev server.