Where to Find the Main Configuration Files for Open-SEO: Complete Guide

The main configuration files for Open-SEO are located in the repository root and include wrangler.jsonc for Cloudflare Workers deployment, vite.config.ts for build settings, tsconfig.json for TypeScript, package.json for scripts and bindings, drizzle.config.ts for database configuration, and .env.example for environment variables.

Open-SEO is a Cloudflare-based SEO application that relies on a distributed configuration architecture split across six core files. Understanding where these main configuration files for Open-SEO reside and how they interact is essential for customizing deployments, managing local development, and wiring up Cloudflare platform services like D1, KV, and Durable Objects.

wrangler.jsonc: Cloudflare Workers Deployment

The wrangler.jsonc file in the repository root controls how the application deploys to Cloudflare Workers. This JSON-with-comments file defines the worker name, entry point, and platform bindings.

Key settings include:

• Worker Metadata: name, main (pointing to src/server.ts), and compatibility_date
• Durable Objects: Bindings like ONBOARDING_CHAT for persistent state management
• Workflow Bindings: SITE_AUDIT_WORKFLOW and RANK_CHECK_WORKFLOW for background job processing
• Storage Bindings: KV namespaces, D1 databases, and R2 buckets for data persistence

According to the every-app/open-seo source code, this file tells Cloudflare which worker file to run and what platform resources to inject into the runtime environment.

vite.config.ts: Build and Development Server

The vite.config.ts file configures the Vite bundler and development server, including the Cloudflare Vite plugin that enables Workers-specific features during local development.

The configuration dynamically constructs allowed hosts based on environment variables:

// vite.config.ts – excerpt
const allowedHosts = [
  env.ALLOWED_HOST,
  env.BETTER_AUTH_URL ? new URL(env.BETTER_AUTH_URL).hostname : undefined,
].filter((host): host is string => Boolean(host));

return {
  server: { allowedHosts, port },
  // …
};

This file also imports plugins for TanStack React-Start, React, Tailwind CSS, and optional development tools, making it the central hub for the client-side build pipeline.

tsconfig.json: TypeScript Compiler Options

The tsconfig.json file enforces strict typing across the entire codebase and configures module resolution. Critical settings include:

• Strict Mode: Enabled for type safety throughout the application
• Path Mapping: The @/* alias maps to ./src/*, allowing clean imports like import { utils } from '@/lib/utils'

This configuration ensures consistent TypeScript behavior whether running locally or in the Cloudflare Workers environment.

package.json: Scripts and Cloudflare Bindings

Beyond dependency management, package.json serves two critical configuration purposes in Open-SEO:

1. NPM Scripts: Centralizes commands for development (npm run dev), production builds, database migrations, and Cloudflare deployments

2. Cloudflare Bindings Metadata: The cloudflare.bindings field documents required environment variables including AUTH_MODE and DATAFORSEO_API_KEY

You can run database migrations against the D1 database using the predefined scripts:

# Apply migrations locally (uses getLocalD1Url())

npm run db:migrate:local

# Apply migrations to remote D1 instance

npm run db:migrate:prod

drizzle.config.ts: Database Configuration

The drizzle.config.ts file configures Drizzle-ORM for the SQLite D1 database. Key settings include:

• Dialect: Set to sqlite for D1 compatibility
• Schema Path: Points to the database schema definitions
• Local D1 URL: Handles connection strings for local development databases

This configuration enables the npm run db:generate command to create appropriate migration files based on schema changes.

.env.example: Environment Variables Template

The .env.example file provides a template for local development environment variables. It includes defaults for:

• VITE_SHOW_DEVTOOLS: Toggles development tools in the UI
• ALLOWED_HOST: Configures the Vite dev server host whitelist
• OAuth-related settings for KV storage configuration

Copy this file to .env and customize values for your local development environment.

Accessing Configuration in Application Code

Configuration values defined in these files are accessible at runtime through the environment bindings. For example, the DATAFORSEO_API_KEY declared in wrangler.jsonc bindings becomes available in the worker:

// src/server.ts (simplified)
export default {
  async fetch(request: Request, env: Env) {
    const apiKey = env.DATAFORSEO_API_KEY; // binding declared in wrangler.jsonc
    // …
  },
};

Summary

• wrangler.jsonc controls Cloudflare Workers deployment, Durable Objects, Workflows, and platform bindings
• vite.config.ts manages the Vite build process, dev server ports, and host allowlists
• tsconfig.json enforces strict TypeScript settings and the @/* path alias
• package.json defines scripts and documents Cloudflare environment bindings
• drizzle.config.ts configures the D1 database connection for Drizzle-ORM
• .env.example provides the template for local environment variables

Frequently Asked Questions

What is the difference between wrangler.jsonc and wrangler.toml?

wrangler.jsonc is the JSON-with-comments configuration format used by Open-SEO, offering better readability and trailing comma support compared to TOML. Both formats control the same Cloudflare Workers deployment settings, but wrangler.jsonc allows comments explaining complex binding configurations like Durable Objects and Workflows.

How do I add a new environment variable to Open-SEO?

First, add the variable to the cloudflare.bindings section in package.json for documentation, then declare it in wrangler.jsonc under the vars or binding sections depending on the type. For local development, add it to .env.example and your local .env file. Access it in code via the env parameter in your worker handlers.

Where do I configure the database connection settings?

Database configuration for the D1 SQLite database resides in drizzle.config.ts, which specifies the dialect, schema path, and connection URLs. The actual D1 database binding and ID are configured in wrangler.jsonc under the d1_databases key, allowing the application to access the database at runtime through env.DB_NAME.

How do I change the development server port?

The development server port is configured in vite.config.ts, which reads from environment variables and constructs the server configuration object. Modify the port variable in the Vite configuration or set the appropriate environment variable in your .env file to override the default port.

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