Core Dependencies for the Open-SEO Project: A Complete Technical Guide

The Open-SEO project from every-app relies on a tightly-curated stack including React 19, TanStack Start, Drizzle ORM, Better-Auth, and specialized SEO API clients like DataForSEO, all orchestrated to run natively on Cloudflare Workers.

Open-SEO is a modern, full-stack SEO application built on top of Cloudflare Workers and React. Understanding the core dependencies for the open-seo project is essential for contributors looking to extend functionality or self-host the platform. This guide breaks down the runtime libraries declared in package.json and explains how they interconnect across the codebase.

Frontend and UI Architecture

The presentation layer is built on React 19 (react and react-dom), providing the component model and rendering engine for the client-side dashboard. Routing and server-side rendering are handled by TanStack Start (@tanstack/react-start) and TanStack Router (@tanstack/react-router), which enable declarative routing within the Cloudflare Workers environment.

Styling relies on Tailwind CSS combined with DaisyUI for pre-built component kits, while Lucide-React supplies the iconography. Form handling is managed by @tanstack/react-form, offering type-safe, schema-driven validation for project creation and onboarding flows.

Data Fetching and State Management

Asynchronous data operations are centralized through TanStack Query (@tanstack/react-query and @tanstack/query-core). This cache-first query layer minimizes external API calls when fetching SEO data like SERP results and Google Search Console metrics.

In src/serverFunctions/rank-tracking.ts, the application implements server functions that TanStack Query consumes on the client:

import { useQuery } from '@tanstack/react-query';
import { getRankTracking } from '@/serverFunctions/rank-tracking';

export function RankTracking({ projectId }: { projectId: string }) {
  const { data, isLoading, error } = useQuery(
    ['rankTracking', projectId],
    () => getRankTracking(projectId),
    { staleTime: 5 * 60_000 }
  );

  if (isLoading) return <div>Loading…</div>;
  if (error) return <div>Error loading rank data</div>;

  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Authentication and Security

Session handling and JWT validation are centralized via Better-Auth (better-auth). This library integrates with Cloudflare Access or local self-host mode, storing session tokens in Cloudflare KV (OAUTH_KV). The middleware in src/middleware/ensureUser.ts enforces these authentication checks before allowing access to protected routes.

Database Abstraction Layer

Drizzle-ORM (drizzle-orm) provides a lightweight, type-safe ORM that abstracts both SQLite (via Cloudflare D1) and PostgreSQL (via Cloudflare PG) without schema drift. The provider selection logic resides in src/db/provider.ts:

import { drizzle } from 'drizzle-orm';
import { createClient as createD1Client } from '@/db/d1/client';
import { createClient as createPgClient } from '@/db/pg/client';

const env = process.env.NODE_ENV;
export const db = env === 'production'
  ? drizzle(createPgClient())
  : drizzle(createD1Client());

Schema files are organized under src/db/ and src/db/pg/, allowing the same codebase to operate on either database dialect depending on the deployment target.

SEO API Integrations

The platform interfaces with external SEO services through dedicated client libraries:

• DataForSEO Client (dataforseo-client): Wraps the DataForSEO service for keyword research, rank tracking, and backlink analysis
• ModelContext SDK (@modelcontextprotocol/sdk): Enables integration with the ModelContext API
• OpenRouter Provider (@openrouter/ai-sdk-provider): Powers AI-assisted insights and content generation

These clients are consumed within server functions to automate SEO workflows while maintaining type safety.

Utility and Parsing Libraries

A robust set of utilities handles data transformation and SEO-specific parsing tasks:

• Zod: Runtime validation and schema parsing
• Remeda: Functional programming utilities
• PapaParse (papaparse): CSV parsing for data imports
• Robots-Parser: Parsing robots.txt files during site audits
• Fast-XML-Parser: XML sitemap processing
• Cheerio: Server-side HTML scraping and DOM manipulation

These libraries support the core audit functionality without requiring a browser environment.

Cloudflare-Native Services

As a Workers-first application, Open-SEO leverages several Cloudflare-specific packages:

• @cloudflare/ai-chat: Powers AI-driven chat assistants
• @cloudflare/think: Serverless execution utilities
• @cloudflare/workers-oauth-provider: OAuth flow management native to Workers
• @cloudflare/workers-types: TypeScript definitions for the Workers runtime

Analytics and telemetry are captured via PostHog (posthog-js and posthog-node), respecting privacy while tracking usage patterns and errors.

Summary

• React 19 + TanStack Start provide the rendering and routing foundation on Cloudflare Workers
• Drizzle-ORM enables type-safe database access across both SQLite (D1) and PostgreSQL (PG) backends
• Better-Auth centralizes authentication with Cloudflare Access integration and KV storage
• TanStack Query manages cached data fetching for SEO APIs like DataForSEO and Google Search Console
• Specialized parsers (Cheerio, robots-parser, fast-xml-parser) handle technical SEO audits without browser overhead
• Cloudflare-native libraries optimize AI features and OAuth flows for the edge runtime

Frequently Asked Questions

What database does Open-SEO use in production?

According to the source code in src/db/provider.ts, Open-SEO uses PostgreSQL (via Cloudflare PG) in production environments, while defaulting to SQLite (via Cloudflare D1) in development. The Drizzle-ORM abstraction allows both dialects to share the same schema definitions without code changes.

How does authentication work in self-hosted deployments?

The src/middleware/ensureUser.ts file implements a dual-mode authentication system. When src/shared/selfhost-checks.ts detects a self-hosted environment, Better-Auth operates in local mode without Cloudflare Access. In managed deployments, it validates JWT tokens against Cloudflare Access and stores session data in the OAUTH_KV namespace.

Which external SEO services does Open-SEO integrate with?

The platform integrates with DataForSEO for keyword research and rank tracking, ModelContext for advanced AI context management, and OpenRouter for AI provider aggregation. These clients are declared as core dependencies and consumed through server functions under src/serverFunctions/.

Is TanStack Query required for all data fetching?

While @tanstack/react-query is the primary state management solution for client-side data fetching, server-side rendering in TanStack Start can fetch data directly within route handlers. However, the codebase consistently uses TanStack Query for cache synchronization and stale-while-revalidate patterns when displaying SEO metrics.

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