# Deploy a folder

> Send a Next.js app's folder to production with npx extraorbital deploy, follow the build, read its errors, roll back and read production's logs.

<Callout title="In brief">

- `npx extraorbital deploy` sends this folder to production and ends with its URL: `✓ Production: https://shop.extraorbital-apps.com (v12)`.
- Only the files ExtraOrbital does not have yet are uploaded. `.gitignore` and `.vercelignore` apply; `node_modules`, `.next`, `.git`, `.env*` and `.extraorbital*` never go.
- Production gets resources of its own (slug `prod`), never your local `.env`. `deploy --check` lists the variables it would lack.
- A failed build exits 1 with its errors by step, the first with its file and line. `extraorbital logs --prod --source build` has the whole log.
- `extraorbital deployments` lists the versions; `extraorbital rollback` serves the one before, without a build.

</Callout>

Production runs on ExtraOrbital Deploy, on Vercel: one Vercel project per ExtraOrbital project, a version history and rollback, and a host of its own, `<slug>.extraorbital-apps.com`. The CLI deploys production only. Previews (a live copy you edit with an agent) are made from the [MCP server](/docs/mcp).

## Deploy

From the app's folder:

```sh
npx extraorbital deploy
```

```text
→ Deploying . to shop · 132 files, 2.4 MB · 18 left out by the ignore rules
  3 to upload (120 KB), 129 already on ExtraOrbital
  v12: building on Vercel…
  │ Running "npm run build"
  │ ✓ Compiled successfully
✓ Production: https://shop.extraorbital-apps.com (v12)
  Primary domain     https://shop.com
```

Another folder: `npx extraorbital deploy ./web`. A message for the version: `-m "New pricing page"`.

| Step | What happens |
| --- | --- |
| 1. The files | The folder is read with its ignore rules, checked against the limits, and summed up. |
| 2. The project | The one `.extraorbital.json` names. An unlinked folder is linked first, as [`link`](/docs/cli#extraorbital-link) does: chosen at a terminal, or named after the git remote or the folder. |
| 3. The upload | Deploy answers which files it does not have (by SHA-1); only those are sent. Unchanged files cost nothing. |
| 4. The version | Production's resources and variables are set, then Vercel builds. The build log streams while it runs. |
| 5. The answer | The production URL, the ExtraOrbital host and the primary domain. Or the errors, and exit code 1. |

## What is uploaded

| Rule | |
| --- | --- |
| `.gitignore` | The folder's, the ones under it, and the ones above it up to the repository's root, as git reads them. |
| `.vercelignore` | At the folder's root, after them. |
| Never | `node_modules`, `.next`, `.git`, `.vercel`, `.turbo`, `.env*` files, `.extraorbital*`. Symbolic links are skipped. |
| Limits | 4 MB per file, 100 MB and 10,000 files per folder. A larger folder is refused before anything is sent, naming the heaviest parts. Serve large files from [storage](/docs/resources/s3). |

`--dry-run` lists the files and their sizes, and sends nothing.

## Production's variables

A local `.env` is never uploaded. Production has its own:

- **Resources.** A permanent resource with the slug `prod` for each service the project uses: the ones `extraorbital add` made for it. A service is never guessed from a variable's name.
- **A sign-in secret.** An app that uses better-auth gets a `BETTER_AUTH_SECRET` of its own, minted once and kept.
- **Logs.** Its server and browser logs reach ExtraOrbital (`extraorbital logs --prod`).

The variables the app reads, from `.env.example` and from `process.env.X` in its code, that production has no value for are listed after the deploy, with the service that provides each one:

```text
! Production has no value for 1 variable the app reads:
  OPENAI_API_KEY (lib/ai.ts) · extraorbital add openai, then deploy again
```

`npx extraorbital deploy --check` lists them before deploying, deploys nothing, and exits 1 if there are any.

## Frameworks

Next.js only, for now: the folder needs a `package.json` with a `next` dependency. Production is a Next.js project on Vercel, and the log client added to every deployment is Next.js code. Anything else is refused with a message, before anything is uploaded.

## When the build fails

```text
✗ v13 failed: 2 errors

  First error  app/page.tsx:3:7  Type 'string' is not assignable to type 'number'.

  Type errors (1)
    app/page.tsx:3:7  Type 'string' is not assignable to type 'number'.
  Lint (1)
    app/lib/x.ts:12:5  'x' is assigned a value but never used. (@typescript-eslint/no-unused-vars)

  Full build log: npx extraorbital logs --prod --source build v13
  Production still serves the version before it.
```

The errors are grouped by step: install, build, type errors, lint, then the deployment itself. The command exits 1, and production keeps serving the version before.

## For agents and scripts

```sh
npx extraorbital deploy --json
npx extraorbital deploy --json --no-wait
```

`--json` prints one object on stdout, progress on stderr:

```json
{
  "ok": true,
  "project": "shop",
  "version": 12,
  "status": "ready",
  "url": "https://shop.extraorbital-apps.com",
  "host": "https://shop.extraorbital-apps.com",
  "primaryDomain": null,
  "files": 132,
  "bytes": 2516582,
  "uploaded": { "files": 3, "bytes": 122880 },
  "errors": [],
  "env": { "services": ["mongo"], "missing": [] }
}
```

On a failure, `ok` is `false`, `errors` holds `{kind, file, line, column, message, rule}` items, and the exit code is 1. `--no-wait` returns once the deployment is created; follow it with `extraorbital deployments`.

A machine still in its sandbox can't deploy: run `npx extraorbital login` once.

## Versions, rollback, logs

```sh
npx extraorbital deployments                           # every version; ● is production
npx extraorbital rollback                              # the version before the current one
npx extraorbital rollback v3                           # a given version (or forward to a newer one)
npx extraorbital logs --prod                           # server and browser logs of production
npx extraorbital logs --prod --source build            # the newest build's output
npx extraorbital logs --prod --level error --since 1h -f
```

A rollback is instant: the version is already built. See the [CLI reference](/docs/cli#extraorbital-logs) for every flag.

---

More for agents: [Sitemap](https://extraorbital.dev/sitemap.md) · [llms.txt](https://extraorbital.dev/llms.txt) · [agents.md](https://extraorbital.dev/agents.md)
