How to Integrate every-app/open-seo into an Existing Next.js Project

You can integrate every-app/open-seo into your existing Next.js application by mounting it as a sub-app under a route prefix, importing its Router component from src/router.tsx, and configuring path rewrites in next.config.js.

every-app/open-seo is a full-stack Next.js 13 application that provides a complete SEO dashboard UI, server-side API routes, and optional MCP server capabilities. Because it shares the same framework architecture as your existing application, you can embed it directly into your codebase rather than running it as an external service.

Choose Your Integration Strategy

OpenSEO supports three primary integration patterns depending on your architecture needs:

• Mount as a sub-app (recommended): Copy the src/ directory into your project and render the OpenSEO router under a path prefix like /openseo. This approach shares your existing authentication, layout, and styling while preserving the full UI and server routes.
• Run as a separate service: Deploy OpenSEO independently via Docker or Cloudflare, then call its REST endpoints from your application. Use this when you need strict service separation or only require the SEO functionality for internal tools.
• Consume only the data layer: Import individual client-side hooks from src/client/features/ to fetch SEO data from DataForSEO without using the OpenSEO UI components.

Mount OpenSEO as a Sub-App

This method provides the complete OpenSEO experience—including the dashboard, keyword research tools, and site audit features—while allowing your existing Next.js application to handle routing and layout.

Add the Source Code to Your Repository

Clone OpenSEO into your project root as a git submodule or copy the source files directly:

# Option 1: Git submodule (keeps upstream updates easy)

git submodule add https://github.com/every-app/open-seo.git openseo

# Option 2: Flat copy (for permanent forking)

cp -r openseo/src ./src/openseo

The primary entry point is src/router.tsx, which exports the main Router component that handles all OpenSEO pages and API routes.

Install Required Dependencies

OpenSEO requires React 18, Next.js 13, Drizzle ORM, and several UI libraries. From your project root, install dependencies using the same package manager OpenSEO uses (pnpm is recommended, though npm and yarn work):

pnpm install

Review the dependency list in the repository's package.json to ensure version compatibility with your existing packages.

Configure Environment Variables

OpenSEO requires a DataForSEO API key for core functionality and optionally uses OpenRouter for AI-powered features. Add these to your project's .env.local or equivalent environment file:

# Required for all SEO data fetching

DATAFORSEO_API_KEY=your_base64_encoded_credentials

# Optional - enables AI agent capabilities

OPENROUTER_API_KEY=your_openrouter_key

The application reads these variables at runtime to authenticate with the DataForSEO API.

Wire the Router Under a Path Prefix

Configure Next.js to route requests starting with /openseo to the OpenSEO application. Update your next.config.js (or next.config.mjs) with async rewrites:

/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      {
        source: '/openseo/:path*',
        destination: '/openseo/:path*',
      },
    ];
  },
};

module.exports = nextConfig;

Then create a catch-all page file to render the OpenSEO router:

// pages/openseo.tsx (or app/openseo/page.tsx for App Router)
import OpenSEORouter from '@/openseo/src/router';

export default function OpenSEOPage() {
  return <OpenSEORouter />;
}

Share Layout and Authentication (Optional)

To apply your existing site layout and authentication context to OpenSEO pages, wrap the router with your layout components:

// pages/openseo.tsx
import OpenSEORouter from '@/openseo/src/router';
import MyAppLayout from '@/components/MyAppLayout';
import { AuthProvider } from '@/lib/auth';

export default function OpenSEOPage() {
  return (
    <AuthProvider>
      <MyAppLayout>
        <OpenSEORouter />
      </MyAppLayout>
    </AuthProvider>
  );
}

OpenSEO uses Mantine-based layout utilities located in src/lib/layout.shared.tsx and src/client/layout/AppShell.tsx. You can override these by providing your own layout wrapper or modifying the shared layout file to match your design system.

Consume Only the Data Layer

If you only need SEO data without the OpenSEO interface, import the client-side hooks directly into your components. These helpers automatically handle DataForSEO API authentication using your environment variables.

import { useKeywordResearch } from '@/openseo/src/client/features/keyword-research';

export function MyKeywordWidget({ seedKeyword }: { seedKeyword: string }) {
  const { data, isLoading, error } = useKeywordResearch(seedKeyword);

  if (isLoading) return <p>Loading keyword data…</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data.keywords.map((kw) => (
        <li key={kw.id}>{kw.text} - Volume: {kw.volume}</li>
      ))}
    </ul>
  );
}

Additional data hooks are available in src/client/features/ for domain overview, site audits, and rank tracking.

Running the Combined Application

Start your development server normally. The combined application serves both your existing pages and the OpenSEO dashboard at the configured path:

pnpm dev

Navigate to http://localhost:3000/openseo to access the SEO dashboard. All server-side routes, API endpoints, and client-side navigation will function within your application's context.

Summary

• every-app/open-seo is a Next.js 13 application that exports a Router component from src/router.tsx for easy mounting.
• Mount OpenSEO under a path prefix using Next.js rewrites in next.config.js and a dedicated page component.
• Required environment variables are DATAFORSEO_API_KEY (mandatory) and OPENROUTER_API_KEY (optional).
• You can wrap the OpenSEO router with your existing layout and authentication providers to maintain UI consistency.
• For headless usage, import data-fetching hooks directly from src/client/features/ without mounting the full UI.

Frequently Asked Questions

Can I run OpenSEO as a separate microservice instead of integrating it into my codebase?

Yes. You can deploy OpenSEO using Docker or Cloudflare Workers as a standalone service and call its REST endpoints from your application. This approach is documented in docs/SELF_HOSTING_DOCKER.md and keeps your repository free of OpenSEO-specific dependencies, though it requires managing separate deployment pipelines and authentication between services.

What API keys are required to make OpenSEO functional?

You must provide a DATAFORSEO_API_KEY containing base64-encoded credentials for the DataForSEO API, which powers all keyword research, backlink analysis, and rank tracking features. The OPENROUTER_API_KEY is optional and only required if you want to enable AI-powered content analysis and agent capabilities through the MCP server interface.

Is every-app/open-seo compatible with Next.js 14 or the App Router?

The source code is built specifically for Next.js 13 using the Pages Router architecture (evident from the src/router.tsx pattern and file structure). While you can attempt to run it in newer Next.js versions, you may encounter compatibility issues with the App Router's server component model and caching mechanisms. Stick to the Pages Router integration pattern shown above for guaranteed stability.

How do I customize the OpenSEO dashboard styling to match my brand?

Override the default Mantine-based layout by wrapping the OpenSEORouter component with your own layout shell, as shown in the "Share Layout and Authentication" section. The default UI components reside in src/client/layout/AppShell.tsx and src/lib/layout.shared.tsx—you can either fork and modify these files or replace them entirely by intercepting the router with your own design system components.

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