# Top-Level Configuration Files in Open-SEO: A Complete Guide to the Repository Root

> Explore Open-SEO's top-level configuration files for pnpm, TypeScript, Cloudflare Workers, and Docker. Master your repository root with this comprehensive guide.

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

---

**The Open-SEO repository contains over 20 top-level configuration files that manage everything from pnpm workspaces and TypeScript compilation to Cloudflare Workers deployment and Docker self-hosting configurations.**

Understanding the top-level configuration files in open-seo is essential for developers looking to contribute, extend, or self-host this SEO optimization platform. These root-level files define the build pipeline, package management strategy, deployment targets, and development environment requirements. Each configuration serves a specific purpose in the monorepo architecture maintained by the every-app organization.

## Package Management and Workspace Configuration

The project uses **pnpm** as its package manager, orchestrated through workspace-specific files at the repository root.

**[`pnpm-workspace.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-workspace.yaml)** defines the monorepo layout, specifying private packages and inter-package linking rules that allow the codebase to share dependencies across multiple modules.

**[`pnpm-lock.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-lock.yaml)** locks exact dependency versions to ensure reproducible installs across different environments and CI pipelines.

**[`package.json`](https://github.com/every-app/open-seo/blob/main/package.json)** serves as the central source of truth for runtime dependencies, npm scripts, and the project version. As implemented in [`src/server/lib/setup-status.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/setup-status.ts), the codebase frequently references this file to expose version information:

```typescript
import { readFileSync } from "fs";
import path from "path";

const pkgPath = path.resolve(__dirname, "..", "..", "package.json");
const { version } = JSON.parse(readFileSync(pkgPath, "utf8"));
console.log(`Open‑SEO version: ${version}`);

```

## TypeScript and Build Tool Configuration

**[`tsconfig.json`](https://github.com/every-app/open-seo/blob/main/tsconfig.json)** governs TypeScript compiler options for the entire monorepo, enforcing strict type checking and module resolution rules across all packages.

**[`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts)** configures the Vite bundler for the front-end application, handling hot module replacement, build optimization, and asset processing.

**[`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts)** sets up the Vitest test runner, defining test inclusion patterns, coverage thresholds, and mocking behaviors for the unit test suite.

## Cloudflare Workers Deployment

The application targets **Cloudflare Workers** as its primary runtime environment.

**`wrangler.jsonc`** contains the Cloudflare Workers configuration, specifying routes, KV namespace bindings, environment variables, and deployment zones.

**[`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts)** provides TypeScript type definitions for the Cloudflare Worker configuration, ensuring type safety when accessing environment bindings in worker code.

**[`vite-plugin-lean-worker-bundle.ts`](https://github.com/every-app/open-seo/blob/main/vite-plugin-lean-worker-bundle.ts)** is a custom Vite plugin that optimizes worker bundle size, reducing cold-start latency for Cloudflare Worker deployments.

## Environment Variables and Secrets

Open-SEO never stores sensitive credentials directly in the repository. Instead, it uses example templates that guide developers on required configuration.

**`.env.example`** acts as the primary template for required environment variables, including API keys and third-party service secrets.

**`.env.production.example`** contains production-specific environment variable templates, tailored for live deployment scenarios.

**`.env.preview.example`** provides configuration templates for preview deployments, allowing safe testing of pull request builds without affecting production data.

## Docker and Containerization

For self-hosting scenarios, the repository includes containerization configurations.

**`Dockerfile.selfhost`** defines the Docker image build process for self-hosted installations, specifying base images, build stages, and runtime commands.

**[`compose.yaml`](https://github.com/every-app/open-seo/blob/main/compose.yaml)** provides a Docker Compose configuration for local multi-container development, orchestrating the application with its dependent services.

**`.dockerignore`** excludes unnecessary files from Docker build contexts, reducing image size and build times by omitting node_modules, local environment files, and development artifacts.

## Code Quality and Linting

**[`.oxlintrc.json`](https://github.com/every-app/open-seo/blob/main/.oxlintrc.json)** configures custom linting rules for Oxlint, enforcing code quality standards and catching potential bugs before they reach production.

**`.prettierignore`** specifies files and directories that Prettier should skip during formatting, typically including generated code, lockfiles, and minified assets.

**`knip.jsonc`** configures the Knip tool for detecting unused code, dead exports, and missing dependencies across the TypeScript codebase.

## CI/CD and Repository Automation

The `.github` directory contains automation configurations that enforce code quality and handle deployments.

**`.github/workflows/*.yml`** defines the complete CI/CD pipeline, including workflows for linting, testing, Docker image builds, and PR preview deployments.

**`.github/CODEOWNERS`** establishes repository code-ownership rules, automatically requesting reviews from specific team members when particular files or directories are modified.

## Utility and Version Control

**`.gitignore`** lists files omitted from version control, including build outputs, environment files, and editor-specific directories.

**[`README.md`](https://github.com/every-app/open-seo/blob/main/README.md)** provides project overview and quick-start instructions, serving as the entry point for new contributors exploring the repository.

## Summary

- **Package management** relies on pnpm via [`pnpm-workspace.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-workspace.yaml) and [`pnpm-lock.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-lock.yaml), with [`package.json`](https://github.com/every-app/open-seo/blob/main/package.json) serving as the version source.
- **TypeScript compilation** is controlled by [`tsconfig.json`](https://github.com/every-app/open-seo/blob/main/tsconfig.json), while **Vite** handles bundling through [`vite.config.ts`](https://github.com/every-app/open-seo/blob/main/vite.config.ts) and testing via [`vitest.config.ts`](https://github.com/every-app/open-seo/blob/main/vitest.config.ts).
- **Cloudflare Workers deployment** requires `wrangler.jsonc` and type definitions in [`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts).
- **Environment configuration** uses `.env.*.example` templates rather than committed secrets.
- **Docker self-hosting** is supported by `Dockerfile.selfhost` and [`compose.yaml`](https://github.com/every-app/open-seo/blob/main/compose.yaml).
- **CI/CD pipelines** are defined in `.github/workflows/*.yml` with review enforcement via `.github/CODEOWNERS`.

## Frequently Asked Questions

### What package manager does Open-SEO use?

Open-SEO uses **pnpm** as its package manager, configured through [`pnpm-workspace.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-workspace.yaml) at the repository root. The [`pnpm-lock.yaml`](https://github.com/every-app/open-seo/blob/main/pnpm-lock.yaml) file ensures reproducible dependency installation across development and production environments.

### How does Open-SEO handle environment variables?

The project uses example template files rather than storing secrets in version control. Developers copy `.env.example`, `.env.production.example`, or `.env.preview.example` to create their local `.env` files, ensuring sensitive API keys and credentials never appear in git history.

### What is the purpose of the wrangler.jsonc file?

The `wrangler.jsonc` file configures **Cloudflare Workers** deployment settings, including route mappings, KV namespace bindings, and environment variable injection. This file is essential for deploying the application to Cloudflare's edge network.

### Where are the CI/CD pipelines defined in the repository?

All continuous integration and deployment configurations reside in `.github/workflows/*.yml`. These YAML files define automated processes for linting with Oxlint, running Vitest tests, building Docker images, and deploying preview environments for pull requests.