How to Integrate Open-SEO into an Existing Project: A Complete Developer Guide

Integrating Open-SEO into an existing project requires deploying it as a standalone Cloudflare Worker and calling its REST endpoints from your application using JWT authentication, without modifying your existing codebase.

Open-SEO is a full-stack SEO service built on Cloudflare Workers and TanStack Server Functions that exposes HTTP-based endpoints for projects, keywords, rank tracking, and Lighthouse audits. Because it runs as an isolated backend service, you can integrate it into any existing stack—whether React, Next.js, Node.js, or elsewhere—by simply making authenticated HTTP requests. This guide walks you through the exact steps to deploy the worker, configure authentication, and call the API using the source files from the every-app/open-seo repository.

Architecture Overview

Open-SEO operates as a separate microservice rather than an importable library. Your application never imports the Open-SEO source code directly; instead, you deploy the worker and communicate with it via HTTP.

The architecture relies on three core components:

• Cloudflare Worker entry point (src/server.ts): Boots the TanStack Server-Function router and mounts the API under /api/*
• Authentication middleware (src/middleware/ensureUser.ts): Validates JWT tokens on every request
• Server functions (src/serverFunctions/*.ts): Handle specific domains like projects, keywords, rank-tracking, and lighthouse audits

When a request hits your deployed worker (e.g., https://your-worker.cloudflareworkers.com/api/projects), the router defined in src/routeTree.gen.ts directs it to the appropriate handler. The ensureUser.ts middleware first verifies the JWT in the Authorization header before allowing access to any endpoint.

Deployment Options

You must deploy the Open-SEO worker before your application can consume its services. Choose between local development for testing or a production Cloudflare Worker deployment.

Local Development

Run the worker locally using the bundled Vite dev server to test integration before deploying:

# Clone the repository

git clone https://github.com/every-app/open-seo.git
cd open-seo

# Install dependencies (pnpm recommended)

pnpm install

# Start the dev server (exposes API at http://localhost:5173)

pnpm dev

The Vite configuration (vite.config.ts) automatically bundles the worker and serves all endpoints at http://localhost:5173/api/*.

Cloudflare Worker Production

For production, deploy the worker to Cloudflare's edge network. The src/server.ts file initializes the TanStack router and wires it to the Cloudflare request lifecycle, making it compatible with Cloudflare Workers' runtime environment.

Authentication Setup

Open-SEO uses JWT-based authentication to secure all endpoints. You must generate tokens signed with the secret defined in your environment variables.

First, copy the environment template and set your secret:

cp .env.example .env

# Edit .env and set OPEN_SEO_JWT_SECRET

Generate a JWT for your client using any standard JWT library. The token must include a sub (user ID) and can optionally include user metadata:

import jwt from 'jsonwebtoken';

const token = jwt.sign(
  { sub: 'user-123', email: 'user@example.com' },
  process.env.OPEN_SEO_JWT_SECRET,
  { expiresIn: '1h' }
);

The src/middleware/ensureUser.ts file handles verification on the server side. It extracts the token from the Authorization: Bearer <token> header, validates it using the utilities in src/lib/auth-*.ts, and injects the user object into the request context (ctx).

Making API Calls from Your Application

Once the worker is deployed and you have a JWT, integrate Open-SEO by making standard HTTP requests from your existing codebase. No additional dependencies or SDKs are required.

Fetching Projects

Call the /api/projects endpoint to retrieve or manage SEO projects:

async function fetchProjects() {
  const res = await fetch('https://my-open-seo-worker.cloudflareworkers.com/api/projects', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${YOUR_JWT}`,
      'Content-Type': 'application/json',
    },
  });

  if (!res.ok) throw new Error('Failed to load projects');
  return await res.json(); // Returns array of project objects
}

This endpoint is handled by src/serverFunctions/projects.ts.

Tracking Keywords

To add keyword tracking, POST to the /api/keyword-tracking endpoint (handled by src/serverFunctions/keywords.ts):

async function trackKeyword(keyword, url) {
  const res = await fetch('https://my-open-seo-worker.cloudflareworkers.com/api/keyword-tracking', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${YOUR_JWT}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ keyword, url }),
  });

  if (!res.ok) throw new Error('Failed to track keyword');
  return await res.json();
}

Running Lighthouse Audits

Trigger performance audits via the /api/lighthouse endpoint defined in src/serverFunctions/lighthouse.ts:

async function runLighthouseAudit(targetUrl) {
  const res = await fetch('https://my-open-seo-worker.cloudflareworkers.com/api/lighthouse', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${YOUR_JWT}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: targetUrl }),
  });

  const report = await res.json();
  return report; // Returns full Lighthouse JSON report
}

For rank tracking data, use the /api/rank-tracking endpoint implemented in src/serverFunctions/rank-tracking.ts, passing the keyword and URL pair as query parameters or body data depending on the specific function signature.

Key Integration Files

When customizing or debugging your integration, reference these critical files in the every-app/open-seo repository:

• src/server.ts: Entry point that boots the Cloudflare Worker and attaches the TanStack router
• src/routeTree.gen.ts: Auto-generated route tree mapping /api/* paths to server functions
• src/middleware/ensureUser.ts: JWT validation middleware that protects all routes
• src/serverFunctions/projects.ts: Project CRUD operations
• src/serverFunctions/keywords.ts: Keyword research and tracking logic
• src/serverFunctions/rank-tracking.ts: SERP position tracking
• src/serverFunctions/lighthouse.ts: Chrome Lighthouse integration
• src/lib/auth-*.ts: Core JWT signing and verification utilities

Summary

Integrating Open-SEO into an existing project follows a service-oriented pattern that keeps your codebase decoupled:

• Deploy the Open-SEO worker locally with pnpm dev or to Cloudflare's edge network
• Configure OPEN_SEO_JWT_SECRET in your environment and generate signed tokens for users
• Call REST endpoints (/api/projects, /api/keywords, /api/rank-tracking, /api/lighthouse) from your existing application using standard fetch requests
• Include the JWT in the Authorization: Bearer header for every request, as enforced by src/middleware/ensureUser.ts

This approach allows any frontend or backend stack to leverage Open-SEO's capabilities without architectural changes.

Frequently Asked Questions

Do I need to rewrite my existing application to use Open-SEO?

No. Open-SEO is designed as a standalone microservice that communicates via HTTP. You can keep your existing React, Next.js, Vue, or Node.js application unchanged. Simply add HTTP client code (fetch or axios) to call the Open-SEO endpoints with a JWT token. Your application treats it like any other third-party API.

What authentication method does Open-SEO use?

Open-SEO uses JWT (JSON Web Token) authentication. The src/middleware/ensureUser.ts middleware validates tokens on every incoming request. You must sign tokens with the OPEN_SEO_JWT_SECRET defined in your .env file, and send them in the Authorization: Bearer <token> header. The token payload should include a sub field representing the user ID.

Can I run Open-SEO locally for development?

Yes. Clone the repository, run pnpm install, and execute pnpm dev to start the Vite development server. This exposes the API at http://localhost:5173/api/* using the configuration in vite.config.ts. This is useful for testing your integration before deploying to Cloudflare's production Workers environment.

Which endpoints are available in the Open-SEO API?

The API exposes endpoints defined in src/serverFunctions/*.ts, including /api/projects for project management, /api/keywords for keyword research, /api/rank-tracking for SERP position monitoring, and /api/lighthouse for performance auditing. The src/routeTree.gen.ts file contains the auto-generated routing table that maps these paths to their respective handlers.

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