Configuration File
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}}
.
Namespace | Variable Name | Description |
---|---|---|
tcb | envId | Environment Id specified in the configuration file or via command-line parameters |
util | uid | 24-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.
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
.
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"
}
}
]
}