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

> Integrate Open-SEO into your existing project by deploying it as a Cloudflare Worker. Learn how to call REST endpoints with JWT authentication without codebase changes. Get the complete developer guide.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/every-app/open-seo/blob/main/src/server.ts)): Boots the TanStack Server-Function router and mounts the API under `/api/*`
- **Authentication middleware** ([`src/middleware/ensureUser.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts) directs it to the appropriate handler. The [`ensureUser.ts`](https://github.com/every-app/open-seo/blob/main/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:

```bash

# 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```bash
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:

```javascript
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`](https://github.com/every-app/open-seo/blob/main/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:

```javascript
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`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/projects.ts).

### Tracking Keywords

To add keyword tracking, POST to the `/api/keyword-tracking` endpoint (handled by [`src/serverFunctions/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/keywords.ts)):

```javascript
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`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/lighthouse.ts):

```javascript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server.ts)**: Entry point that boots the Cloudflare Worker and attaches the TanStack router
- **[`src/routeTree.gen.ts`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts)**: Auto-generated route tree mapping `/api/*` paths to server functions
- **[`src/middleware/ensureUser.ts`](https://github.com/every-app/open-seo/blob/main/src/middleware/ensureUser.ts)**: JWT validation middleware that protects all routes
- **[`src/serverFunctions/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/projects.ts)**: Project CRUD operations
- **[`src/serverFunctions/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/keywords.ts)**: Keyword research and tracking logic
- **[`src/serverFunctions/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/rank-tracking.ts)**: SERP position tracking
- **[`src/serverFunctions/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts) file contains the auto-generated routing table that maps these paths to their respective handlers.