Deploying Full-Stack Apps: Next.js and Hono

Most things people share from HQ are simple pages: a report, a dashboard, a deck. Those deploy with no setup. A full-stack app is different. It runs its own server code, for example to save form submissions, call other services, or show data that changes.

HQ Deploy supports two ways to build a full-stack app:

• Next.js 15
• Hono 4

If you're starting a new app that needs server code, build it with one of these.

Deploying your app#

From an HQ session, ask HQ to "deploy this," or type /deploy, from your app's folder. HQ works out what kind of project it is, builds it, shows you a preview on your computer, and publishes it to a link like https://your-app.indigo-hq.com.

If you'd rather deploy from your own terminal or a build pipeline, use the hq-deploy command-line tool. See Deploying Your Own Web App.

Two rules for apps that run a server#

Apps that run their own server have two requirements. Missing either one fails the deploy:

1. Answer health checks. Your app must respond to GET /health with a 200 status. HQ uses this to check that a new version is running.
2. Listen on the right port. Your server must listen on the port in the PORT environment variable, which is 3000.

A bad deploy never takes your site down. The old version keeps running until the new one passes its health check. If the new version doesn't come up within 5 minutes, the deploy is marked failed and the old version keeps serving. More detail in Deploying Your Own Web App.

Passwords and keys your app needs#

Never put passwords or API keys in your code. Store them in your company's vault, and HQ gives your app access to them when it runs. See the Secrets Guide.

If your app uses stored secrets, HQ won't publish it as a public link without checking with you first. A public app that can use your company's keys could be used by anyone who finds it. Add access control (a password, company-only, or specific people) or confirm you understand the risk.

Other kinds of projects#

• Static sites (plain HTML, Vite, Astro, and Next.js sites with no server code) deploy with no extra setup.
• A project with an api/ folder at the top level that isn't built with Next.js or Hono may not deploy yet. If you're building something new, use Next.js 15 or Hono 4.

Common questions#

If you get stuck#

See Deploying Your Own Web App for the command-line details, or report it with /hq-bug. It packages the details for the team automatically.