Open-SEO Package.json Scripts: Complete Development Workflow Guide

The root package.json of the every-app/open-seo repository defines over 30 npm scripts that automate development, testing, database migrations, and Cloudflare Workers deployment. These scripts form a comprehensive CLI interface for managing the Vite-based SEO platform, covering everything from local hot-reloading to production sourcemap uploads.

The package.json file serves as the central command hub for open-seo. Located at the repository root, it orchestrates a modern TypeScript toolchain including Vite for bundling, Drizzle Kit for database management, and Wrangler for edge deployment. Below is the complete breakdown of essential scripts developers use daily.

Development Server Scripts

Local development relies on Vite-powered scripts that handle hot-reloading and agent debugging.

dev starts the standard Vite development server (line 9). This is the primary command for daily feature work, providing fast HMR (Hot Module Replacement) for the React frontend.

dev:agents and dev:agents:force run Vite while capturing logs to .logs/dev-server.log (lines 11‑12). Use these when debugging background agents. The :force variant ensures a fresh start by clearing cached state.

dev:clear-chat clears the Cloudflare Workers state for the onboarding chat agent (line 10). Run this when testing the AI chat flow from a clean slate.

Build and Deployment Pipeline

Production workflows follow a strict sequence from type-checking to edge deployment.

build executes tsc --noEmit followed by vite build (line 13). This produces a minified, production-ready bundle while catching TypeScript errors before bundling begins.

preview first runs the build, then serves the production bundle locally on port 3001 (line 16). Use this to verify the final asset output before deploying.

deploy triggers the full release sequence: production database migration via Wrangler, asset building, and Cloudflare Workers publication (line 17). This is the canonical command for shipping to production.

sourcemaps:upload generates a production build with sourcemaps enabled, injects them into PostHog, and uploads them for error tracing (line 18). Critical for monitoring production exceptions in the analytics dashboard.

Code Quality and Maintenance

Strict linting and formatting standards are enforced through automated scripts.

lint runs oxlint in type-aware mode to catch bugs and style violations (line 14). lint:fix automatically resolves auto-fixable issues (line 15).

format:check and format:write invoke prettier to verify or correct code formatting across the codebase (lines 21‑22).

types:check performs a standalone TypeScript type-check via tsc --noEmit (line 20). This complements the build script by allowing type validation without emitting files.

knip detects unused or duplicate dependencies (line 27). Run this periodically to keep the bundle size lean and node_modules clean.

ci:check composes all quality gates into a single command: prettier, knip, tsc, and oxlint (line 40). This is the script used in CI pipelines to validate pull requests.

Database and Authentication Management

Drizzle ORM and Better Auth integration is handled through specialized database scripts.

db:generate invokes drizzle-kit to create migration files based on schema changes (line 24).

db:migrate:local applies D1 database migrations against your local SQLite instance (line 25), while db:migrate:prod targets the remote production D1 database (line 26).

auth:generate executes the better-auth CLI to generate authentication schemas (line 23). The output is written to src/db/better-auth-schema.ts, defining tables for sessions, users, and OAuth accounts.

cf-typegen generates TypeScript bindings for Cloudflare Workers environment variables and bindings (line 19). Run this after modifying wrangler.toml to keep type definitions synchronized.

Testing Suite

Comprehensive testing is split between unit/integration tests with Vitest and E2E tests with Playwright.

test launches vitest in watch mode for interactive development (line 29). test:watch provides an explicit watch configuration (line 30), while test:ci runs tests with a CI-friendly reporter and exits on completion (line 31).

test:e2e executes Playwright end-to-end tests against a running instance (line 32). Additional scripts like test:e2e:seeded and test:e2e:ui provide specialized configurations for seeded databases and headed browser mode (lines 33‑36).

Utility and Billing Scripts

Specialized utilities support billing operations and data management.

billing:backlinks and billing:brand-lookup execute TypeScript scripts via tsx to calculate usage profiles for SEO features (lines 36‑37). These scripts reside in the scripts/ directory, such as scripts/backlinks-cost-profile.ts.

seed:rank-tracking populates the database with demo data for testing the rank-tracking dashboard (line 39).

cleanup:default-projects:d1 removes temporary default projects from the local D1 instance (line 38), useful for resetting development environments.

release:notes generates changelog entries by executing scripts/release-notes.mjs (line 28), automating release documentation based on recent commits.

Practical Usage Examples

Run these commands in the repository root using pnpm, specified as "packageManager": "pnpm@10.30.1" in package.json:

# Standard development with HMR

pnpm run dev

# Debug agents with log capture

pnpm run dev:agents

# Full production build with type-checking

pnpm run build

# Deploy to Cloudflare (includes DB migration)

pnpm run deploy

# Run all CI checks locally before pushing

pnpm run ci:check

# Reset local database and generate new migrations

pnpm run db:migrate:local

Summary

• Development: dev, dev:agents, and dev:clear-chat provide Vite-based local servers with optional logging and state reset.
• Production: build, preview, and deploy handle bundling, verification, and Cloudflare Workers publication.
• Quality: lint, format:write, types:check, knip, and ci:check enforce code standards and dependency hygiene.
• Data: db:* scripts manage D1 migrations, while auth:generate updates Better Auth schemas in src/db/better-auth-schema.ts.
• Testing: test* runs Vitest suites; test:e2e* executes Playwright against the full stack.
• Observability: sourcemaps:upload integrates with PostHog for production error tracking.

Frequently Asked Questions

How do I start the development server for open-seo?

Run pnpm run dev to start the Vite development server with hot module replacement. For debugging background agents that log to files, use pnpm run dev:agents instead, which captures output to .logs/dev-server.log.

What script deploys the application to production?

Execute pnpm run deploy to trigger the full deployment pipeline. This script first applies pending database migrations to the remote D1 database using Wrangler, then builds the production bundle and publishes the Cloudflare Worker to the edge network.

How does open-seo handle database schema changes?

Use pnpm run db:generate to create migration files via Drizzle Kit after editing schema definitions. Apply these migrations locally with pnpm run db:migrate:local before using db:migrate:prod to update the production database. The auth:generate script similarly updates authentication tables via src/db/better-auth-schema.ts.

Which script runs the complete CI validation suite?

pnpm run ci:check executes the full validation pipeline including Prettier formatting checks, Knip dependency analysis, TypeScript type-checking (tsc --noEmit), and Oxlint linting. This mirrors the exact checks performed in continuous integration environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}