GuidesNode.js

Deploying Node.js App

Zeabur supports various types of Node.js projects:

Monorepo Support

Zeabur will automatically recognize pnpm workspace, Yarn Workspace, and most toolchains based on these two Monorepo approaches, such as Turborepo and Lerna.

Take the basic template of Turborepo as an example, its pnpm-workspace.yaml content is as follows:

packages:
  - "apps/*"
  - "packages/*"

Under apps, there are two directories, docs and web. By default, Zeabur will select the first Node.js application listed in the workspace package list to deploy. In this case, Zeabur will deploy the application under apps/docs. If you want to deploy apps/web, you can create a zbpack.json file in the root directory of the project and add the following content:

{
    "app_dir": "apps/web"
}

Or use environment variables to set it:

ZBPACK_APP_DIR=apps/web

This will deploy the apps/web application.

If your application is indeed in the root directory but leverage pnpm-workspace.yaml to place React components, design systems, etc, you can use the environment variable ZBPACK_APP_DIR=/ or add the following to zbpack.json

{
    "app_dir": "/"
}

to have Zeabur deploy your application placed in the root directory.

Nx and Rush, which are not based on the above two Monorepo approaches, are not yet supported for one-click deployment. You can refer to “Disable Cache Functionality” and “Modifying Build and Start Commands” to configure Monorepo.

Disabling Cache Functionality

By default, Zeabur rearranges the installation process to speed up your CI/CD by recording the steps of dependency installation. This should not affect most Node.js projects, but if your project needs to use other files in the project during dependency installation which leads to a project compilation failure, you may need to disable the caching feature.

To disable this feature, create a zbpack.json file in the root directory of your project and add the following content:

{
    "cache_dependencies": false
}

Or set environment variables:

ZBPACK_CACHE_DEPENDENCIES=false

Modifying Build and Start Commands

If your project type is more specialized (such as using a custom Monorepo toolchain), you may need to specify the build and start commands for the service, for example, change the start command of the frontend service to pnpm run start:frontend; change the build command of the api service to pnpm run start:api.

Here are two ways to modify these commands.

Modifying via Files

Add the following two settings to zbpack.json:

{
    "build_command": "<custom build command>",
    "start_command": "<custom start command>"
}

The default settings in zbpack.json will be applied to all deployed services. If you want to specify different commands for different services (e.g., use a specific command for a service named api and another command for a service named frontend), you need to create a file named zbpack.[service name].json:

// zbpack.api.json
{
    "build_command": "pnpm run build:api",
    "start_command": "pnpm run start:api"
}
// zbpack.frontend.json
{
    "build_command": "pnpm run build:frontend",
    "start_command": "pnpm run start:frontend"
}

The priority of applying the settings is zbpack.[service name].json > zbpack.json.

Modify Using Environment Variables

You can also use environment variables to set the build and start commands:

ZBPACK_BUILD_COMMAND=pnpm run build:api
ZBPACK_START_COMMAND=pnpm run start:api

Configure Node.js Version and Package Manager Version

Node.js Version

By default, Zeabur uses the latest LTS version of Node.js to build your project.

If you want to use a different version, you can specify it in your package.json:

{
    "engines": {
        "node": "18.1.0"
    }
}

Package Manager Version

By default, Zeabur uses yarn to install dependencies for your project. If you want to use a different package manager, you can specify it in your package.json:

{
    "packageManager": "pnpm@8.0.0"
}

Static Website Deployment

If your project only needs to generate pure frontend web pages (without a backend server), it can be hosted directly using web servers like NGINX or Caddy. You can let Zeabur deploy it in a more lightweight way, thereby saving resource usage and costs.

  1. First, confirm which folder your build command generates the final web files in (commonly dist, build, or public folders)

  2. Then, add this environment variable to tell Zeabur where the web files are:

    ZBPACK_OUTPUT_DIR=dist

    You can also write the configuration to zbpack.json:

    {
    "output_dir": "dist"
}

  3. This way, after the next build completes, Zeabur will use the resource-efficient Caddy to host your website.

Web Scraping

Playwright Support

If your package.json declares playwright-chromium, Zeabur will automatically prepare the necessary environment to run Playwright.

Note that Playwright should be run in Headless mode, which is usually the default.

Puppeteer Support

If your package.json declares puppeteer, Zeabur will automatically prepare the necessary environment to run Puppeteer.

Note that Puppeteer should be run in Headless mode, which is usually the default.

Additional Notes

  1. You should get the port to listen from process.env.PORT.

    For example:

    const port = process.env.PORT || 3000
// instead of const port = 3000

  2. Avoid using nodemon as runtime. Execute your command with general node command in production.

    For example, in package.json:

    {
    "scripts": {
        "start": "node server.js"
        // instead of "start": "nodemon server.js"
    }
}
Private NetworkingAstro