Skip to main content

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:

NamespaceVariable NameDescriptionExample
tcbenvIdEnvironment ID specified in the configuration file or command-line parameters{{tcb.envId}}
utiluidA 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​

Example:

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

integrations​

  • Type: Array<Integration>
  • Description: Integration configuration item array, each element describes the configuration of an integration
  • Detailed Description: See Integration Center Overview

Example:

{
  "integrations": [
    {
      "name": "myPayment",
      "authTypeCode": "weixinpaydc",
      "envVariables": {
        "MCH_ID": "1234567890",
        "API_KEY": "your-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
FieldTypeRequiredDefaultDescription
serviceNameStringNopackage.json name or directory nameCloud app service name
rootStringNoCurrent directoryApp project root directory (relative to cloudbaserc.json), for specifying sub-project paths in monorepo scenarios
frameworkStringNoAuto-detectFrontend framework type, supported values: react, vue, vite, next, nuxt, angular, static
installCommandStringNonpm installInstall dependencies command, empty string to skip the install step
buildCommandStringNoAuto-detect based on frameworkBuild command, empty string to skip the build step (for pure static projects)
outputDirStringNo./dist (./ when no build command)Build output directory
deployPathStringNo/${serviceName}Deployment path (static hosting mount path), must start with /
envVariablesObjectNo—Environment variables (non-sensitive), key-value pairs, injected during cloud build
ignoreString/ArrayNo—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 * * * *"
        }
      ]
    }
  ],
  "integrations": [
    {
      "name": "myPayment",
      "authTypeCode": "weixinpaydc",
      "envVariables": {
        "MCH_ID": "1234567890",
        "API_KEY": "your-api-key"
      }
    }
  ]
}

Config File Operations​

Initialize Configuration​

The tcb config init command is used to create configuration files from templates, helping you quickly initialize configuration templates for SCF or integrations.

Command Format​

tcb config init <module> [options]

Where <module> indicates the module to initialize. Currently supported:

ModuleDescription
fnInitialize SCF configuration template
integrationInitialize integration configuration template

Command Parameters​

ParameterDescriptionRequired
--name <name>Configuration item name (SCF name or integration name)No (interactive input)
--type <type>Integration type (integration module only), e.g., weixinpaydcNo (interactive selection)
-o, --output <output>Output file path, defaults to cloudbaserc.json in the current directoryNo

Usage Example​

Initialize SCF configuration:

# Interactively create SCF configuration
tcb config init fn

# Create configuration with specified function name
tcb config init fn --name myFunction

# Specify output file
tcb config init fn --name myFunction -o ./config/cloudbaserc.json

Initialize integration configuration:

# Interactively select integration type and create configuration
tcb config init integration

# Specify integration type and name
tcb config init integration --type weixinpaydc --name myPayment

# Specify output file
tcb config init integration --type weixinpaydc --name myPayment -o ./config/cloudbaserc.json

Initialization Behavior​

SCF Configuration:

  • Generates a function configuration template containing basic fields (name, timeout, runtime, envVariables, etc.)
  • The envVariables field will be automatically populated with placeholders based on the integration type, indicating required/optional fields

Integration Configuration:

  • Pulls the template field definitions for the integration type from the cloud
  • Automatically identifies required and optional fields
  • Uses placeholder ****** for sensitive fields (e.g., keys, certificates), prompting the user to fill in real values
  • Generates a complete configuration containing authTypeCode, name, and envVariables
Use Cases
  • Quick Start: Quickly create standardized configuration files through templates
  • Configuration Learning: Understand which fields need to be configured for SCF or integrations
  • Team Collaboration: Generate standardized configuration templates, team members only need to fill in specific values

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:

ModuleDescription
fnPull SCF configuration
integrationPull integration configuration

Command Behavior​

Pull SCF Configuration (tcb config pull fn):

  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.

Pull Integration Configuration (tcb config pull integration):

  1. Query cloud configuration: Based on the specified integration name, obtain the complete configuration of the created integration from the cloud (authTypeCode, envVariables, etc.).
  2. Sensitive Field Desensitization: For password-type fields (e.g., API keys, certificates), the cloud returns ****** as placeholders, requiring the user to manually fill in real values.
  3. 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 integrations with the same name, the CLI will ask whether to overwrite; for integrations with different names, they will be appended to the integrations array.
  4. When the integration does not exist: Returns an error message, suggesting the user to use tcb config init integration to create a configuration template.

Command Parameters​

ParameterDescriptionRequired
[name...]SCF/integration name(s). Specify one or more names.No
--allPull configurations of all functions/integrations in the configuration fileNo
-e, --env-id <envId>Environment IDNo
-o, --output <output>Output file path, defaults to cloudbaserc.json in the current directoryNo
--stdoutOutput the result to the console instead of writing to a fileNo
--code-secret <codeSecret>CodeSecret for code encryption functionsNo
--dir <dir>Specifies the directory for inferring the configuration (when the SCF does not exist)No
--yesSkip interactive confirmation and automatically overwrite existing configurationsNo

Usage Example​

Pull SCF configuration:

# 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

Pull integration configuration:

# Pull configuration for a single integration
tcb config pull integration myPayment

# Pull configuration for multiple integrations
tcb config pull integration payment1 payment2

# Pull configurations for all integrations in the configuration file
tcb config pull integration --all

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

# Specify output file path
tcb config pull integration myPayment -o ./config/cloudbaserc.json

# Automatic confirmation, skip interactive prompts
tcb config pull integration --all --yes
Use Cases

SCF Configuration:

  • 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.

Integration Configuration:

  • Quick Synchronization: Pull created integration configurations from the cloud to avoid manually filling in complex fields like authTypeCode.
  • Configuration Backup: Export cloud integration configurations to local for version management and backup.
  • Team Collaboration: Team members can quickly synchronize integration configurations, only need to fill in real values for sensitive fields.

Push Configuration​

The tcb config update command is used to push configurations from cloudbaserc.json to the cloud, synchronizing local configurations with cloud resources.

Command Format​

tcb config update <module> [name] [options]

Where <module> indicates the module to push. Currently supported:

ModuleDescription
fnPush SCF configuration
integrationPush integration configuration

Command Parameters​

ParameterDescriptionRequired
[name]Resource name (SCF name or integration name)No (choose one with --all)
--allPush configurations of all resources in the configuration fileNo
-e, --env-id <envId>Environment IDNo
--timeout <timeout>[fn] Timeout (seconds)No
--memory <memory>[fn] Memory size (MB)No
--runtime <runtime>[fn] RuntimeNo
--handler <handler>[fn] Entry functionNo
--vpc <vpcId/subnetId>[fn] VPC configuration (format: vpcId/subnetId)No
--yesSkip interactive confirmationNo

Usage Example​

Push SCF configuration:

# Push configuration for a single function
tcb config update fn hello

# Push single function configuration and override timeout parameter
tcb config update fn hello --timeout 30

# Batch push configurations of all functions in the configuration file
tcb config update fn --all

# Push function configuration and specify VPC
tcb config update fn myFunc --vpc vpc-xxx/subnet-xxx

Push integration configuration:

# Push configuration for a single integration
tcb config update integration myPayment

# Batch push configurations of all integrations in the configuration file
tcb config update integration --all

# Automatic confirmation, skip interactive prompts
tcb config update integration --all --yes

Push Behavior​

Push SCF Configuration (tcb config update fn):

  1. Read Local Configuration: Read function configurations from the functions field in cloudbaserc.json.
  2. Parameter Priority: CLI parameters (e.g., --timeout) > values in configuration file.
  3. Environment Variable Handling:
    • If the configuration contains environment variables, the CLI will ask for the update method:
      • Overwrite Update: Completely replace cloud environment variables with local environment variables
      • Merge Update: Merge local and cloud environment variables, local overrides variables with the same name
  4. Batch Push: When using the --all parameter, it will push configurations of all functions in the configuration file.

Push Integration Configuration (tcb config update integration):

  1. Read Local Configuration: Read integration configurations from the integrations field in cloudbaserc.json.
  2. Match Cloud Instance: Match the existing integration instance in the cloud based on the name field in the configuration.
  3. Smart Merge:
    • For optional fields (e.g., demoCodeFunctionName), if the local configuration is explicitly set to an empty string '', the corresponding field in the cloud will be cleared.
    • For required fields (e.g., authTypeCode), if not specified locally, the original value in the cloud will be retained.
  4. Batch Push: When using the --all parameter, it will push configurations of all integrations in the configuration file.
Use Cases

SCF Configuration:

  • Configuration Synchronization: Push locally modified function configurations to the cloud to keep them consistent.
  • Batch Update: Update configurations of multiple functions at once via the --all parameter.
  • Parameter Override: Temporarily modify a parameter (e.g., --timeout) without modifying the configuration file.

Integration Configuration:

  • Credential Rotation: Update integration credential information (e.g., API keys, certificates, etc.).
  • Configuration Management: Manage configurations of multiple integrations through configuration files.
  • Team Collaboration: Team members synchronize integration configurations through configuration files, only need to fill in sensitive fields.

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

For more details on integration configurations, see Integration Center Overview.