Build and deployFrameworks
Frameworks and workloads
Which frameworks Orbits detects, the commands it uses for each, and how each kind of project runs, from static sites to Node servers, workers and containers.
Orbits reads your repository's package.json, lock file and a few config files to work out what the app is and how to build it. What it finds fills in the Configure step, and you can change any of it.
Detected frameworks
Detection checks the dependencies in package.json in this order, so a Next.js app that also lists Vite is still Next.js:
| Framework | Detected by | Default output | Runs as |
|---|---|---|---|
| Next.js | next | .next (out with output: "export") | Server (next start), or static files for a static export |
| Nuxt | nuxt | .output | Server |
| Astro | astro | dist | Static files, or a server when the Node adapter writes one |
| SvelteKit | @sveltejs/kit | .svelte-kit | Server (needs @sveltejs/adapter-node) |
| Remix | any @remix-run/ package | build | Server |
| React Router | @react-router/dev | Server | |
| SolidStart | @solidjs/start | Server | |
| TanStack Start | @tanstack/react-start | Server | |
| Gatsby | gatsby | public | Static files |
| Create React App | react-scripts | build | Static files |
| Vite | vite | dist | Static files |
| Node.js | express, fastify, koa, hono or @nestjs/core, or a start script | Server | |
| Dolph.js | @dolphjs/dolph | Server | |
| HTML | no package.json, an index.html | the root | Static files |
Elysia isn't detected from the repository, but you can pick it as the framework on the Configure step. Anything else with a package.json and no start script is built and served as a static site.
Detection also reports the Node.js version the repository asks for, from engines.node in package.json, or from .nvmrc or .node-version. Check that the project's Node.js version setting matches it (see Node.js versions).
Install and build commands
The package manager comes from the lock file, or from the packageManager field when there is none:
| Lock file | Install | Build |
|---|---|---|
pnpm-lock.yaml | pnpm install --frozen-lockfile | pnpm build |
yarn.lock | yarn install --frozen-lockfile (yarn install --immutable on Yarn 2 and later) | yarn build |
bun.lock | bun install --frozen-lockfile | bun run build |
bun.lockb | bun install | bun run build |
package-lock.json | npm ci | npm run build |
| none | npm install | npm run build |
The build command runs your build script, so it's only set when package.json has one. A Next.js app with no build script runs next build. A static site with no build script is served as it is, with no install. In a monorepo, the lock file and packageManager field are looked for in the app's directory and every directory above it up to the repository root.
Bun can install and build any project. A server app whose start command uses Bun also runs with Bun; otherwise apps run on Node.js.
Workloads
Each project has a workload, the way it runs. It's chosen when the project is created and can't change afterwards.
| Workload | What it is | How Orbits runs it |
|---|---|---|
static | Files: HTML, CSS, JavaScript, images | Served as they are from the output directory. Unknown paths answer 404, unless the SPA fallback is on, in which case they answer with index.html. |
function | A server-rendered framework | Runs the framework's server, the same way as app. Pro only. |
app | A long-running Node.js (or Bun) server | Started with its start command, listening on port 3000 unless the project sets another port. |
worker | A command with no web traffic | Runs its command, continuously or on a cron schedule. |
container | Your own image | Built from the repository's Dockerfile, or pulled from a prebuilt image, and run on the port you set. |
When you don't choose one, Orbits picks it from the framework: Next.js, SvelteKit, Nuxt, Remix, React Router, SolidStart and TanStack Start get function; Node.js, Elysia and Dolph.js get app; everything else gets static. The web app's Configure step doesn't ask: it uses this default. To create a worker or container project, set the workload when you create it through the API.
Server apps
For a server app, Orbits finds the start command in this order:
- the start command the project sets;
- the server a framework's build wrote:
.output/server/index.mjs(Nuxt, SolidStart, TanStack Start),dist/server/entry.mjs(Astro's Node adapter),build/index.js(SvelteKit's Node adapter); npm run start, whenpackage.jsonhas astartscript.
If none applies, the build fails at Uploading and says to add a start script. A SvelteKit app needs @sveltejs/adapter-node, so the build has a server to run.
The app is started with NODE_ENV=production and PORT, HOST=0.0.0.0 and HOSTNAME=0.0.0.0 set, which are what Next.js, Nitro, SvelteKit, Astro and Express listen on by convention. Listen on PORT.
Two cases change how a project runs whatever its workload says:
- A Next.js app built with
output: "export"is served as a static site fromout, becausenext startcan't serve a static export. - An Astro build that writes a server (
dist/server/entry.mjs) runs on Node.
Workers
A worker runs the command the project sets, and needs one: a worker without a command fails at Installing. With a schedule, it's a cron expression read in UTC. Workers run for production only; a preview of a worker is started, checked and stopped.
Containers
A container project is built from its Dockerfile (the path is a project setting) or runs a prebuilt image you name, but not both. It needs the port it listens on, or the build fails. Your image runs as whatever user it sets.
Node.js versions
Builds and apps use Node.js 22 unless the project asks for another. Node.js 18, 20, 22 and 24 are available. Pick 18, 20 or 22 with Node.js version in the project's settings, or set node_version (such as 24.x) through the API. A version Orbits doesn't have builds on Node.js 22.
Not available yet
- WebSockets: requests reach your app as plain HTTP, without the upgrade to a WebSocket.
- Apps that sleep when idle: every app stays running, on Free and on Pro.
- Creating a project from a template.
For the build settings themselves, see build settings.