Deploying

Deploying a 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:

  • A 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. Activate — the new version is set as the active deployment. The Cloudflare Worker immediately begins serving the new files.

  5. Done — the CLI prints your live URL. The whole process typically takes 10-30 seconds.

$ npx @overscore/cli deploy

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

  Live at: https://acme-analytics.overscore.dev/sales-overview/

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 by pulling its source and deploying it again

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

Going back to an earlier version

There is no one-click rollback. List the deploy history, pull the version you want, and deploy it:

npx @overscore/cli versions
npx @overscore/cli pull <slug> --version 3
npx @overscore/cli deploy

You can also download the source for a single version from the dashboard's Develop tab in the Hub.

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, uploads it as a new version, and activates it. Previous versions stay available to pull and redeploy.

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