Config File

The cloudbaserc.json file serves as the core configuration file for TCB projects, enabling unified management of deployment configurations for both CLI and VS Code plugins. Through this configuration file, you can simplify command-line operations and achieve multi-environment deployment with dynamic configuration management.

The configuration file is mainly used for the following scenarios:

• SCF deployment: define function name, runtime, timeout, environment variables, and other configurations.
• Multi-environment Management: supports different environments such as development, testing, and production through environment variables and dynamic variables
• Cross-tool Sharing: Share unified configuration between CLI and VS Code plugins to avoid duplicate settings.

Quick Start

When using tcb init to initialize a project, the cloudbaserc.json configuration file is automatically generated. You can also specify a custom configuration file path via the --config-file parameter.

# Initializing the project and automatically generating cloudbaserc.json
tcb init

# Using Custom Configuration File
tcb deploy --config-file custom-config.json

JSON Schema

The configuration file supports JSON Schema validation for code completion and validation hints in your editor.

Schema URL: https://static.cloudbase.net/cli/cloudbaserc.schema.json

VS Code Configuration Example (add to .vscode/settings.json):

{
  "json.schemas": [
    {
      "fileMatch": ["cloudbaserc.json"],
      "url": "https://static.cloudbase.net/cli/cloudbaserc.schema.json"
    }
  ]
}

Dynamic Variables

Starting from CLI version 0.9.1, the configuration file supports the version 2.0 format, introducing the dynamic variables feature. By declaring "version": "2.0" in cloudbaserc.json, you can use the {{}} syntax to dynamically obtain configuration values from environment variables or other data sources.

💡 Note: The version 2.0 configuration file only supports JSON format.

Basic Example:

{
  "version": "2.0",
  "envId": "{{env.ENV_ID}}",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "{{env.FUNCTION_NAME}}",
      "timeout": 5
    }
  ]
}

Data Source

CloudBase provides multiple namespaces to access different data sources. Reference variables in the format namespace.variableName, such as {{tcb.envId}}.

Supported Data Sources:

Namespace	Variable Name	Description	Example
tcb	envId	Environment ID specified in the configuration file or command-line parameters	{{tcb.envId}}
util	uid	A 24-bit random string that can be used to generate unique identifiers	{{util.uid}}
env	*	All environment variables loaded from the .env file	{{env.API_KEY}}

Environment Variables

CloudBase provides enhanced support for environment variables to help you use different configurations across development stages (development, testing, production). Manage environment variables via .env files, with automatic loading of corresponding configurations based on the runtime mode.

File Loading Rules

CloudBase supports the following .env file types:

.env                # Base configurations shared across all environments
.env.local          # Local private configurations (recommended to be added to .gitignore)
.env.[mode]         # Configuration for specific modes (e.g., .env.production, .env.development)

Loading Order:

1. Default Loading: .env and .env.local are always loaded.
2. Mode-based Loading: When using the --mode <mode> parameter, additionally load the .env.[mode] file.
3. Override Rules: .env.[mode] > .env.local > .env (Files loaded later override variables with the same name).

Example:

# Specify test mode during deployment
tcb framework deploy --mode test

When executing the above command, it will load the three files .env, .env.local, and .env.test in sequence and merge the environment variables.

Best Practices

Store sensitive information such as API keys and database passwords in the .env.local file and add it to .gitignore to prevent leakage of confidential data.

Usage Example

.env.local file:

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=s1mpl3

cloudbaserc.json configuration:

{
  "version": "2.0",
  "envId": "xxx",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "database",
      "envVariables": {
        "DB_HOST": "{{env.DB_HOST}}",
        "DB_USER": "{{env.DB_USER}}",
        "DB_PASSWORD": "{{env.DB_PASSWORD}}"
      }
    }
  ]
}

Extended Syntax

In addition to basic key-value pairs, CloudBase supports the use of compound key-value pair syntax in .env files, constructing nested objects and array structures using the . symbol.

Basic Key-Value Pairs

FOO=bar
VUE_APP_SECRET=secret

Compound Key-Value Pairs

Use the . symbol to add attributes to the same key, supporting nested objects and arrays:

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

Compilation Result:

The above configuration will be parsed into the following JSON object:

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

Referencing in Configuration Files

You can directly reference object properties in cloudbaserc.json:

{
  "version": "2.0",
  "envId": "xxx",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "app",
      "envVariables": {
        "BOOK_NAME": "{{env.Book.Name}}",
        "FIRST_AUTHOR": "{{env.Book.Authors.0}}"
      }
    }
  ]
}

Precautions

When referencing an entire object (e.g. {{env.Book}}), it will be automatically converted to a JSON string during compilation:

{{env.Book}} → {"Name":"Test","Publish":"2020","Authors":["Jack","Mike"]}

Configuration Fields

The following are the main configuration fields supported by cloudbaserc.json and their descriptions.

version

• Type: String
• Description: Configuration file version number. Currently supports "2.0". Defaults to version "1.0" when not specified.
• Example: "version": "2.0"

envId

• Type: String
• Description: TCB environment ID, the unique identifier of the environment
• Example: "envId": "dev-abc123"

region

• Type: String
• Description: The region where the environment is located. The Shanghai region can be omitted, while other regions (e.g., Guangzhou, Beijing) must be specified.
• Example: "region": "ap-guangzhou"

functionRoot

• Type: String
• Description: SCF code directory, relative to the project root directory
• Example: "functionRoot": "./functions" or "functionRoot": "functions"

functions

• Type: Array<CloudFunction>
• Description: Function configuration item array, each element describes an SCF deployment configuration.
• Detailed Description: View the Function Configuration Items Documentation

Example:

{
  "functions": [
    {
      "name": "app",
      "timeout": 10,
      "runtime": "Nodejs16.13",
      "envVariables": {
        "API_KEY": "{{env.API_KEY}}"
      }
    }
  ]
}

app

• Type: Object
• Description: Cloud app deployment configuration for tcb app deploy / tcb deploy commands. When configured, you can skip specifying framework, build commands, and other parameters each time.
• Detailed Description: See App Deployment Documentation

Field	Type	Required	Default	Description
serviceName	String	No	package.json name or directory name	Cloud app service name
root	String	No	Current directory	App project root directory (relative to cloudbaserc.json), for specifying sub-project paths in monorepo scenarios
framework	String	No	Auto-detect	Frontend framework type, supported values: react, vue, vite, next, nuxt, angular, static
installCommand	String	No	npm install	Install dependencies command, empty string to skip the install step
buildCommand	String	No	Auto-detect based on framework	Build command, empty string to skip the build step (for pure static projects)
outputDir	String	No	./dist (./ when no build command)	Build output directory
deployPath	String	No	/${serviceName}	Deployment path (static hosting mount path), must start with /
envVariables	Object	No	—	Environment variables (non-sensitive), key-value pairs, injected during cloud build
ignore	String/Array	No	—	Glob patterns for files/directories to ignore during packaging and upload, node_modules and .git are excluded by default

General Priority Rule: CLI parameters > cloudbaserc.json configuration > Auto-detection > Interactive input

⚠️ Note: Some parameters have special rules (e.g., envVariables has no CLI parameter, buildCommand has framework defaults), see App Deployment Documentation for detailed priority for each parameter.

Example:

{
  "version": "2.0",
  "envId": "{{env.TCB_ENV_ID}}",
  "app": {
    "serviceName": "my-frontend",
    "root": "./packages/web",
    "framework": "react",
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "outputDir": "build",
    "deployPath": "/my-app",
    "envVariables": {
      "API_URL": "https://api.example.com",
      "NODE_ENV": "production"
    }
  }
}

Complete Configuration Example

Here is a complete example containing common configurations:

{
  "version": "2.0",
  "envId": "{{env.TCB_ENV_ID}}",
  "region": "ap-shanghai",
  "functionRoot": "./functions",
  "functions": [
    {
      "name": "api",
      "timeout": 10,
      "runtime": "Nodejs16.13",
      "memorySize": 256,
      "envVariables": {
        "DB_HOST": "{{env.DB_HOST}}",
        "API_KEY": "{{env.API_KEY}}"
      },
      "installDependency": true
    },
    {
      "name": "task",
      "timeout": 30,
      "runtime": "Nodejs16.13",
      "triggers": [
        {
          "name": "dailyTask",
          "type": "timer",
          "config": "0 0 2 * * * *"
        }
      ]
    }
  ]
}

Config File Operations

Pull Configuration

The tcb config pull command is used to pull the configuration of deployed resources from the cloud and write it to the local cloudbaserc.json file, helping you quickly synchronize cloud state or initialize local configuration files.

Command Format

tcb config pull <module> [name...] [options]

Where <module> indicates the resource module to be pulled. Currently supported:

Module	Description
fn	Pull SCF configuration

Command Behavior

When executing tcb config pull fn, the CLI performs the following operations:

1. Query cloud configuration: Based on the specified function name, obtain the complete configuration of the deployed SCF from the cloud (timeout, memory, runtime, environment variables, triggers, etc.).
2. Merge to Local:
   • If the local cloudbaserc.json does not exist, it will be automatically created and the pulled configuration will be written to it.
   • If the file already exists, for functions with the same name, the CLI will ask whether to overwrite; for functions with different names, they will be appended to the functions array.
3. When the SCF does not exist: The CLI will ask whether to infer the configuration based on the local project directory and write it.

Command Parameters

Parameter	Description	Required
[name...]	SCF name(s). Specify one or more names.	No
--all	Pull configurations of all functions in the configuration file	No
-e, --env-id <envId>	Environment ID	No
-o, --output <output>	Output file path, defaults to cloudbaserc.json in the current directory	No
--stdout	Output the result to the console instead of writing to a file	No
--code-secret <codeSecret>	CodeSecret for code encryption functions	No
--dir <dir>	Specifies the directory for inferring the configuration (when the SCF does not exist)	No
--yes	Skip interactive confirmation and automatically overwrite existing configurations	No

Usage Example

# Pulling Configuration for a Single Function
tcb config pull fn myFunc

# Pulling Configuration for Multiple Functions
tcb config pull fn func1 func2 func3

# Pulling Configurations for All Functions in the Configuration File
tcb config pull fn --all

# Output the result to the console (without writing to a file)
tcb config pull fn func1 --stdout

# Specify output file path
tcb config pull fn myFunc -o ./config/cloudbaserc.json

# Automatic confirmation, skip interactive prompts
tcb config pull fn --all --yes

Use Cases

• Initialize local configuration: In a new environment or on a new machine, quickly synchronize configuration from the cloud via the pull command, without manual input.
• Configuration Review: After pulling, use the tcb config diff fn command to compare the differences between local and cloud configurations.
• Team Collaboration: Commit the pulled results to the version control repository to ensure team members use consistent function configurations. :::

For more details on SCF configuration items, see Configuration File - SCF