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

The main entry point for the Open-SEO application is the fetch export defined in src/server.ts, which Cloudflare Workers invoke to handle every incoming HTTP request. This serverless function acts as the central orchestrator, routing traffic between the TanStack React-Start handler, OAuth flows, and specialized endpoints like MCP servers and agent workflows.

Open-SEO is architected as a Cloudflare Worker, meaning the platform expects a default export containing specific handler functions. According to the every-app/open-seo source code, the fetch method in src/server.ts serves as this primary interface, wrapping the TanStack Start framework with custom runtime logic for database connections and route-specific middleware.

The Cloudflare Worker Entry Point Architecture

Cloudflare Workers look for a default exported object containing lifecycle methods. In src/server.ts, this export exposes both fetch (for HTTP requests) and scheduled (for cron triggers):

// src/server.ts
import { createStartHandler, defaultStreamHandler } from "@tanstack/react-start/server";

const appFetch = createStartHandler(defaultStreamHandler);

export default {
  fetch,               // ← Cloudflare invokes this as the entry point
  async scheduled(event, env, ctx) {
    // Cron job handling logic
  }
};

When a request hits the Worker, Cloudflare automatically executes the fetch function, passing the standard Worker parameters: request, env, and executionCtx. This design pattern ensures that all traffic flows through a single, controllable gateway before reaching application logic.

How the Request Handler Orchestrates Traffic

Inside src/server.ts, the fetch implementation delegates to an internal handleFetch function that performs three critical operations before serving responses:

1. Database Context Initialization: Wraps the request with withPgClient to establish a per-request Postgres client, ensuring database connections are properly scoped and cleaned up.
2. Special Route Handling: Intercepts specific paths including /agents/*, Autumn webhook endpoints, and self-hosted MCP (Model Context Protocol) servers.
3. Application Fallback: Routes standard page requests to the TanStack React-Start handler (appFetch) for server-side rendering and API calls.

The handleFetch implementation effectively creates a middleware layer that preprocesses requests before they reach the React application layer. This architecture allows Open-SEO to handle both traditional web traffic and specialized API endpoints within the same serverless function.

Distinguishing Between Configuration and Entry Point

Developers often confuse src/start.ts with the application entry point because it handles framework configuration. However, src/start.ts merely defines the TanStack Start instance used by the handler, not the Worker entry point itself:

// src/start.ts
import { createCsrfMiddleware, createStart } from "@tanstack/react-start";

const csrfMiddleware = createCsrfMiddleware();

export const startInstance = createStart(() => ({
  requestMiddleware: [csrfMiddleware],
  functionMiddleware: globalServerFunctionMiddleware,
}));

While src/start.ts exports the configuration consumed by createStartHandler, Cloudflare never directly invokes this file. Instead, src/server.ts imports this configuration during initialization, creating a clear separation between framework setup and request handling orchestration.

Extending the Entry Point with Custom Routes

You can extend the main entry point to handle custom API endpoints by modifying the handleFetch logic before it delegates to appFetch. This approach is useful for health checks or lightweight endpoints that don't require the full React-Start initialization:

// Example: Adding a health check endpoint inside handleFetch
if (pathname === "/api/health") {
  return new Response(JSON.stringify({ status: "ok", timestamp: Date.now() }), {
    headers: { "Content-Type": "application/json" },
    status: 200,
  });
}

For testing purposes, you can manually invoke the entry point using standard ES module imports:

// Manual invocation for integration testing
import server from "./src/server";

const response = await server.fetch(
  new Request("https://example.com/api/health"), 
  {} as any, 
  {} as any
);

Summary

• The primary entry point for Open-SEO is the fetch export in src/server.ts, invoked automatically by Cloudflare Workers for every HTTP request.
• Request orchestration happens through handleFetch, which initializes Postgres clients, handles agent/MCP routes, and falls back to TanStack React-Start for standard requests.
• Configuration separation exists between src/start.ts (framework setup) and src/server.ts (request handling), with only the latter serving as the Worker entry point.
• Extensibility is built into the architecture, allowing developers to intercept requests before they reach the React application layer for custom API endpoints or authentication logic.

Frequently Asked Questions

What file does Cloudflare Workers use as the entry point for Open-SEO?

Cloudflare Workers use src/server.ts as the entry point, specifically looking for the default exported object containing the fetch function. This is defined by the Cloudflare Workers runtime specification, which automatically invokes this method when HTTP requests arrive at the edge.

How does Open-SEO handle routing for special endpoints like webhooks and MCP servers?

The handleFetch function in src/server.ts checks the request pathname against specific patterns (such as /agents/* or Autumn webhook routes) before falling back to the TanStack React-Start handler. This allows the application to handle specialized server-to-server communication without loading the full React rendering pipeline.

What is the difference between src/server.ts and src/start.ts in the Open-SEO codebase?

src/server.ts is the Cloudflare Worker entry point that exports the fetch handler invoked by the runtime, while src/start.ts configures the TanStack Start framework instance (createStart) with CSRF middleware and server-function middleware. The entry point imports the start configuration, but Cloudflare never directly executes src/start.ts.

Can I add custom API routes without modifying the TanStack React-Start router?

Yes. You can extend the handleFetch function in src/server.ts to intercept specific paths (like /api/health or custom webhooks) and return Response objects directly before the request reaches the appFetch handler. This pattern is ideal for lightweight endpoints that require minimal overhead or need to bypass React-Start's rendering logic entirely.

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