Deploying

Deploying an Overscore dashboard takes a single command. This guide covers the full deployment flow, environment configuration, versioning, and what your deployed URL looks like.

Prerequisites

Before deploying, make sure you have:

  • An Overscore project with at least one dashboard created in the Hub
  • The CLI authenticated on this machine. Run npx @overscore/cli auth login once, approve in the browser, and the credential is saved to ~/.overscore/config. Check it any time with npx @overscore/cli auth.
  • A working React app that builds successfully (e.g., npm run build completes without errors)

Environment Variables

Your dashboard's .env file records which project and dashboard the code belongs to. Both npx create-overscore and npx @overscore/cli open write it for you, so you normally never edit it by hand:

VITE_OVERSCORE_PROJECT_SLUG=your-project-slug
VITE_OVERSCORE_DASHBOARD_SLUG=your-dashboard-slug
VITE_OVERSCORE_API_URL=https://overscore.dev/api

There is no API key to set. npx @overscore/cli dev mints a short-lived key itself and injects it into the dev server, and deploy runs the production build with that key cleared, so no key ever reaches the deployed bundle. A deployed dashboard authorizes its queries through the viewer's own signed-in session instead.

VITE_OVERSCORE_PROJECT_SLUG

The slug of your project, as shown in the Hub URL. For example, if your project URL is overscore.dev/projects/acme-analytics, the slug is acme-analytics.

VITE_OVERSCORE_DASHBOARD_SLUG

The slug of the specific dashboard you're deploying. Each dashboard within a project has its own slug, visible in the Hub.

VITE_OVERSCORE_API_URL

The hub API the CLI and the local dev server talk to. It points at the production hub unless you're working against another environment. A deployed dashboard doesn't use it — the worker proxies its queries.

Deploying with the CLI

Run the deploy command from your project directory:

npx @overscore/cli deploy

Here's what happens when you run this command:

  1. Authenticate — the CLI uses your saved login and confirms you have permission to deploy to this dashboard.

  2. Build — your React app is built using your project's build command (typically vite build). The CLI clears VITE_OVERSCORE_API_KEY for this build so no key is bundled. This produces a dist/ folder with static HTML, CSS, and JavaScript files.

  3. Upload — the built assets are uploaded to Cloudflare R2 object storage. Each deployment is stored as a separate versioned snapshot.

  4. Stage or activate — if deploy review is enabled for an already-live dashboard, viewers keep the current version while the new one gets a private preview. Otherwise the Worker serves the new version directly.

  5. Done — the CLI says whether the version is live or staged and prints the relevant URLs.

$ npx @overscore/cli deploy

  ✓ Authenticated
  ✓ Building dashboard...
  ✓ Uploading assets (14 files, 847 KB)
  ✓ Deployment uploaded

  Staged — not live yet
  Preview: https://acme-analytics.overscore.dev/sales-overview/~preview/
  Put it live: npx @overscore/cli promote

URL Pattern

Every deployed dashboard follows this URL pattern:

https://{project-slug}.overscore.dev/{dashboard-slug}/

For example:

  • Project slug: acme-analytics
  • Dashboard slug: sales-overview
  • URL: https://acme-analytics.overscore.dev/sales-overview/

Anyone with the URL can access the dashboard, provided they're a member of the project and sign in with Google OAuth. Unauthenticated visitors are redirected to the sign-in page.

Versioning

Every deployment creates a new version. Overscore keeps a history of your deployments so you can:

  • View deployment history in the Hub, including timestamps and which version is currently active
  • Go back to an earlier version with the guarded rollback command, or pull its source to continue editing it

Versions are immutable snapshots — deploying a new version never modifies or deletes previous ones.

Going back to an earlier version

List the deploy history, then point the live dashboard at the version you want:

npx @overscore/cli versions
npx @overscore/cli rollback 3

The CLI asks for confirmation before changing the live pointer. You can also pull or download a version's source when you want to continue building from it.

Scaffolding a New Dashboard

If you're starting from scratch, use the scaffolding tool to create a new dashboard project with everything preconfigured:

npx create-overscore

This sets up:

  • A Vite + React project with TypeScript
  • @overscore/client pre-installed
  • OverscoreProvider already wired up in your root component
  • A .env file already filled in with your project slug, dashboard slug, and API URL
  • A sample component using the useQuery hook

From there, build your dashboard with your preferred AI coding tool and deploy when ready.

Redeploying

To update a deployed dashboard, just run the same command again:

npx @overscore/cli deploy

The CLI builds a fresh bundle and uploads it as a new version. Depending on the dashboard's deploy-review setting, it either becomes live or waits as a staged preview for overscore promote. Previous versions remain in history.

Common Issues

"No Overscore credentials found"

The CLI has no saved login on this machine, so it opens the browser login for you. If that doesn't complete, run npx @overscore/cli auth login directly, then npx @overscore/cli auth to confirm it worked. You can review and revoke machines in the Hub under Settings → Devices.

"Build failed"

The CLI runs your project's build command. If it fails, try running npm run build manually to see the full error output. Fix any build errors before deploying.

"Permission denied"

Your account needs to be an owner or editor on the project you're deploying to. Also check that VITE_OVERSCORE_PROJECT_SLUG and VITE_OVERSCORE_DASHBOARD_SLUG in .env point at the dashboard you mean.

Next Steps