Primcloud
Docs menu

Getting started with Node.js

Deploy a minimal Node.js app to Primcloud end-to-end using a sample Express repo, in about five minutes.

On this page

This guide walks through deploying a small Node.js app to Primcloud. You'll fork a sample repo, import it, watch the build, and reach the deployed app at a *.primcloud.app URL. Takes about five minutes.

Before you start#

You'll need:

  • A Primcloud account. Standard accounts are free to create; compute is metered by the minute once you deploy, from around $5/mo for the smallest app.
  • A git provider connected to your account with access to at least one repo.
  • Optional: Node.js 22, 24, or 26 installed locally, if you want to run the sample or make changes before deploying.

The sample app#

For this guide, use Heroku's heroku/nodejs-getting-started repo. It's a minimal Express app that builds cleanly on the Primcloud Runtime with no changes. Fork it into an account your connected provider can see, so Primcloud can pull from it.

The repo already includes the two files the build cares about:

  • A package.json with engines.node pinning the runtime and a start script (node index.js).
  • A package-lock.json, npm's lockfile, which locks the build to npm and to a reproducible dependency graph.

1. Create the application#

From the Primcloud dashboard, hit Import Git Repository on the applications list. The import wizard walks you through three quick steps:

  1. Pick a repository: select your fork of nodejs-getting-started.
  2. Configure the deployment:
    • Branch: main (the fork's default).
    • Region: US East (NYC).
  3. Review and create: Primcloud auto-provisions the app's primary *.primcloud.app subdomain on the production environment.

2. Deploy#

The first deployment kicks off automatically when the app is created. Watch it stream in the Deployments tab:

  • Detection. Primcloud sees the package.json at the repo root and picks the Node.js toolchain.
  • Node.js install. The version declared in engines.node is resolved against the Node.js versions the Primcloud Runtime ships and installed. Repeat deploys with the same version are cached, so only the first build pays the download cost.
  • Package manager install. The package-lock.json in the repo tells the build to use npm, and npm ci runs against the lockfile to produce an exact node_modules tree.
  • Build scripts. If the app defines heroku-prebuild, heroku-build / build, or heroku-postbuild in package.json, they run in that order. The sample doesn't ship any of these, so this step is skipped.
  • Prune. After the build, packages your lockfile doesn't list are removed from node_modules. With npm, as here, dev dependencies stay installed.
  • Release. Primcloud reads the Procfile and starts the web process on the pod formation. Without a Procfile, Primcloud would run npm start (the sample has one anyway).

When the deployment status flips to Release Succeeded, the app is live.

3. Reach the app#

The application dashboard shows the assigned *.primcloud.app URL in the header. Click it, and the sample app's homepage loads.

If it doesn't come up:

  • Deployments: the build log has the raw output from the build, including any npm or Node.js errors.
  • Logs: runtime output from your app streams there, including any startup errors.
  • Confirm the app binds to the port in $PORT. Primcloud sets this env var on the web formation, and the Express sample reads it via process.env.PORT.

Where to go next#