Deploying Node.js App
Zeabur supports various types of Node.js projects:
- Native projects (supporting NPM/Yarn/PNPM/Bun and other package managers)
- Projects bundled with Vite
- Qwik
- Next.js
- Remix
- Nuxt.js
- Umi
- Svelte (Kit)
- Nest.js
- Nue.js
- Express
- Astro
- Waku
- Nue
- Create React App
- vue-cli
- Hexo
- Vitepress
- Astro (static, SSR)
- Slidev
- Docusaurus
- Solid Start (Node, static)
Monorepo Support
Zeabur will automatically recognize pnpm workspace (opens in a new tab), Yarn Workspace (opens in a new tab), 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 (opens in a new tab) and Rush (opens in a new tab), 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"
}
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 (opens in a new tab), 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 (opens in a new tab), which is usually the default.
Deploying in Serverless Mode
If your Node.js project meets the following criteria, you can deploy it in Serverless mode on Zeabur:
- Project is built with frameworks designed for Serverless deployment, such as Next.js (opens in a new tab), Nuxt.js (opens in a new tab), Remix (opens in a new tab), etc.
- The Project does not use the above frameworks, but the service itself meets the concept of Serverless: the state of each request is independent of each other, and can automatically sleep when there is no request.
Enable Serverless
If your project is written using Next.js, Nuxt.js, Waku, Angular, and Remix
(a complete list can be found in the getServerless
function of zeabur/zbpack
repository (opens in a new tab)),
Zeabur will automatically deploy the project in serverless form.
If you need to disable this, please refer to the Enable Serverless chapter.
For projects written in other frameworks (or you build your serverless function manually), opting in is currently required. Please refer to the Enable Serverless page to enable serverless support. If there are no issues during testing, feel free to submit a Pull Request to the zbpack code repository (opens in a new tab) for supporting your framework.
Building Project in Serverless Format
If your project uses frameworks such as Next.js, Nuxt.js, Remix, etc., you can skip this step because zbpack (opens in a new tab) will automatically convert it to Serverless format.
However, if your project does not use the above frameworks, you need to build your project into Serverless format yourself. Here is an example of a basic Express.js application:
// app.js
const express = require('express')
const app = express()
app.get('/', (req, res) => {
res.send('Hello World!')
})
module.exports = app
In the above example, you can see that the app.js
module has already exported the app
object, which is an object that conforms to the Serverless processing function format of Zeabur. Therefore, all we have to do is to output it to the index.func
directory under .zeabur/output/functions
during the build phase.
To achieve this, we can add the following script to the code:
// scripts/build.js
const esbuild = require('esbuild');
const fs = require('fs');
// dynamic-required files
const dynamicRequiredDirs = ['views']
// static files
const staticFileDirs = ['public']
// Remove old output
if (fs.existsSync('.zeabur/output')) {
console.info('Removing old .zeabur/output')
fs.rmSync('.zeabur/output', {recursive: true})
}
function getModuleEntries() {
function getModuleEntriesRecursive(dir) {
let entries = []
fs.readdirSync(dir).forEach(file => {
const path = `${dir}/${file}`
if (fs.statSync(path).isDirectory()) {
if(file === 'node_modules') return
entries = entries.concat(getModuleEntriesRecursive(path))
} else if (file.endsWith('.js')) {
entries.push(path)
}
})
return entries
}
return getModuleEntriesRecursive('.')
}
// build with esbuild
try {
esbuild.build({
entryPoints: getModuleEntries(),
bundle: false,
minify: false,
outdir: '.zeabur/output/functions/index.func',
platform: 'node',
target: 'node20',
plugins: [{
name: 'make-all-packages-external',
setup(build) {
let filter = /^[^.\/]|^\.[^.\/]|^\.\.[^\/]/ // Must not start with "/" or "./" or "../"
build.onResolve({filter}, args => ({path: args.path, external: true}))
},
}],
}).then(res => {
if (res.errors.length > 0) {
console.error(res.errors)
process.exit(1)
}
console.info('Successfully built app.js into .zeabur/output/functions/index.func')
fs.copyFileSync('.zeabur/output/functions/index.func/app.js', '.zeabur/output/functions/index.func/index.js')
fs.rmSync('.zeabur/output/functions/index.func/app.js')
})
} catch (error) {
console.error(error)
}
// copy node_modules into function output directory
console.info('Copying node_modules into .zeabur/output/functions/index.func/node_modules')
fs.cpSync('node_modules', '.zeabur/output/functions/index.func/node_modules', {recursive: true, verbatimSymlinks: true})
// copy package.json into function output directory
console.info('Copying package.json into .zeabur/output/functions/index.func')
fs.cpSync('package.json', '.zeabur/output/functions/index.func/package.json')
// copy dynamic-required files into function output directory, so they can be required during runtime
dynamicRequiredDirs.forEach(dir => {
copyIfDirExists(dir, `.zeabur/output/functions/index.func/${dir}`)
})
// copy static files into function output directory, so they can be served by the web server directly
staticFileDirs.forEach(dir => {
copyIfDirExists(dir, `.zeabur/output/static`)
})
function copyIfDirExists(src, dest) {
if (fs.statSync(src).isDirectory()) {
console.info(`Copying ${src} to ${dest}`)
fs.cp(src, dest, {recursive: true}, (err) => {
if (err) throw err;
});
return
}
console.warn(`${src} is not a directory`)
}
This script does a straightforward thing, it uses esbuild (opens in a new tab) to build your project, then puts all .js
files into the .zeabur/output/functions/index.func
directory according to the original relative path, and copies node_modules
and package.json
to the .zeabur/output/functions/index.func
directory, so that the project is built.
Note in particular that we have retained two special configurable fields in this script:
// dynamic-required files
const dynamicRequiredDirs = ['views']
// static files
const staticFileDirs = ['public']
These two fields allow us to put things other than .js
into the output, where dynamicRequiredDirs
is a file that is only required at runtime, such as a template file in the views
directory; staticFileDirs
is a static file, such as a static resource in the public
directory, which is placed in the .zeabur/output/static
directory so that they can be distributed to users around the world by the Zeabur Edge Network at a faster speed.
Don't forget to install esbuild
in your project after adding this script, and add the build
command to the scripts
in package.json
:
{
"scripts": {
"build": "node scripts/build.js"
}
}
You can find the complete sample code at zeabur/expressjs-template (opens in a new tab) or modify the scripts/build.js
script according to your needs.
Additional Notes
-
You should get the port to listen from
process.env.PORT
.For example:
const port = process.env.PORT || 3000 // instead of const port = 3000
-
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" } }