> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instapods.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js

> Node.js preset with npm and systemd process management. Versions 18, 20, 22 (default), and 24 available.

The Node.js preset provides Node.js with npm, managed by a systemd service for automatic restarts and logging.

## Available Versions

| Version | Status |
| - | - |
| **Node.js 18** | LTS |
| **Node.js 20** | LTS |
| **Node.js 22** | LTS (default) |
| **Node.js 24** | LTS |

Select a version when creating your pod. If not specified, Node.js 22 is used.

```bash theme={null}
instapods pods create my-app -p nodejs --version 24
```

### Switching Version Later

You aren't locked into the version you picked. On the pod's detail page, the **Node version** picker
in the pod info panel switches an existing pod to any supported major in place - your files,
environment variables, domain and plan all stay as they are.

<Tabs>
  <Tab title="Dashboard">
    Open the pod, choose a version next to **Node version**, and click **Switch**.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://app.instapods.com/api/pods/my-app/node-version \
      -H "Authorization: Bearer YOUR_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"version": "22"}'
    ```
  </Tab>
</Tabs>

The switch installs the new Node, rebuilds native modules, and restarts your app. It runs in the
background and takes a couple of minutes, so the call returns straight away - watch the pod's
**Events** tab for the result.

<Note>
  If your `package.json` declares an `engines.node` your pod doesn't meet, you don't need to do this
  by hand: [Deploy Doctor](/support/troubleshooting#deploy-doctor) spots it and offers the switch as
  a one-click fix.
</Note>

## What's Included

| Component | Version | Details |
| - | - | - |
| **Node.js** | 18, 20, 22, or 24 (your choice) | JavaScript runtime |
| **npm** | Bundled with Node.js | Package manager |
| **systemd** | — | Process manager (`app` service) |
| **git** | Latest | Version control |
| **SSH** | OpenSSH | Access via dedicated port |

Pre-installed utilities: curl, wget, vim, htop, unzip.

## Directory Structure

```
/home/instapod/app/
├── package.json
├── index.js            # Entry point (configurable)
└── node_modules/       # (after npm install)
```

* **App Root**: `/home/instapod/app`
* **App Port**: 3000 (your app must listen on this port)
* **Environment**: `NODE_ENV=production` is set by default

## How the App Service Works

Your Node.js app runs as a systemd service called `app`. It:

* Runs `/usr/bin/node index.js` from `/home/instapod/app`
* Starts automatically on boot
* Restarts on crash (`on-failure` policy)
* Logs to the system journal (viewable via the Logs tab or CLI)
* Runs as the `instapod` user

The service expects your app to listen on port **3000**. The nginx proxy on the server forwards traffic from your pod's public URL to this port.

<Warning>
  Your app **must** bind to `0.0.0.0` (not `localhost` or `127.0.0.1`) on port 3000, otherwise it won't be reachable from the public URL.
</Warning>

## Deploying Your App

### Upload and Reload

```bash theme={null}
# Sync your project
instapods files sync my-node-app --local ./my-project

# Reload (auto-installs deps + restarts)
instapods pods reload my-node-app
```

<Tip>
  `pods reload` automatically runs `npm install --production` when it detects a `package.json` in your app directory. You don't need to install dependencies manually.
</Tip>

### Example Express App

```javascript theme={null}
// index.js
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello from InstaPods!');
});

app.listen(3000, '0.0.0.0', () => {
  console.log('Server running on port 3000');
});
```

```json theme={null}
{
  "name": "my-app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.18.0"
  }
}
```

## No Hot Reload

Node.js does not support hot reloading of code. Every code change requires a full process restart via `pods reload`. The restart takes about 1 second and causes a brief interruption.

## Viewing Logs

```bash theme={null}
instapods logs my-node-app -s app
```

## Adding a Database

```bash theme={null}
instapods services add my-node-app -s postgresql -w
instapods services creds my-node-app -s postgresql
```

<Note>
  Database services require the Build plan or higher.
</Note>

## Use Cases

* Express / Fastify APIs
* Next.js applications (standalone mode)
* GraphQL servers
* Real-time apps with WebSockets
* Background workers and job queues


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.