Files Present in the Root of the Open‑SEO Repository: A Complete Developer Guide

The root directory of the every-app/open-seo repository contains 20+ configuration files, deployment scripts, and entry points including wrangler.jsonc for Cloudflare Workers configuration, Dockerfile.selfhost for containerization, and cli-auth.ts for CLI authentication utilities.

The open-seo codebase is a Cloudflare Workers-based platform for SEO optimization and auditing. Understanding the files present in the root of the open-seo repository is essential for developers configuring deployments, managing database migrations, or extending the application's CLI capabilities as implemented in every-app/open-seo. These top-level files define the project skeleton while the bulk of application logic resides in subdirectories like src/, drizzle/, and docs/.

Project Configuration Files

The open-seo repository root houses several critical configuration files that drive TypeScript compilation and Cloudflare Workers deployment.

TypeScript and Wrangler Configuration

The tsconfig.json file contains the TypeScript compiler options for the entire project, enforcing strict type checking and modern ES module output. Alongside it, wrangler.jsonc and wrangler.audit.jsonc manage Cloudflare Workers deployment settings, defining account IDs, route bindings, and KV namespace configurations.

The worker-configuration.d.ts file provides TypeScript type definitions for the Cloudflare Worker environment, ensuring type safety when accessing bindings like env.DB or env.CACHE within the application code.

Lock Files and Skills Configuration

The repository includes skills-lock.json, which tracks enabled skills and capabilities for the AI agent system, and .npmrc for npm registry configuration and authentication token management during package installation.

Build and Deployment Scripts

Self-hosting and containerization are supported through dedicated Docker configurations located at the repository root.

Docker Self-Hosting Setup

The Dockerfile.selfhost defines a multi-stage build process optimized for production deployments, while docker-entrypoint.sh provides the initialization script that configures runtime environment variables and starts the worker process. These files enable developers to deploy the open-seo platform on any container-compatible infrastructure.

Orchestration Configuration

The compose.yaml file (Docker Compose configuration) simplifies local development and testing by orchestrating the worker container alongside dependent services. This allows developers to spin up the entire stack using docker-compose up without manual configuration.

Runtime Entry Points

Several TypeScript files in the root directory serve as executable entry points for different operational modes.

Worker Initialization

alchemy.run.ts functions as the primary Cloudflare Worker entry point, importing the application logic from src/ and binding it to the Workers runtime. The alchemy.preview-access.run.ts and alchemy.access.ts files handle specialized deployment scenarios, including preview environment access control and staging configurations.

CLI Utilities

The cli-auth.ts script provides a command-line interface for generating and validating authentication tokens required for API access. This utility interacts directly with the Cloudflare Workers authentication system and can be executed via Node.js from the repository root.

Documentation and Repository Metadata

Human-readable documentation at the root level helps onboard new contributors.

The README.md contains the quick-start guide and high-level architecture overview, while CLAUDE.md and AGENTS.md provide specific context for AI-assisted development workflows. The LICENSE file defines the open-source licensing terms governing the codebase.

Hidden Tooling Configuration

Several dotfiles in the root directory configure development tools and enforce code quality standards.

• .gitignore – Specifies untracked files and directories (node_modules, build outputs, environment files)
• .prettierignore – Excludes files from code formatting
• .oxlintrc.json – Configures the Oxlint JavaScript/TypeScript linter rules
• .npmrc – Controls npm behavior and registry settings

These hidden files ensure consistent development environments across different machines and CI/CD pipelines.

Database Migration Configuration

The open-seo repository supports multiple database backends through drizzle-orm, with configuration files located at the root.

The drizzle-prod.config.ts configures migrations for SQLite (production), while drizzle-pg.config.ts handles PostgreSQL-specific settings. These files define the migration folder paths, connection strings, and schema definitions required by the drizzle-kit CLI tool.

Practical Usage Examples

Loading Cloudflare Worker Configuration

When developing worker modules, reference the root configuration files to ensure type safety and configuration consistency:

// src/worker.ts
import type { WorkerConfiguration } from '../worker-configuration.d.ts';
import config from '../wrangler.jsonc' assert { type: 'json' };

export const initWorker = (cfg: WorkerConfiguration) => {
  // Use configuration values such as `account_id`, `workers_dev`, etc.
};

Running CLI Authentication

Execute the authentication utility directly from the repository root:

node cli-auth.ts --token <YOUR_TOKEN>

This command validates the provided token against the Cloudflare Workers authentication endpoints and stores valid credentials for subsequent API calls.

Building the Self-Hosted Docker Image

Deploy the application locally using the provided Docker configuration:

docker build -f Dockerfile.selfhost -t open-seo-selfhost .
docker run -p 8787:8787 open-seo-selfhost

This binds port 8787 (the standard Cloudflare Workers port) to your local machine, allowing you to test the full application stack outside of Cloudflare's hosted infrastructure.

Summary

• The open-seo repository root contains configuration files for TypeScript (tsconfig.json), Cloudflare Workers (wrangler.jsonc), and database migrations (drizzle-prod.config.ts).
• Deployment scripts including Dockerfile.selfhost and docker-entrypoint.sh enable containerized self-hosting outside of Cloudflare's infrastructure.
• Runtime entry points such as alchemy.run.ts and cli-auth.ts provide executable paths for the worker and command-line utilities.
• Hidden configuration files (.gitignore, .oxlintrc.json, .npmrc) maintain code quality and development environment consistency.

Frequently Asked Questions

What is the purpose of wrangler.jsonc in the open-seo repository?

The wrangler.jsonc file configures the Cloudflare Workers deployment environment, specifying account IDs, route patterns, KV namespace bindings, and compatibility dates. This JSONC (JSON with Comments) file is consumed by the Wrangler CLI during deployment and development server operations.

How do I self-host the open-seo application using root-level files?

Use the Dockerfile.selfhost and docker-entrypoint.sh files to build a containerized instance. Run docker build -f Dockerfile.selfhost -t open-seo . followed by docker run -p 8787:8787 open-seo to start the service locally on port 8787, bypassing the need for Cloudflare's hosted Workers platform.

What database configurations are available in the root directory?

The repository includes drizzle-prod.config.ts for SQLite production migrations and drizzle-pg.config.ts for PostgreSQL connections. These files configure the drizzle-orm migration tool, specifying schema paths, connection URLs, and dialect-specific options for each supported database backend.

Are there CLI utilities available in the root directory?

Yes, the cli-auth.ts file provides a command-line authentication utility for generating and validating API tokens. This script can be executed with Node.js to manage access credentials required for interacting with the open-seo platform's protected endpoints.

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