# Where Are TypeScript Definitions and Interfaces Stored in OpenSEO?

> Find where TypeScript definitions and interfaces are stored in OpenSEO. Discover centralized types in src/types/ and global declarations.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: internals
- Published: 2026-08-08

---

**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`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/projects.ts), keyword schemas live in [`src/types/schemas/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/keywords.ts), and Lighthouse audit types are defined in [`src/types/schemas/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/types/vite-env.d.ts)** – Declares Vite environment variables available through `importMeta.env`
- **[`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts)** – Exposes Cloudflare Worker configuration types for the server-side runtime
- **[`web/worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/src/types/vite-env.d.ts)** – Global Vite environment variable definitions for build-time configuration
- **[`src/types/schemas/projects.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/projects.ts)** – Zod schema and exported TypeScript types for project creation and management
- **[`src/types/schemas/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/keywords.ts)** – Schema definitions and interfaces for keyword ranking data
- **[`src/types/schemas/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/lighthouse.ts)** – Type definitions for Google Lighthouse audit results
- **[`src/types/keywords.ts`](https://github.com/every-app/open-seo/blob/main/src/types/keywords.ts)** – Core interfaces for keyword entities separate from validation schemas
- **[`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts)** – Cloudflare Worker bindings and environment types (root level)
- **[`web/worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/types/vite-env.d.ts), [`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts), and [`web/worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/worker-configuration.d.ts) in OpenSEO?

The [`worker-configuration.d.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.