Application Deployment

version tip

This module has been added since v5.0.0.

The CloudAppService provides deployment management capabilities for Web applications, accessible via app.cloudAppService.

Differences from CloudRun

• app.cloudAppService (this document): CloudApp application deployment, currently supporting the static-hosting (Static Hosting) deployment type, providing complete application version management.
• app.cloudBaseRun (formerly known as app.cloudApp, deprecated alias): Cloud Run (CloudBaseRun / TCBR), used for containerized service deployment. These are independent services; do not confuse them.

Naming Migration Notice

Prior to v5.0.0, app.cloudApp was used as the access point for CloudBaseRunService (Cloud Run).

Starting from v5.0.0:

• app.cloudApp — Deprecated, can still access CloudBaseRunService, but migration to app.cloudBaseRun is strongly recommended.
• app.cloudAppService — New access point for CloudApp application deployment service

---

createApp

1. API Description

API feature: Create or update CloudApp applications (initial call creates the application, subsequent calls with the same application name trigger an update deployment)

API declaration: app.cloudAppService.createApp(params): Promise<ICreateCloudAppResult>

2. Input Parameters

Field	Required	Type	Description
deployType	Yes	DeployType	Deployment type: static-hosting (Static Hosting) / http-function (reserved)
serviceName	Required	String	Application service name, globally unique
envId	No	String	Environment ID, defaults to the envId during initialization
buildType	No	BuildType	Build type: GIT / ZIP (default) / TEMPLATE
staticConfig	No	IStaticConfig	Static Hosting configuration (used when deployType is static-hosting)

IStaticConfig

Field	Required	Type	Description
cosTimestamp	Required	String/Number	COS upload timestamp (returned by uploadCode)
framework	No	String	Framework type: vue, react, next, nuxt, vite, angular, static
nodeJsVersion	No	String	Node.js version, default 20
appPath	No	String	Access path (hosting mount path), default /serviceName
buildPath	No	String	Build artifacts directory
staticCmd	No	IStaticCmd	Build command configuration
staticEnv	No	IStaticEnv	Static environment variables

IStaticCmd

Field	Description
buildCmd	Build command (e.g. npm run build)
installCmd	Installation command (e.g. npm install)
deployCmd	Deployment command (usually automatically generated, no manual specification required)

3. Return Results

Field	Type	Description
ServiceName	String	Application service name
BuildId	String	Build ID, used for polling status
RequestId	String	Unique identifier of the request

---

describeAppList

1. API Description

API feature: Query the CloudApp application list

API declaration: app.cloudAppService.describeAppList(params): Promise<IDescribeCloudAppListResult>

2. Input Parameters

Field	Required	Type	Description
deployType	Required	DeployType	Deployment type: static-hosting, etc.
envId	No	String	Environment ID
pageNo	No	Number	Page number (starting from 1)
pageSize	No	Number	Page size
searchKey	No	String	Fuzzy search by application name

3. Return Results

Field	Type	Description
Total	Number	Total applications
ServiceList	CloudAppServiceItem[]	Application list
RequestId	String	Unique identifier of the request

CloudAppServiceItem

Field	Type	Description
ServiceName	String	Application service name
DeployType	String	Deployment type
Framework	String	Framework type
Domain	String	Access domain
AppPath	String	Access path
CreateTime	String	Creation time
LatestVersionName	String	Latest version name
LatestStatus	String	Latest version status: BUILDING / SUCCESS / FAILED
LatestBuildTime	String	Latest build time

---

describeAppInfo

1. API Description

API feature: Query the details of a single CloudApp application.

API declaration: app.cloudAppService.describeAppInfo(params): Promise<IDescribeCloudAppInfoResult>

2. Input Parameters

Field	Required	Type	Description
deployType	Required	DeployType	Deployment type
serviceName	Required	String	Application service name
envId	No	String	Environment ID

3. Return Results

Field	Type	Description
ServiceName	String	Application service name
DeployType	String	Deployment type
Framework	String	Framework type
Domain	String	Access domain
AppPath	String	Access path
CreateTime	String	Creation time
LatestVersionName	String	Latest version name
LatestStatus	String	Latest version status
LatestBuildTime	String	Latest build time

---

deleteApp

1. API Description

API feature: Delete CloudApp application (including all historical versions)

API declaration: app.cloudAppService.deleteApp(params): Promise<IDeleteCloudAppResult>

2. Input Parameters

Field	Required	Type	Description
deployType	Required	DeployType	Deployment type
serviceName	Required	String	Application service name
envId	No	String	Environment ID

3. Return Results

Field	Type	Description
Result	Boolean	whether the deletion was successful
RequestId	String	Unique identifier of the request

---

describeAppVersion

1. API Description

API feature: Query details of a specified application version (including build status).

API declaration: app.cloudAppService.describeAppVersion(params): Promise<IDescribeCloudAppVersionResult>

2. Input Parameters

Field	Required	Type	Description
deployType	Required	DeployType	Deployment type
serviceName	Required	String	Application service name
envId	No	String	Environment ID
versionName	No	String	Version name (either this or buildId)
buildId	No	String	Build ID (either this or versionName)

3. Return Results

Field	Type	Description
BuildType	String	Build type
BuildId	String	Build ID
Status	String	Build status: BUILDING / SUCCESS / FAILED / PENDING
Domain	String	Version access domain (present when status is SUCCESS)
Url	String	Version access URL (present when status is SUCCESS)
BuildDuration	Number	Build duration (seconds)
FailReason	String	Failure reason (present when status is FAILED)

---

describeAppVersionList

1. API Description

API feature: Query application version list

API declaration: app.cloudAppService.describeAppVersionList(params): Promise<IDescribeCloudAppVersionListResult>

2. Input Parameters

Field	Required	Type	Description
deployType	Required	DeployType	Deployment type
serviceName	Required	String	Application service name
envId	No	String	Environment ID
pageNo	No	Number	Page number
pageSize	No	Number	Page size

3. Return Results

Field	Type	Description
Total	Number	Total versions
VersionList	CloudAppVersion[]	Version list
RequestId	String	Unique identifier of the request

---

deleteAppVersion

1. API Description

API feature: Delete the specified historical version of the application

API declaration: app.cloudAppService.deleteAppVersion(params): Promise<Object>

2. Input Parameters

Field	Required	Type	Description
deployType	Required	DeployType	Deployment type
serviceName	Required	String	Application service name
versionName	Required	String	Version name to be deleted
envId	No	String	Environment ID

---

Code Upload

uploadCode

1. API Description

API feature: Compress and upload local code to COS for subsequent createApp deployment.

API declaration: app.cloudAppService.uploadCode(params): Promise<IUploadCloudAppCodeResult>

tip

Typically, the CLI (tcb app deploy) automatically calls this API to complete code upload, eliminating the need for manual invocation. Manual invocation is only required when directly using the SDK for automated deployment.

2. Input Parameters

Field	Required	Type	Description
envId	No	String	Environment ID
serviceName	Required	String	Application service name
filePath	Required	String	The local absolute path of the file or directory to be uploaded
ignore	No	string[]	glob patterns for files/directories to ignore during upload
onProgress	No	Function	Upload progress callback (data: IProgressData) => void

3. Return Results

Field	Type	Description
cosTimestamp	String	COS upload timestamp, must be passed to createApp's staticConfig.cosTimestamp
RequestId	String	Unique identifier of the request

---

Complete Usage Sample

import CloudBase from '@cloudbase/manager-node'
import path from 'path'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function deployApp() {
  const serviceName = 'my-react-app'

  // 1. Upload code
  console.log('Uploading code...')
  const { cosTimestamp } = await app.cloudAppService.uploadCode({
    serviceName,
    filePath: path.resolve('./my-react-app'),
    ignore: ['**/node_modules/**', '**/.git/**']
  })

  // 2. Create/Update application
  console.log('Triggering deployment...')
  const { BuildId } = await app.cloudAppService.createApp({
    deployType: 'static-hosting',
    serviceName,
    buildType: 'ZIP',
    staticConfig: {
      framework: 'react',
      cosTimestamp,
      appPath: `/${serviceName}`,
      buildPath: 'build',
      staticCmd: {
        buildCmd: 'npm run build',
        installCmd: 'npm install'
      }
    }
  })

  // 3. Poll build status
  console.log('Waiting for build completion, BuildId:', BuildId)
  let status = 'BUILDING'
  while (status === 'BUILDING' || status === 'PENDING') {
    await new Promise(r => setTimeout(r, 5000))
    const version = await app.cloudAppService.describeAppVersion({
      deployType: 'static-hosting',
      serviceName,
      buildId: BuildId
    })
    status = version.Status
    console.log('Build status:', status)
  }

  if (status === 'SUCCESS') {
    const info = await app.cloudAppService.describeAppInfo({
      deployType: 'static-hosting',
      serviceName
    })
    console.log('Deployment succeeded! Access URL: ', info.Domain)
  } else {
    console.error('Deployment failed')
  }
}

deployApp()