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

> Explore over 30 npm scripts in the root package.json for open-seo. Automate development, testing, migrations, and Cloudflare Workers deployment with this comprehensive CLI.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-06-28

---

**The root [`package.json`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/package.json):

```bash

# 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.