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)

Soporte para Monorepo

Zeabur reconocerá automáticamente pnpm workspace, Yarn Workspace y la mayoría de las cadenas de herramientas basadas en estos dos enfoques Monorepo, como Turborepo y Lerna.

Tomemos como ejemplo la plantilla basic de Turborepo, su contenido de pnpm-workspace.yaml es el siguiente:

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

Y bajo apps hay dos directorios, docs y web. Por defecto, Zeabur seleccionará la primera aplicación Node.js listada en la lista de paquetes del espacio de trabajo para desplegar. En este caso, Zeabur desplegará la aplicación apps/docs. Si deseas desplegar apps/web, puedes crear un archivo zbpack.json en el directorio raíz del proyecto y agregar el siguiente contenido:

{
    "app_dir": "apps/web"
}

O utilizar variables de entorno para configurarlo:

ZBPACK_APP_DIR=apps/web

Esto desplegará la aplicación apps/web.

Si tu aplicación está en el directorio raíz pero usa pnpm-workspace.yaml para colocar componentes de React, sistemas de diseño y otros elementos, puedes usar la variable de entorno ZBPACK_APP_DIR=/ o agregar lo siguiente en zbpack.json

{
    "app_dir": "/"
}

para que Zeabur despliegue tu aplicación colocada en el directorio raíz.

Desactivar caché

Por defecto, Zeabur reorganiza el proceso de instalación para acelerar tu CI/CD grabando los pasos de instalación de dependencias. Esto no debería afectar a los proyectos Node.js en general, pero si tu proyecto necesita usar otros archivos en el proyecto durante la instalación de dependencias y esto provoca un fallo en la compilación del proyecto, es posible que necesites desactivar la función de caché para usarlo correctamente.

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

{
    "cache_dependencies": false
}

O establecer variables de entorno:

ZBPACK_CACHE_DEPENDENCIES=false

Cambiar comandos de construcción y arranque

Si tu tipo de proyecto es más especializado (como el uso de una cadena de herramientas Monorepo personalizada), es posible que necesites especificar los comandos de construcción (build) y arranque (start) para el servicio, por ejemplo, cambiar el comando de arranque del servicio frontend a pnpm run start:frontend; cambiar el comando de construcción del servicio api a 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"
}

La prioridad de aplicación de zbpack.json es zbpack.[nombre del servicio].json es mayor que zbpack.json.

Modificar Usando Variables de Entorno

También puedes usar variables de entorno para establecer los comandos de construcción y arranque:

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

Configurar la Versión de Node.js y la Versión del Gestor de Paquetes

Versión de Node.js

Por defecto, Zeabur utiliza la última versión LTS de Node.js para construir tu proyecto.

Si deseas utilizar una versión diferente, puedes especificarla en tu package.json:

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

Versión del Gestor de Paquetes

Por defecto, Zeabur utiliza yarn para instalar las dependencias de tu proyecto. Si deseas utilizar un gestor de paquetes diferente, puedes especificarlo en tu package.json:

{
    "packageManager": "pnpm@8.0.0"
}

Despliegue de sitios web estáticos

Si tu proyecto solo necesita generar páginas web de frontend puro (sin necesidad de un servidor backend), puedes usar servidores web como NGINX o Caddy para el alojamiento. Esto permite que Zeabur utilice un método más ligero para el despliegue, ahorrando recursos y costos.

1. Primero, confirma en qué carpeta tu comando de compilación genera los archivos web finales (comúnmente en carpetas como dist, build o public)

2. Luego, añade esta variable de entorno para indicarle a Zeabur la ubicación de los archivos web:

   ZBPACK_OUTPUT_DIR=dist

   También puedes escribir la configuración en zbpack.json:

   {
       "output_dir": "dist"
   }

3. De esta manera, después de la próxima compilación, Zeabur utilizará Caddy, que consume menos recursos, para alojar tu sitio web.

Raspado web

Soporte de Playwright

Si tu package.json declara playwright-chromium, Zeabur preparará automáticamente el entorno necesario para ejecutar Playwright.

Ten en cuenta que Playwright debe ejecutarse en modo Headless, que suele ser el valor predeterminado.

Soporte de Puppeteer

Si tu package.json declara puppeteer, Zeabur preparará automáticamente el entorno necesario para ejecutar Puppeteer.

Ten en cuenta que Puppeteer debe ejecutarse en modo Headless, que suele ser el valor predeterminado.

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