Frontend Runtime Environment

You can deploy frontend apps (like websites) to Cloud Engine. For apps built with frameworks like React and Vue, their build processes can be run on Cloud Engine so you don’t have to clutter your Git repositories with production builds or set up additional CI environments. With Cloud Engine, you can easily bind custom domains to your app, set up auto-renewal for SSL certificates, and enable HTTPS redirects. These features help you reduce the time spent on deploying and maintaining your app.

info

This article serves as an introduction to Cloud Engine’s frontend runtime environment. For features provided by the Cloud Engine platform, see Cloud Engine Platform Features.

If your project has a file named static.json or index.html under its root directory, Cloud Engine will identify it as a frontend project. When you deploy your project, Cloud Engine will build it with the Node.js runtime environment and automatically start an HTTP server with serve.

Getting Started

Most frontend scaffolds can be deployed to Cloud Engine with little to no configurations. Consider using them if you plan to create a new project.

React

create-react-app provides out-of-the-box toolchains that automatically set up build tools for your React project so you can focus on development:

npx create-react-app react-for-engine --use-npm

Then navigate to the project’s directory (react-for-engine in the example above) and create a configuration file named static.json that rewrites non-existing URLs to index.html. This allows your single-page application to use its own frontend router (like react-router):

static.json

{
  "public": "build",
  "rewrites": [{ "source": "**", "destination": "/index.html" }]
}

Then create a file named leanengine.yaml and specify the build command in it:

leanengine.yaml

build: npm run build

Vue

You can create a Vue project with Vue CLI:

npm install -g @vue/cli
vue create vue-for-engine

Then navigate to the project’s directory (vue-for-engine in the example above) and create a configuration file named static.json that rewrites non-existing URLs to index.html. This allows your single-page application to use its own frontend router (like vue-router):

static.json

{
  "public": "dist",
  "rewrites": [{ "source": "**", "destination": "/index.html" }]
}

Then create a file named leanengine.yaml and specify the build command in it:

leanengine.yaml

build: npm run build

Next.js

You can create a Next.js project with create-next-app:

npx create-next-app next-for-engine --use-npm

Then navigate to the project’s directory (next-for-engine in the example above), create a file named leanengine.yaml, and specify the build command in it:

leanengine.yaml

build: npm run build

info

In order for Next.js API Routes to work, Cloud Engine will run the project in a Node.js runtime environment by starting a Next.js production server with npm start. The section below regarding configuring serve won’t be applicable to Next.js projects.

The build process can be run on Cloud Engine so you don’t have to include a production build in your Git repository or set up additional CI environments.

Deploy to Cloud Engine

Run the following command to deploy your project to the production environment:

tds deploy --prod

Configure Node.js Version

You can specify the version of Node.js by setting engines.node in package.json:

package.json

{
  "engines": {
    "node": "16.x"
  }
}

You can set it to * to stick to the latest (current) version.

note

If you don’t specify a Node.js version, the latest stable (LTS) version will be used.

Config Package Manager

Cloud Engine now supports these package managers:

• npm
• pnpm
• Yarn 1
• Yarn 2+

Cloud Engine will automatically detect the package manager based on these conditions:

Package Manager	Condition	Version
pnpm	A valid pnpm-lock.yaml exists
	lockfileVersion: '6.0' or higher	8
	lockfileVersion: 5.3 or higher	7
	Otherwise	6
Yarn 1	yarn.lock exists	1
Yarn 2+	Not supported by default, enable via Corepack	2+
npm	Otherwise	npm with the Node.js is used

Experimental Corepack support

Due to Corepack is still experimental, Cloud Engine can't make sure the support for Corepack is stable, use at your own risk

To enable Corepack, setting the ENABLE_EXPERIMENTAL_COREPACK environment variable of the group to any non-empty string.

Cloud Engine will automatically detect package manager based on packageManager field in package.json, then use Corepack to install and enable the package manager. This is the only way to use Yarn 2+ for now.

Assume we have a package.json shown below：

package.json

{
  "name": "example",
  "packageManager": "[email protected]"
}

Now Cloud Engine will call corepack prepare --activate and detect the package manager is Yarn 2+.

Reference：Corepack

Default commands

The default commands may vary depending on the package manager, e.g. if pnpm is used, npm ci will be pnpm install --frozen-lockfile.

Cloud Engine will skip installing the devDependencies only when installDevDependencies is not true and the build script is empty (which either not specified in leanengine.yaml or scripts.build in package.json not exists).

Pharse	Package Mamager	Condition	Command
install	npm	Node.js version is higher then 10 and package-lock.json or npm-shrinkwrap.json exists	npm ci
			npm install or npm install --omit=dev
	pnpm		pnpm install --frozen-lockfile or pnpm install --frozen-lockfile --prod
	Yarn 1		yarn install or yarn install --production
	Yarn 2+		yarn install

note

Be adviced, Yarn 1 will use the resolved URL in yarn.lock without respecting your registry configuration, use proper registry before deploy to Cloud Engine, or build time might increase.

Install Dependencies (package.json)

Cloud Engine will automatically install dependencies according to the package.json in your project:

package.json

{
  "dependencies": {
    "leancloud-storage": "^3.11.0",
    "leanengine": "^3.3.2"
  },
  "devDependencies": {
    "nodemon": "^1.18.7"
  }
}

While installing dependencies, Cloud Engine will trigger the life cycle scripts of npm, such as postinstall and prepare.

Since Cloud Engine installs dependencies on the server side, the CLI won’t upload node_modules by default. If you’re deploying with Git, you should include node_modules in .gitignore so it won’t be tracked by Git.

note

CLI will upload .yarn directory, if you don't want to enable Zero-installs when Yarn 2+ PnP(Plug'n'Play) is used, add .yarn/cache to your .gitignore and .leanignore

Configure serve

To customize the behavior of serve, create a file named static.json under the root directory of your project.

static.json

{
  "public": "build", // Start the website from the `build` directory rather than the root directory
  "rewrites": [
    { "source": "**", "destination": "/index.html" } // Redirect all non-existing URLs to `index.html` (applicable to most single-page applications)
  ]
}

See serve-handler · Options for more options and usages of serve.

Customize Build Process

You can override the default behavior by specifying startup commands (run), dependency installation commands (install), and build commands (build) in leanengine.yaml:

leanengine.yaml

run: echo 'run another command'
install:
  - {use: 'default'}
  - echo 'install additional dependencies here'
build:
  - echo 'overwrite default build command here'

See Reference: leanengine.yaml for more information.

System Dependencies

You can specify the system dependencies provided by the server-side environment using leanengine.yaml:

leanengine.yaml

systemDependencies:
  - imagemagick

See Reference: leanengine.yaml for a complete list of supported system dependencies.

Build Logs

By default, the logs generated during the build process won’t be printed to the console. If the build process fails, the logs from the last completed step will be printed to the console.

To print the complete build log for debugging, check Print build logs if you are deploying from the dashboard or add --options 'printBuildLogs=true' if you are deploying with the CLI.

Cloud Environment

Custom Domains

Projects deployed to Cloud Engine can only be accessed with domains configured. You can bind domains by going to Developer Center > Your game > Game Services > Cloud Services > Cloud Engine > Manage deployment > Your group > Settings > Domains.

If you bind a domain that starts with stg- (e.g., stg-api.example.com), it will be assigned to the staging environment automatically.

We provide shared domains for apps that are still under testing. You can assign your app a shared domain with a prefix of your choice.

Load Balancer and CDN

All HTTP and HTTPS requests sent to Cloud Engine will go through a load balancer that deals with chores including HTTPS encryption, HTTPS redirection, and response compression. You won’t have to implement features for handling these tasks yourself for the programs hosted on Cloud Engine. Meanwhile, the load balancer brings the following restrictions that your program cannot bypass:

• Paths starting with /.well-known/acme-challenge/ are used by Cloud Engine to automatically renew certificates. Requests sent to these paths won’t be forwarded to your program.
• The size of a request header (URL and headers) should be within 64K and each line of the request header should be within 8K.
• The size of a request (for uploading files) should be within 100M.
• The timeout for connecting or waiting for a response is 60 seconds.

HTTPS Redirect

When you bind a custom Cloud Engine domain, you can enable Force HTTPS to have the load balancer redirect HTTP requests to HTTPS while keeping the paths.

Timezone

The timezone used on the server side is UTC+0.