What Is the Main Entry Point for the Open-SEO Project?

The main entry point for the Open-SEO project is src/server.ts, which exports the fetch and scheduled handlers that Cloudflare Workers invokes for every HTTP request and cron-based rank-checking job.

The every-app/open-seo repository is a Cloudflare Workers application built on TanStack React-Start that powers SEO auditing, SERP rank tracking, and AI chat agent routing. Identifying the main entry point for the Open-SEO project is critical for debugging request flows, extending middleware, or customizing worker behavior for custom deployments.

The Primary Entry Point: src/server.ts

Cloudflare Workers requires a single module that exports specific handler functions. In the Open-SEO codebase, src/server.ts serves as this contract point with the Workers runtime.

The file exports two critical handlers:

• fetch: Handles all incoming HTTP requests and routes them to the appropriate sub-system.
• scheduled: Executes cron-triggered background jobs for periodic rank checking.

The Fetch Handler

The fetch export is the primary request processor. According to the source code in src/server.ts, this function wraps the request handling with database connection management and delegates to specialized routers based on the URL pathname.

// src/server.ts (excerpt)
import { createStartHandler, defaultStreamHandler } from "@tanstack/react-start/server";
import { routeAgentRequest } from "agents";
import { resolveUserContextFromHeaders } from "@/middleware/ensure-user/resolve";

const appFetch = createStartHandler(defaultStreamHandler);
const openSeoOAuthProvider = createOpenSeoOAuthProvider(appFetch);

function fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
  // Cloudflare Workers call this function for every incoming request.
  // It delegates to the appropriate sub‑router based on pathname.
  return withPgClient(() => Promise.resolve(handleFetch(request, env, ctx)));
}

Inside handleFetch, the request is routed to:

• The TanStack React-Start handler (appFetch) for server-rendered routes.
• The OAuth provider for authentication flows.
• Self-hosted MCP (Model Context Protocol) endpoints.
• Chat agent routes handled by the routeAgentRequest function.

The Scheduled Handler

The scheduled export handles cron-triggered executions configured in wrangler.toml. This handler triggers the RankCheckWorkflow for periodic SERP position monitoring and the SiteAuditWorkflow for automated SEO auditing. Both workflow classes are defined in src/server/workflows/RankCheckWorkflow.ts and src/server/workflows/SiteAuditWorkflow.ts but are re-exported through src/server.ts to maintain a clean public API for the Worker.

Request Routing and Middleware Initialization

While src/server.ts acts as the runtime entry point, it coordinates with initialization logic defined elsewhere. The actual TanStack React-Start configuration—including CSRF protection middleware and global server-function middleware—resides in src/start.ts.

src/start.ts vs src/server.ts

The distinction between these files is architectural:

• src/start.ts: Contains the createStart call that configures the TanStack React-Start framework, sets up the default stream handler, and attaches global middleware. This file is imported by src/server.ts but is not the Workers entry point.
• src/server.ts: Imports the configured app from src/start.ts and exports the handlers required by the Cloudflare Workers runtime. The wrangler.toml configuration points specifically to this file.

This separation allows the framework initialization to remain isolated from the platform-specific handler exports required by Cloudflare's runtime.

Workflow Exports and Server Functions

Beyond request handling, src/server.ts serves as the aggregation point for background job workflows. The file re-exports:

• SiteAuditWorkflow from src/server/workflows/SiteAuditWorkflow.ts
• RankCheckWorkflow from src/server/workflows/RankCheckWorkflow.ts

These exports enable the Workers runtime to instantiate workflow classes directly when triggered by the scheduled handler or by durable object alarms. Health check endpoints, such as those defined in src/routes/api/health.ts, are accessible through the TanStack router initialized in src/start.ts but are ultimately served through the fetch handler in the entry point.

Summary

• src/server.ts is the main entry point for the Open-SEO project, exporting the fetch and scheduled handlers required by Cloudflare Workers.
• The fetch handler routes HTTP requests to TanStack React-Start, OAuth providers, MCP endpoints, or chat agents based on the request path.
• src/start.ts handles framework initialization and middleware setup but is not the runtime entry point.
• Background workflows for SEO auditing and rank checking are re-exported through src/server.ts for cron-triggered execution.
• The entry point uses withPgClient to wrap requests with PostgreSQL connection management.

Frequently Asked Questions

Is src/start.ts the main entry point for Open-SEO?

No. While src/start.ts initializes the TanStack React-Start framework and configures middleware, the actual Cloudflare Workers entry point is src/server.ts. The Workers runtime loads src/server.ts based on the main field in wrangler.toml, which then imports the configured application from src/start.ts.

What handlers must src/server.ts export for Cloudflare Workers?

The file must export a fetch handler for HTTP requests and a scheduled handler for cron jobs. The fetch function accepts Request, Env, and ExecutionContext parameters, while scheduled handles background execution triggers for workflows like RankCheckWorkflow.

How does the entry point handle database connections?

The fetch handler wraps request processing with withPgClient(), a utility that manages PostgreSQL connection pooling. This ensures each request has access to the database client through the execution context while properly handling connection cleanup.

Can I add custom API routes by modifying the entry point?

While you can modify routing logic in the handleFetch function within src/server.ts, the recommended approach is to add routes through the TanStack React-Start file-based routing system in src/routes/. For example, adding a file to src/routes/api/ automatically registers the endpoint through the appFetch handler without requiring changes to the entry point file.

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