Node.js

Guara Cloud fully supports Node.js applications, including frameworks like Express, Fastify, Next.js, NestJS, and any other Node.js-based project.

Supported versions

The following Node.js versions are auto-detected:

• Node.js 18 (LTS)
• Node.js 20 (LTS)
• Node.js 22 (Current)

The version is auto-detected from the engines field in your package.json. If no version is specified, the latest LTS version is used.

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

Deploy with Dockerfile

For full control over your build, provide a Dockerfile in the root of your repository.

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --production

COPY . .

EXPOSE 3000

CMD ["node", "server.js"]

const express = require('express');
const app = express();

const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(PORT, () => {
  console.log('Server running on port ' + PORT);
});

Deploy with Buildpack

If your repository does not contain a Dockerfile, Guara Cloud automatically detects your Node.js project by the presence of a package.json file.

The auto-detection will:

1. Detect the Node.js version from engines in package.json
2. Detect your package manager from lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb)
3. Install dependencies with the detected package manager
4. Execute the build script if defined
5. For server apps: start using the start script
6. For static sites (Astro, Vite, React, Angular): serve with Caddy automatically

Frameworks like Next.js, Nuxt, Astro, Vite, Angular, Remix, and SvelteKit are automatically detected and configured. Corepack is supported for package manager version pinning.

Make sure your package.json includes a start script for server applications:

{
  "scripts": {
    "start": "node server.js"
  }
}

Port configuration

Your application must listen on the port configured in your service settings. The default is 3000, but you can change it at any time to match your application.

const PORT = process.env.PORT || 3000;
app.listen(PORT);

Example project structure

my-node-app/
  package.json
  package-lock.json
  server.js
  src/
    routes/
    middleware/
  Dockerfile          # optional — omit to use Buildpack

Environment variables

These environment variables are commonly used with Node.js deployments:

Common pitfalls