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
  • An API key generated for your dashboard (found in the Hub under your dashboard's settings)
  • A working React app that builds successfully (e.g., npm run build completes without errors)

Environment Variables

Your dashboard needs three environment variables to connect to Overscore. Create a .env file in your project root:

VITE_OVERSCORE_API_KEY=your-api-key-here
VITE_OVERSCORE_PROJECT_SLUG=your-project-slug
VITE_OVERSCORE_DASHBOARD_SLUG=your-dashboard-slug

VITE_OVERSCORE_API_KEY

The API key authenticates your deployed dashboard's data requests. Generate one in the Hub under your dashboard's settings. This key is safe to include in your frontend build — it only authorizes read access to the queries registered for that specific dashboard.

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.

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 verifies your API key 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). 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
  • Roll back to a previous version instantly from the Hub if a deployment introduces a problem

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

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.example file with the required environment variables
  • 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 remain available for rollback in the Hub.

Common Issues

"API key not found"

Double-check that VITE_OVERSCORE_API_KEY is set in your .env file and that the key matches what's shown in the Hub. If you recently regenerated the key, update your .env file.

"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"

Make sure the API key corresponds to the correct project and dashboard slugs. The key, project slug, and dashboard slug must all match.

Next Steps