Config File

The cloudbaserc.json file serves as the core configuration file for CloudBase 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 Pull configuration and Push configuration.

Configuration File Lookup

The CLI looks for the following files in the project directory in order and uses the first match:

1. cloudbaserc
2. cloudbaserc.json
3. cloudbaserc.yaml
4. cloudbaserc.yml
5. cloudbaserc.js
6. cloudbase.config.js

An object-typed cloudbase field in package.json is also supported and takes precedence over the files above.

The project directory is set by the global options --cwd / --workdir and defaults to the current directory. See Global Options. When --cwd is given, only that level is searched, without traversing parent directories; if no config file is found there, the project is treated as having none.

When --config-file is given, that file is used and is resolved against the current directory; the lookup above is skipped.

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	CloudBase 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	Static hosting 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	Not required (can be omitted)
Description	Config file version. The current schema only accepts "2.1"; the CLI no longer writes this field, so omitting it means the latest format
Example	"version": "2.1" (optional)

envId

Property	Value
Type	String
Description	CloudBase 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 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

Static hosting 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	Static hosting app deployment configuration for tcb app deploy / tcb deploy commands

Common Fields at a Glance

• serviceName: Static hosting app service name, defaults to the package.json name or directory name
• root: App root directory (relative to the project directory), 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. Build and deploy are separated: run tcb app build locally first to generate the output, then tcb deploy only uploads it (no longer runs local builds automatically); pure static (no buildCommand) 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: App root directory (relative to the project directory), 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.

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

Fields:

Field	Type	Required	Default	Description
type	String	Yes	—	Database type, currently only postgresql is supported
migrations	String	No	./cloudbase/migrations	Migration file directory, relative to the project directory, relative paths only

{
  "database": {
    "type": "postgresql",
    "migrations": "./cloudbase/migrations"
  }
}

Migration files follow the <14-digit-timestamp>_<name>.sql naming, for example 20240101120000_init.sql. The CLI executes files in ascending lexicographic order, records applied files in the __migrations table, and never runs them twice.

Declarative migrations do not support automatic rollback, write the reverse SQL manually. To manage migration records by hand, see Repair migration history.

Complete Configuration Example

Here is a complete example containing common configurations:

{
  "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

The configuration file supports the dynamic variables feature: use the {{}} syntax to dynamically obtain configuration values from environment variables or other data sources. It does not depend on the version field ("2.0" is no longer accepted by the current schema and will fail validation).

💡 Note: Dynamic variables are only available in JSON config files.

Basic Example:

{
  "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:

{
  "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:

{
  "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.

---

Notes

tcb app deploy and tcb deploy read the same app config, but build differently since v3.9.0:

	tcb app deploy	tcb deploy (declarative)
Build	Cloud build (install dependencies + run buildCommand)	No build; uploads outputDir artifacts as-is
outputDir	Optional (interactive prompt / dist default)	When unset, inferred from buildCommand / framework / package.json; pure-static items fall back to the project root
installCommand / buildCommand	Applied	Ignored — use tcb app build locally

Use tcb app deploy for a cloud build and tcb deploy to deploy artifacts that are already built — see Declarative deployment · Notes.