Building for Production

This guide covers building and deploying your Cobalt application for production.

Build Command

Build your application with:

bunx cobalt build

This command bundles the server-side code into a single cobalt.server.js file. It is being saved in the ./dist directory.

Start Command

Start the production server:

bunx cobalt start

The server runs on port 4000 by default.

You can use environment variables to change the port or use the -p flag.

PORT=4000 bunx cobalt start
COBALT_PORT=4000 bunx cobalt start # COBALT_PORT takes precedence over PORT

or

bunx cobalt start -p 4000

Build Output

After building, you'll have:

dist/
├── cobalt.server.js   # Bundled server
└── cobalt.server.js.map # Source map for the bundled server

Deployment

The build output is currently optimized for Bun.

Therefore you'll need to use an environment with the Bun runtime installed.

Having bun installed, you can easily start the server with:

bunx cobalt start

or

bunx cobalt start -p 4000

Why use cobalt start instead of bun run cobalt.server.js?

cobalt start is a wrapper around bun run cobalt.server.js that adds some additional features:

• It looks for cobalt.server.js in the dist directory or the current directory.
• It initializes Cobalt Auth if it is used in the project.

Next Steps

• Docker — Containerized deployment
• Cobalt Auth — Production auth setup
• Context Factory — Production context configuration