Build your application
Choose a runtime version
Cloud can run your JavaScript application on Node.js, Bun, or Deno. There’s nothing to configure here, since Cloud detects the right runtime from the files in your repository:
You may choose your Node.js, Bun, or Deno version from the Runtime section of your environment’s General Settings page. After changing it, redeploy your environment so the new version takes effect. If you’re using Node.js, it’s also a good idea to keep the
engines field in your package.json compatible with the version you select. You can find the supported versions in the Runtimes documentation.
Install and compile during the build
By default, Cloud pre-fills a build command that installs your application’s dependencies:Run your application
Set the start command
Cloud pre-fills a start command based on thestart script or main entry in your package.json, such as node server.js. If neither of these points to a file, the start command falls back to npm start, bun run start, or deno task start, depending on your runtime.
Your start command should run your compiled output directly with node, such as node dist/server.js. When you keep compilation in your build commands, your application starts quickly when a new instance boots or when your environment wakes up after scaling to zero, since there’s nothing left to compile. Tools such as nodemon, tsx watch, and ts-node are great for development, but don’t use them to run your application in production.
Listen on the right port
Cloud routes traffic to your application on the port set by thePORT environment variable. This is 3000 by default, or the port you chose when creating your application. Your application should read this value and leave the host out of its listen call:
0.0.0.0, or a loopback-only host such as 127.0.0.1 or localhost, Cloud won’t be able to reach your application.
If you are using Hono on Node.js, you will start your server through @hono/node-server:
Memory and workers
Cloud sets the JavaScript heap limit for your Node.js or Deno application based on your instance’s memory. When your application runs out of heap, it exits with an out-of-memory error in your logs, rather than the instance killing it with no error at all. If your application runs several processes, Cloud gives each process an equal share of the memory. If your application forks its own workers, setWEB_CONCURRENCY to the number of workers so Cloud can divide the memory between them.
To set your own heap size, add --max-old-space-size to NODE_OPTIONS for Node.js or to DENO_V8_FLAGS for Deno. Cloud doesn’t override a heap size you set. Deno expects its V8 flags separated by commas:
deno serve --parallel, Cloud sets DENO_JOBS to the number of whole CPU cores on your instance. Deno reads DENO_JOBS to decide how many workers to start. To run a different number of workers, set DENO_JOBS in your environment variables.
Shut down gracefully
When an instance stops, whether during a deployment or while scaling down, Cloud sends aSIGTERM signal to your process. To avoid cutting off requests that are still in progress, your application should handle this signal and wait for those requests to finish before exiting:
server.close stops accepting new connections and invokes its callback once all of the active connections have ended. The fallback timer makes sure your process exits even if a connection lingers. Keep this timer shorter than your environment’s graceful shutdown timeout so the rest of the instance has time to stop cleanly. Once that timeout passes, Cloud terminates any process that is still running.
Running behind the proxy
Cloud handles TLS for you before forwarding requests to your application, so your server only needs to speak plain HTTP. Cloud’s proxy passes the original request scheme in theX-Forwarded-Proto header and the client’s address chain in the X-Forwarded-For header.
Before relying on these headers to determine the request scheme or client IP address, you should configure your framework’s trusted proxy settings. In Express, you may tell your application to trust the proxy running alongside it, which allows req.protocol and req.secure to reflect the original scheme:
Environment variables
Cloud sets your environment variables directly on your application’s process, so you can read them fromprocess.env just like you normally would. There’s no need for a loader such as dotenv. Your build commands receive the same variables through a .env file in the build context.
In addition to your own variables, Cloud automatically sets NODE_ENV=production and APP_URL, which contains your application’s URL, on every deployment. To add your own values, see the environment variables documentation.
A custom variable may refer to another variable with ${NAME}, such as CALLBACK_URL="${APP_URL}/auth/callback". Cloud resolves the reference before it sets the variable, so process.env.CALLBACK_URL holds the final URL. See referencing other variables for which variables you can reference.
Databases and storage
Databases and caches
When you attach a database or cache from the infrastructure canvas, Cloud injects aDATABASE_URL (postgresql://... or mysql://...) or REDIS_URL (rediss://...) variable into your application’s environment. Most popular libraries accept these URLs directly, so connecting usually takes just a line or two of code.
For Postgres, you may pass the connection URL straight to node-postgres:
rediss:// scheme:
DATABASE_URL as well.
Run migrations
Database migrations belong in your environment’s deploy commands. Cloud runs these commands just before your new deployment goes live. If one of them fails, Cloud cancels the rollout. Keep in mind that deploy commands must finish within 15 minutes, and any changes they make to the filesystem will not be kept. For example, if you are using Prisma, your deploy command might look like this:Object storage
When you attach a bucket as your environment’s default disk, Cloud injects theAWS_BUCKET, AWS_ENDPOINT_URL, AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY variables. When creating your S3 client with the AWS SDK for JavaScript, be sure to pass the endpoint explicitly:

