Deploy a Node.js app

What this covers

A Node.js app is any server-side JavaScript application — Express APIs, Fastify services, Next.js with a custom server, or WebSocket backends. The platform clones your repository, detects your package manager from the lockfile (pnpm-lock.yaml → pnpm, yarn.lock → yarn, otherwise npm), installs dependencies, runs your build script automatically if package.json defines one, and starts your app with the command you specify. No database is provisioned automatically.

Before you start

Your GitHub repository must contain a package.json in the root directory. Your app must listen on the port provided by the $PORT environment variable (e.g. app.listen(process.env.PORT)). You do not need a start command: we detect it from package.json or your entry file, and leaving the field blank is the right default. Do not commit a .env file to your repository — the platform passes your environment variables to the app directly, and frameworks such as Next.js re-read a committed .env at startup and can overwrite them. Do not set NODE_ENV=production as a variable either: the platform already builds in production mode, and setting it makes the install skip devDependencies, which breaks any build that needs TypeScript or a bundler.

How to do it

1. Purchase an App Hosting plan or start a free trial from the Services page.
2. Push your Node.js project to a public GitHub repository. Ensure package.json is at the root.
3. Make sure your app binds to the port provided by process.env.PORT.
4. Navigate to Portal → Services and open your App Hosting service.
5. In the Deploy App section, set Action to Deploy Node.js app and Runtime to node.
6. Paste your GitHub repository URL into the Artifact Reference field.
7. Leave the Start Command field empty. We work it out from your repository, in this order: the "start" script in package.json, then package.json "main", then the first of server.js, index.js, app.js, src/index.js, src/server.js, dist/index.js, dist/server.js or build/index.js. ⚠️ Anything you type here OVERRIDES that, so a command that does not match your layout will break a deploy that would otherwise have worked. Only fill it in if your server starts in a way the list above cannot express. If nothing runnable is found the deploy fails and says so — it does not start a broken process.
8. Add any required environment variables using the Environment Variables fields.
9. Click Redeploy App. The platform installs dependencies with your lockfile's package manager (npm, pnpm, or yarn), runs your build script if present, and starts your server.
10. No database is provisioned automatically. If your app needs one, deploy PocketBase as a separate service, or connect an external database by adding your own environment variables.
11. Visit your assigned domain to confirm your app is running.

What our team checks

Support checks that your repository is accessible, package.json is present, the start command is valid, and the app responds on the health path after startup.