Skip to main content

Configuration File

danger

CLI 0.x will be deprecated and its documentation will no longer be updated. Please refer to the v1 documentation.

To address complex usage scenarios, we provide a project-level cloudbaserc.json configuration file that can be shared and used across both CLI and VS Code extensions.

The configuration file contains settings for using the CloudBase CLI or VS Code extension, simplifying the operation of both the CLI and VS Code.

By default, when initializing a project with cloudbase init, a cloudbaserc.json file is generated as the configuration file. You can also use --config-file to specify another file as the configuration file, which must meet the format requirements.

Dynamic Variables

CLI version 0.9.1+ introduces the new version 2.0 configuration file, which supports dynamic variables. By declaring "version": "2.0" in cloudbaserc.json, you can enable the new features. The new configuration file only supports JSON format.

The dynamic variables feature allows the use of dynamic variables in the cloudbaserc.json configuration file to retrieve dynamic data from environment variables or other data sources. Values enclosed in {{}} are defined as dynamic variables, which can reference values from data sources, as shown below:

{
"version": "2.0",
"envId": "envId",
"functionRoot": "./functions",
"functions": [
{
"name": "{{variable}}"
}
]
}

Data Source

CloudBase defines namespaces for multiple data sources to distinguish between different data sources. You can reference data via namespace.variableName, such as {{tcb.envId}}.

NamespaceVariable NameDescription
tcbenvIdEnvironment Id specified in the configuration file or via command-line parameters
utiluid24-bit random string
env*Environment variables loaded from .env files

Environment Variables

CloudBase provides special support for environment variables to address resource deployment issues using CLI & Framework across different development stages and configurations. CloudBase supports using .env type files as the primary data source, with different suffixes distinguishing various stages and scenarios. For example, .env.development represents development-stage configurations, while .env.production represents production-environment configurations.

CloudBase defines some constraints: By default, CLI & Framework automatically load data from .env and .env.local files. Developers can add configurations for specific environments by using the --mode <mode> option.

.env                # Loaded in all environments
.env.local # Loaded in all environments, can be added to .gitignore to be ignored
.env.[mode] # Loaded only in the specified mode

When loading data sources, .env and .env.local are loaded directly (if present). When --mode [mode] is specified, the .env.[mode] file is additionally loaded, and variables with the same name are merged and overridden in the following order: .env.[mode] > .env.local > .env. This means variables in .env.[mode] override those in .env.local and .env, and so on.

When using the tcb framework:deploy --mode test command, environment variables from three files—.env, .env.local, and .env.test—are automatically loaded and merged.

tip

We recommend placing private configurations such as secret keys in the .env.local file and adding .env.local to the .gitignore configuration.

As in the .env.local file containing the following variables

DB_HOST = localhost
DB_USER = root
DB_PASSWORD = s1mpl3

can be used in the configuration file

{
"version": "2.0",
"envId": "xxx",
"functionRoot": "./functions",
"functions": [
{
"name": "test",
"envVariables": {
"PASSWORD": "{{env.DB_PASSWORD}}"
}
}
]
}

Extension env syntax

Generally, you can directly use key-value pairs in the env file

FOO=bar
VUE_APP_SECRET=secret

However, when we need to use complex environment variables, simple key-value pairs become insufficient. Therefore, CloudBase extends the syntax supported by .env to include composite key-value pairs, allowing you to add attributes to the same key via ., for example:

Book.Name=Test
Book.Publish=2020
Book.Authors.0=Jack
Book.Authors.1=Mike

will be compiled into a Book object containing the following properties

{
"Name": "Test",
"Publish": "2020",
"Authors": ["Jack", "Mike"]
}

You can directly reference the relevant properties using {{env.Book.Name}} in cloudbaserc.json.

caution

When the value in .env is an object, it will be converted to a JSON string during compilation. For example, {{env.Book}} will be compiled to {"Name":"Test","Publish":"2020","Authors":["Jack","Mike"]}.

Field

The following are the fields supported by the CloudBase configuration file and their meanings.

version

Type: `String

The version field indicates the version of the current configuration file. Currently supported versions are "2.0". When the version field is absent, the configuration file defaults to version "1.0".

envId

Type: `String

envId represents the environment ID, which serves as the unique identifier for the environment.

functionRoot

Type: `String

The folder path where the cloud function code is stored, relative to the root directory.

functions

Type: Array<CloudFunction>

An array composed of function configuration items. For detailed information on function configuration items, please refer to the Function Configuration Items Documentation.

Simple Reference Configuration

Below is the basic information contained in a simple CLI configuration file:

{
"version": "2.0",
"envId": "dev-xxxx",
"functionRoot": "functions",
"functions": [
{
"name": "app",
"timeout": 5,
"envVariables": {
"key": "value"
}
}
]
}