# How to Integrate Open-SEO into Your Existing Project

> Integrate Open-SEO into your project by deploying it as a Cloudflare Worker and calling its REST endpoints. Achieve seamless SEO integration without importing source code.

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

---

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

Authentication occurs through JWT verification in [`src/middleware/ensureUser.ts`](https://github.com/every-app/open-seo/blob/main/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:

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

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

```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
}

```

### Tracking Keywords

To submit a keyword for rank tracking via the [`src/serverFunctions/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/keywords.ts) endpoint:

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

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

  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`](https://github.com/every-app/open-seo/blob/main/src/server.ts)** – Boots the Cloudflare Worker and wires the TanStack router to the request lifecycle.
- **[`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)** – Validates JWT tokens and injects user context into requests.
- **[`src/serverFunctions/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/projects.ts)** – Handles CRUD operations for SEO projects.
- **[`src/serverFunctions/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/keywords.ts)** – Manages keyword research and tracking logic.
- **[`src/serverFunctions/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/rank-tracking.ts)** – Provides ranking data for specific keyword/URL pairs.
- **[`src/serverFunctions/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/routeTree.gen.ts).