Where Are TypeScript Definitions and Interfaces Stored in OpenSEO?

All TypeScript definitions and interfaces for the OpenSEO project are centralized under the src/types/ directory, supplemented by global declaration files in the repository root and web/ subdirectory.

The OpenSEO codebase relies on a strict type system to ensure data integrity across its SEO automation platform. By consolidating all TypeScript definitions in a single location, the repository maintains consistent data shapes for API payloads, database entities, and environment configurations. This architecture allows developers to import types via absolute paths using the @/types/ alias.

The src/types/ Directory Structure

The src/types/ folder serves as the single source of truth for all data structures within the application. Files here define everything from API request shapes to Cloudflare Worker configurations.

Schema Definitions in src/types/schemas/

Schema files located in src/types/schemas/*.ts use Zod for runtime validation while simultaneously exporting static TypeScript types. Each schema leverages z.infer<typeof SchemaName> to generate corresponding type definitions, ensuring that compile-time type checking aligns with runtime data validation.

For example, project-related types reside in src/types/schemas/projects.ts, keyword schemas live in src/types/schemas/keywords.ts, and Lighthouse audit types are defined in src/types/schemas/lighthouse.ts.

Utility Types and Interfaces

Beyond Zod schemas, the directory contains standalone interface definitions for domain-specific data structures. The file src/types/keywords.ts defines core keyword-related interfaces used throughout the SEO analysis modules. These utility types support shared helper functions like isSupportedLocationCode() without requiring Zod overhead.

Global Declaration Files

OpenSEO includes several ambient declaration files for environment-specific types:

• src/types/vite-env.d.ts – Declares Vite environment variables available through importMeta.env
• worker-configuration.d.ts – Exposes Cloudflare Worker configuration types for the server-side runtime
• web/worker-configuration.d.ts – Provides Worker configuration types specifically for the web client bundle

How to Import and Use TypeScript Types from OpenSEO

Developers reference these definitions using absolute imports mapped to @/types/. This pattern ensures consistent type usage across server handlers, React components, and utility functions.

Importing Zod-Generated Types

When working with API endpoints or database operations, import the inferred types directly from the schema files:

// Import a generated TypeScript type from a Zod schema
import type { CreateProjectInput } from '@/types/schemas/projects';

// Use the type in a server-side handler
export async function createProject(input: CreateProjectInput) {
  // `input` is guaranteed to match the Zod schema at compile-time
  await db.insertProject(input);
}

Accessing Environment Types

For Vite-specific environment variables, the global declarations provide type safety without manual casting:

// Import a global environment type (Vite)
declare const importMeta: ImportMeta;

// Access a typed env variable
const showDevtools = importMeta.env.VITE_SHOW_DEVTOOLS === 'true';

Using Domain-Specific Utilities

Utility types support shared business logic such as location code validation:

// Example of using the shared keyword-location helpers with typed arguments
import { isSupportedLocationCode } from '@/shared/keyword-locations';

function setLocation(code: number) {
  if (!isSupportedLocationCode(code)) {
    throw new Error('Unsupported location code');
  }
  // ...
}

Key TypeScript Definition Files in OpenSEO

Understanding the specific responsibilities of each file helps navigate the codebase efficiently:

• src/types/vite-env.d.ts – Global Vite environment variable definitions for build-time configuration
• src/types/schemas/projects.ts – Zod schema and exported TypeScript types for project creation and management
• src/types/schemas/keywords.ts – Schema definitions and interfaces for keyword ranking data
• src/types/schemas/lighthouse.ts – Type definitions for Google Lighthouse audit results
• src/types/keywords.ts – Core interfaces for keyword entities separate from validation schemas
• worker-configuration.d.ts – Cloudflare Worker bindings and environment types (root level)
• web/worker-configuration.d.ts – Worker configuration types scoped to the web application client

Summary

• All TypeScript definitions for OpenSEO live in the src/types/ directory and related global declaration files
• Zod schemas in src/types/schemas/*.ts provide both runtime validation and static types via z.infer
• Global declarations for Vite and Cloudflare Workers reside in src/types/vite-env.d.ts, worker-configuration.d.ts, and web/worker-configuration.d.ts
• Absolute imports using @/types/ provide consistent access to type definitions across the entire codebase

Frequently Asked Questions

Where are the Zod validation schemas located in OpenSEO?

All Zod validation schemas are stored in the src/types/schemas/ directory. Each file in this folder defines a Zod schema and exports a corresponding TypeScript type using z.infer<typeof Schema>, enabling both runtime validation and compile-time type checking.

How do I import TypeScript types in the OpenSEO codebase?

Use absolute imports with the @/types/ alias. For example, import type { CreateProjectInput } from '@/types/schemas/projects' imports the TypeScript interface generated from the Zod schema. This pattern works consistently across server-side code, React components, and utility functions.

What is the purpose of worker-configuration.d.ts in OpenSEO?

The worker-configuration.d.ts files declare TypeScript types for Cloudflare Worker environment variables and bindings. The root-level file configures server-side Worker types, while web/worker-configuration.d.ts provides types for the client-side web bundle, ensuring type-safe access to platform-specific APIs.

Are environment variables typed in OpenSEO?

Yes, environment variables are typed through src/types/vite-env.d.ts, which declares the Vite-specific ImportMeta interface. This allows type-safe access to variables like importMeta.env.VITE_SHOW_DEVTOOLS with full IntelliSense support and compile-time validation.

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