How to Integrate Open-SEO into Your Existing Project

You integrate Open-SEO by deploying it as a standalone Cloudflare Worker and calling its REST endpoints via HTTP requests with JWT authentication, without importing any source code into your existing codebase.

Integrating Open-SEO into your existing project requires no refactoring of your current tech stack. The every-app/open-seo repository provides a full‑stack SEO service built on Cloudflare Workers and TanStack Server Functions that exposes HTTP‑based server functions for keyword tracking, rank monitoring, and Lighthouse audits. Your application communicates with the worker through standard REST calls, keeping your codebase completely decoupled from the SEO service implementation.

Architecture Overview

Open-SEO runs as an isolated backend service rather than a traditional library import. The architecture consists of a Cloudflare Worker that boots from src/server.ts and mounts a TanStack Server‑Function router under /api/*.

All request handling lives in src/serverFunctions/*.ts, where each file exports a server function for a specific domain such as projects, keywords, rank tracking, and Lighthouse audits. The routing table is auto‑generated in src/routeTree.gen.ts.

Authentication occurs through JWT verification in src/middleware/ensureUser.ts, which validates the token supplied in the Authorization header before injecting the user context into the request.

Deploying the Open-SEO Worker

To begin integration, you must first run the worker locally or deploy it to Cloudflare.

Clone the repository and install dependencies:

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

# Install dependencies (pnpm recommended)

pnpm install

# Start the development server

pnpm dev

The Vite configuration in vite.config.ts bundles the worker automatically, exposing the API at http://localhost:5173/api/*.

Configure the required environment variables by copying .env.example to .env and setting OPEN_SEO_JWT_SECRET to a secure random string.

Configuring Authentication

The Open-SEO worker uses JWT‑based authentication. You must generate tokens signed with the OPEN_SEO_JWT_SECRET defined in your environment variables.

Generating JWTs

Use any standard JWT library to create tokens for your users:

import jwt from 'jsonwebtoken';

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

Include this token in the Authorization header as a Bearer token when calling the API endpoints.

Calling the API from Your Application

Once the worker is deployed and you have generated a JWT, integrate the endpoints into your existing application using standard fetch requests.

Fetching Projects

To retrieve the list of SEO projects from src/serverFunctions/projects.ts:

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
}

Tracking Keywords

To submit a keyword for rank tracking via the src/serverFunctions/keywords.ts endpoint:

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

To trigger a Lighthouse performance audit through 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 }),
  });

  if (!res.ok) throw new Error('Lighthouse audit failed');
  return await res.json(); // Returns Lighthouse JSON report
}

Key Implementation Files

Understanding the source structure helps diagnose issues and extend functionality:

• src/server.ts – Boots the Cloudflare Worker and wires the TanStack router to the request lifecycle.
• src/routeTree.gen.ts – Auto‑generated route tree mapping /api/* paths to server functions.
• src/middleware/ensureUser.ts – Validates JWT tokens and injects user context into requests.
• src/serverFunctions/projects.ts – Handles CRUD operations for SEO projects.
• src/serverFunctions/keywords.ts – Manages keyword research and tracking logic.
• src/serverFunctions/rank-tracking.ts – Provides ranking data for specific keyword/URL pairs.
• src/serverFunctions/lighthouse.ts – Wraps Chrome Lighthouse and returns JSON reports.
• src/lib/auth-*.ts – Core utilities for JWT creation and verification.
• .env.example – Documents required environment variables including OPEN_SEO_JWT_SECRET.

Summary

• Open-SEO operates as a standalone Cloudflare Worker using TanStack Server Functions, requiring no code changes to your existing application.
• Integration occurs via HTTP REST calls to endpoints like /api/projects, /api/keyword-tracking, and /api/lighthouse.
• Authentication requires JWT tokens signed with your OPEN_SEO_JWT_SECRET and passed in the Authorization header, verified by src/middleware/ensureUser.ts.
• Local development uses Vite via pnpm dev to serve the worker on localhost:5173 before Cloudflare deployment.

Frequently Asked Questions

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

No. Open-SEO is designed as a decoupled service. Your existing application—whether built with React, Next.js, Node, or any other stack—only needs to make HTTP requests to the deployed worker. You do not import any Open-SEO source code into your project.

What authentication method does Open-SEO use?

Open-SEO uses JWT (JSON Web Token) authentication. The src/middleware/ensureUser.ts file verifies tokens signed with the OPEN_SEO_JWT_SECRET environment variable. Your application must generate these tokens server-side and include them as Bearer tokens in the Authorization header of every request.

Can I run Open-SEO locally during development?

Yes. Running pnpm dev starts a local Vite server that bundles the worker using the configuration in vite.config.ts. This exposes the API at http://localhost:5173/api/*, allowing you to test integration before deploying to Cloudflare Workers.

Which endpoints are available in the Open-SEO API?

The worker exposes several TanStack Server Functions under /api/*, including /api/projects for SEO project management, /api/keywords for keyword research, /api/rank-tracking for position monitoring, and /api/lighthouse for performance audits. The complete routing table is auto-generated in src/routeTree.gen.ts.

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