How to Import and Use the Main Exports from the Open‑SEO Library

To import and use the main exports from the open-seo library, import startInstance from the package root to bootstrap the application, or import specific server functions from open-seo/serverFunctions/* and database clients from open-seo/client/tanstack-db for granular functionality.

Open‑SEO is published as a type‑module npm package ("type": "module" in package.json) under the repository every-app/open-seo. The library’s public API is centralized in src/start.ts, which exports the primary startInstance used to wire up the React‑Start server alongside global server‑function middleware.

Primary Entry Point: The startInstance Export

The most common way to import and use the main exports from the open-seo library is through the startInstance constant defined in src/start.ts. This export creates a configured React‑Start instance that includes built‑in CSRF protection and global server‑function middleware.

// src/start.ts - Primary application bootstrap
import { startInstance } from 'open-seo';

// startInstance is a React‑Start instance ready for Cloudflare Workers or Node.js
export const app = startInstance;

The startInstance export handles the heavy lifting of setting up the server environment, making it the single entry point for most consumers who need to initialize the full Open‑SEO application stack.

Importing Server Functions for Backend Operations

For scenarios requiring only specific backend capabilities, you can import individual server functions directly from their sub‑paths. The src/serverFunctions/ directory contains modular implementations for domains like projects, keywords, and rank tracking, each re‑exported from the package root.

// Import specific server functions from src/serverFunctions/projects.ts
import {
  getProjects,
  createProject,
  updateProject,
} from 'open-seo/serverFunctions/projects';

// Example usage inside a React component or API route
async function loadProjects() {
  const projects = await getProjects({});
  console.log(projects);
}

Each server function is typed with Zod schemas, providing automatic input validation without additional configuration. This granular import pattern reduces bundle sizes when you only need specific operations rather than the full application instance.

Database Access with TanStack‑DB Client

When you need direct database access from React components, import the TanStack‑DB client from src/client/tanstack-db/index.ts. This export provides a pre‑configured Drizzle ORM instance (db) with the complete schema exported from src/db/index.ts.

// Use the TanStack‑DB client for queries in React components
import { useQuery } from '@tanstack/react-query';
import { db } from 'open-seo/client/tanstack-db';

function ProjectList() {
  const { data: projects } = useQuery(['projects'], () => db.project.findMany());
  
  return (
    <ul>
      {projects?.map((p) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

The db export supports SQLite, DynamoDB, and Postgres backends, allowing you to query, insert, or update data without manually configuring the ORM connection.

Installation and Module Configuration

Because Open‑SEO is an ES module package, you must use modern import syntax rather than CommonJS require.

npm install open-seo

# or

pnpm add open-seo

Ensure your project's package.json includes "type": "module" or use the .mjs/.mts extension for your files. The library strictly enforces ES module semantics as defined in the source repository's configuration.

Summary

• Import startInstance from the package root (open-seo) to bootstrap the complete React‑Start application with CSRF protection and global middleware.
• Import individual server functions from open-seo/serverFunctions/* when you need specific backend operations like project or keyword management.
• Use the TanStack‑DB client (open-seo/client/tanstack-db) for direct database queries in React components using the pre‑configured Drizzle ORM instance.
• Enable ES modules in your project since Open‑SEO publishes only ESM exports ("type": "module").

Frequently Asked Questions

Can I use CommonJS require() to import from open-seo?

No, you cannot use require() because Open‑SEO is published as a pure ES module package with "type": "module" set in its package.json. You must use standard ES module import syntax (import ... from ...) in files with .js, .ts, .mjs, or .mts extensions, or ensure your project is configured as a module.

What is the difference between importing startInstance versus individual server functions?

Importing startInstance from src/start.ts initializes the entire React‑Start server infrastructure with global middleware and CSRF handling, suitable for full‑stack applications. Importing individual functions from open-seo/serverFunctions/* allows you to use specific backend logic (like getProjects or createProject) without bootstrapping the complete server, ideal for serverless functions or microservices.

Does the open-seo library support TypeScript out of the box?

Yes, all main exports from the open-seo library include TypeScript definitions. The server functions use Zod schemas for runtime validation that infer TypeScript types, and the database client (db) exported from src/client/tanstack-db/index.ts includes full type safety for the Drizzle ORM schema defined in src/db/index.ts.

Which database backends are supported when using the TanStack‑DB export?

The db export from open-seo/client/tanstack-db supports SQLite, DynamoDB, and Postgres backends. The schema definitions in src/db/index.ts abstract the underlying database implementation, allowing you to use the same db.project.findMany() syntax regardless of your chosen storage engine.

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