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.

To generate or initialize the configuration file, see Initialize Configuration; to sync configurations between local and cloud, see Config Operations.

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"
    }
  ]
}

Configuration Fields

The following are the top-level configuration fields supported by cloudbaserc.json. Click a field name to jump to its details:

Field	Type	Description
`version`	`String`	Configuration file version
`envId`	`String`	TCB environment ID
`region`	`String`	Environment region
`functionRoot`	`String`	SCF code directory
`functions`	`Array<CloudFunction>`	SCF configuration array
`integrations`	`Array<Integration>`	Integration configuration array
`app`	`Object`	Cloud app deployment configuration
`gateway`	`Object`	Gateway routing configuration
`hosting`	`Array<Object>`	Static hosting app configuration
`database`	`Object`	Database migration configuration

version

Property	Value
Type	`String`
Default	`"1.0"` (when not specified)
Description	Configuration file version number. Currently supports `"2.0"` (dynamic variables) and `"2.1"` (declarative deployment, supporting `gateway`/`database` and other resources)
Example	`"version": "2.0"`

envId

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

region

Property	Value
Type	`String`
Description	The region where the environment is located. The Shanghai region can be omitted, while other regions (e.g., Singapore) must be specified
Example	`"region": "ap-singapore"`

functionRoot

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

functions

Function configuration item array, where each element is a CloudFunction object describing an SCF deployment configuration (basic, code, environment variables, triggers, image, etc.). See Config File - Cloud Function for the full field list.

Property	Value
Type	`Array<CloudFunction>`
Description	Each element describes an SCF deployment configuration (`name`, `runtime`, `timeout`, `envVariables`, etc.)

Common Fields Quick Reference

name (required): Identifier after deployment (unique within an envId); must match function:<name> in gateway.routes[].target
runtime: Runtime environment; supports Nodejs16.13 / Nodejs18.15 / Nodejs20.19 / Python3.10 / Golang1.21 / PHP8.2 / Java17, etc.
timeout: Timeout in seconds, 1-900, default 5
handler: Handler entry, format filename.functionname (e.g. index.main), default index.main
memorySize: Memory in MB, 64-3072, default 256
envVariables: Key-value env vars, supports {{env.NAME}} for external refs; secrets should use KMS/SCF key management instead of hard-coding
functionRoot (top-level): Root directory for all functions; when dir is omitted, deployment path is functionRoot/name
Full 30+ fields grouped by basic / code & deps / advanced / triggers / VPC / WebSocket / concurrency / image in Config File - Cloud Function

Example:

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

integrations

Integration configuration item array, where each element describes an Integration Center configuration (Weixin Pay, Official Account, AI tools, etc.). Integration Center handles credential storage, callback verification, and signing as platform-side concerns, so your business code only consumes the SDK or HTTP surface. See Configuration File - Integration for the full field list.

Property	Value
Type	`Array<Integration>`
Description	Each element describes the configuration of an integration (`keyId`, `authTypeCode`, `envVariables`, etc.)

Common Fields at a Glance

keyId (required): Unique identifier of the integration instance, used to match an existing instance in the cloud; unique within an envId
authTypeCode (required): Integration type code, determines which SCF template Integration Center deploys; query with tcb integration types
envVariables: Credential-type env vars managed by Integration Center (do not hard-code in business code); supports the @ file reference syntax
demoCodeFunctionName: Cloud function name to bind
Full field list, common authTypeCode values, credential fields, and the @ file reference syntax: see Configuration File - Integration

app

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. See App Deployment for the full field list, priority rules, and CLI parameter mapping.

Property	Value
Type	`Object`
Description	Cloud app deployment configuration for `tcb app deploy` / `tcb deploy` commands

Common Fields at a Glance

serviceName: Cloud app service name, defaults to the package.json name or directory name
root: App project root directory (relative to cloudbaserc.json), for specifying sub-project paths in monorepo scenarios
framework: Frontend framework react / vue / vite / next / nuxt / angular / static
buildCommand / outputDir: Build command and output directory; pure static projects can skip the build
deployPath: Static hosting mount path, must start with /
Full 9 fields, priority rules, and CLI parameter mapping: see App Deployment

gateway

CloudBase gateway routing configuration for declarative deployment via tcb deploy. Defines how HTTP requests are forwarded to upstream services (cloud functions, static hosting, etc.) by "domain + path". See Configuration File - Gateway for the full field list.

Property	Value
Type	`Object`
Description	CloudBase gateway routing configuration for declarative deployment via `tcb deploy`

Common Fields at a Glance

routes (required): Gateway route list; each item defines a "domain + path → upstream" forwarding rule
routes[].path (required): URL path, e.g. /api; wildcard * is not supported
routes[].target (required): Target resource function:<name> (cloud function) or hosting:<name> (static hosting)
routes[].domain: Bound custom domain; when not bound, tcb deploy auto-binds (idempotent)
routes[].accessType: Domain access type DIRECT / CDN / CUSTOM / EO
Full 13 routes[] fields and detailed notes on access types, protocols, certificates, and rate limiting: see Configuration File - Gateway

hosting

Static hosting app configuration (array, multi-site) for declarative deployment via tcb deploy. Supports local build (aligned with Netlify): when buildCommand is non-empty, automatically runs install + build then uploads artifacts; for pure static, uploads directly. See Static Website Hosting for the full field list.

Property	Value
Type	`Array<Object>`
Description	Static hosting app configuration for declarative deployment via `tcb deploy`

Common Fields at a Glance

name (required): App name, unique within the same config file, referenced by gateway.routes[].target: hosting:<name>
root: Project root directory (relative to cloudbaserc.json), for monorepo
framework: Frontend framework react / vue / vite / vite-react / vite-vue / next / nuxt / angular / static / custom
buildCommand / outputDir: Build command and output directory; pure static projects upload outputDir directly
deployPath: Static resource deploy path, must start with /, unique across hosting apps
Full 9 fields, framework presets, and relationship with app.envVariables: see Static Website Hosting

database

Database migration configuration for declarative SQL migration execution via tcb deploy. See Relational Database (PostgreSQL) for the full field list, migration file naming convention, and execution order.

Property	Value
Type	`Object`
Description	Database migration configuration for declarative SQL migration execution via `tcb deploy`

Common Fields at a Glance

type (required): Database type, currently only postgresql is supported
migrations: Migration file directory (relative to project root), default ./cloudbase/migrations
Full fields, migration file naming convention, execution order, and rollback notes: see Relational Database (PostgreSQL)

Complete Configuration Example

Here is a complete example containing common configurations:

{
  "version": "2.1",
  "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": [
    {
      "keyId": "myPayment",
      "authTypeCode": "weixinpaydc",
      "envVariables": {
        "MCH_ID": "1234567890",
        "API_KEY": "your-api-key"
      }
    }
  ],
  "hosting": [
    {
      "name": "web",
      "root": "./web",
      "framework": "vite",
      "outputDir": "dist",
      "buildCommand": "npm run build",
      "installCommand": "npm install",
      "deployPath": "/",
      "envVariables": {
        "VITE_APP_ID": "your-app-id"
      },
      "ignore": [
        "node_modules",
        ".git"
      ]
    }
  ],
  "gateway": {
    "routes": [
      {
        "path": "/api",
        "target": "function:api"
      },
      {
        "path": "/",
        "target": "hosting:web"
      }
    ]
  },
  "database": {
    "type": "postgresql",
    "migrations": "./cloudbase/migrations"
  }
}

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:

Default Loading: .env and .env.local are always loaded.
Mode-based Loading: When using the --mode <mode> parameter, additionally load the .env.[mode] file.
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"]}

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

For more details on integration configurations, see Configuration File - Integration.

JSON Schema​

Configuration Fields​

version​

envId​

region​

functionRoot​

functions​

integrations​

app​

gateway​

hosting​

database​

Complete Configuration Example​

Dynamic Variables​

Data Source​

Environment Variables​

File Loading Rules​

Usage Example​

Extended Syntax​

Basic Key-Value Pairs​

Compound Key-Value Pairs​

Referencing in Configuration Files​

JSON Schema

Configuration Fields

version

envId

region

functionRoot

functions

integrations

app

gateway

hosting

database

Complete Configuration Example

Dynamic Variables

Data Source

Environment Variables

File Loading Rules

Usage Example

Extended Syntax

Basic Key-Value Pairs

Compound Key-Value Pairs

Referencing in Configuration Files