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. Public and private repositories both work. For a private one, create a GitHub token with the repo scope and paste it into the GitHub token field when you deploy; leave that field empty for a public repository.
How to do it
- Want to see it work first? Deploy our Node.js starter from the public repository https://github.com/cirro-admin/cmcloudhosting-demo with Subdirectory node and Runtime node. Its README lists every field, and once it runs you have a working reference for your own app.
- Purchase an App Hosting plan or start a free trial from the Services page.
- Push your Node.js project to a GitHub repository. Ensure package.json is at the root.
- Make sure your app binds to the port provided by process.env.PORT.
- Navigate to Portal → Services and open your App Hosting service.
- In the Deploy App section, set Action to Deploy Node.js app and Runtime to node.
- Paste your GitHub repository URL into the Artifact Reference field.
- 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.
- Add any required environment variables using the Environment Variables fields.
- 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.
- Need a database? Add managed PostgreSQL from your service page and pass DATABASE_URL to your app as an environment variable (see Connect your app to PostgreSQL), or run a PocketBase backend as a separate service.
- Visit your assigned domain to confirm your app is running.
Starter code and references
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.
Next step
Push your Node.js project to GitHub with package.json at the root, then open the deploy form.