How to deploy Node.js on Saplo (custom backend from a repository)

Node.js is not a framework, but a server-side JavaScript runtime. Unlike Next.js or Nuxt, the "Node.js" stack in the Saplo catalog doesn't impose any conventions or project structure. You write your own HTTP server in Express, Fastify, Koa, NestJS, or without any framework, and Saplo just ensures that the process runs continuously and restarts after a crash. This is the most universal backend option in the catalog: it suits an API for a mobile application, a Discord bot, or a websocket server, as long as the project itself exposes an HTTP port.

Who is Node.js on Saplo for?

Before you start the installation, check if it's the right choice for your project:

• API for a mobile application or a SPA frontend - you expose REST or GraphQL, and the frontend (React, Vue) is set up separately from the same directory,
• bot or background integration - webhooks, Discord and Slack bots, queue workers,
• websockets backend - Nginx on Saplo's side passes the Upgrade header, so long-held connections work without additional configuration,
• you have a ready Node.js project and want deployments from git push - you link the repository once, and Saplo builds and restarts the process automatically.

If your project is in a specific framework with its own build and start convention (Next.js, Nuxt), choose its dedicated stack in the catalog - you'll get a ready-made configuration without manually specifying the start command.

Requirements

To set up Node.js on Saplo, you need:

• A Box on L plan or higher - the Node process is kept constantly in memory, so it requires more RAM than a static site.
• A minimum of 512 MB of free RAM and 3 GB of disk space for the application process itself.
• A domain or subdomain *.saploapp.pl included in the price of each plan.
• A Git repository if you want to use automatic deployment (optional at the start, you can also upload the application as a .zip archive through the panel).

Step-by-step installation

1. In the Saplo panel, go to App catalog and select Node.js (category "Applications").
2. Specify a Box with plan L or higher and the application name - a default subdomain will be created from it.
3. Choose the Node.js version (18, 20 or 22, default 20) and confirm the installation.
4. The engine creates a minimal Express starter - package.json and server.js with a single endpoint - and runs it via supervisor on port 3000, while nginx proxies traffic from the domain to this port.
5. After the installation is complete, the domain from step 2 shows a working starter - from this moment on, you replace it with your own code via git deploy.

Deploying Your Own Code via Git

1. In the application details, find the Git / CI-CD section and click "Connect GitHub", then confirm the installation of the "Saplo Deploy" app and point it to your Node project repository.
2. Place the saplo.yaml file in the root directory of your repository. Unlike stacks with specific conventions (Next.js, Nuxt), the Node.js stack does not have a default start command - you must explicitly specify start.command, otherwise the build will succeed, but the process will not start.
3. Commit and push the file to the production branch (by default main).
4. Each subsequent git push to this branch triggers a build and a process restart; you can see the status in the Deployments tab.
5. The default application port is 3000 - nginx directs traffic from 80/443 to it, unless you change it in start.port.

Example of a minimal saplo.yaml file for Node.js:

name: my-project
stack: node
runtime:
  node: "22"
build:
  install: npm ci
start:
  command: node index.js
  port: 3000
env:
  NODE_ENV: production

Node.js on Saplo vs. alternatives

FAQ

Will any framework - Express, Fastify, NestJS - work? Yes, the Node.js stack doesn't impose a framework. It only requires the process to listen on the port specified in start.port (3000 by default).

What happens if I forget about start.command in saplo.yaml? The build will succeed, but the process won't start - you'll see an error in the Deployments tab. Add start.command and push a new version.

Do websockets work through Saplo's nginx? Yes, the reverse proxy passes the Upgrade header, so long-lived WebSocket connections work without additional configuration.

Can I have a database next to the application? Yes, you set up the database (Postgres, MySQL, Redis) as a separate application from the catalog and connect the connection variable in env of your saplo.yaml.

Will I get SSL and my own domain? Yes, the SSL certificate is automatic, and a domain or subdomain *.saploapp.pl is included in the price of every plan.

With Saplo, you can set up Node.js from scratch to a working domain in minutes, and every subsequent git push restarts the process with a new version without your intervention. If your project uses a specific framework with its own convention (Next.js, Nuxt), check its dedicated stack in the same catalog.