# Open‑SEO Utility Functions Location: A Complete File‑by‑File Guide

> Discover utility function locations in every-app/open-seo. This guide details their placement across client, server, and shared scripts for easy access and integration.

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

---

**Utility functions in the open‑seo project are organized into focused `utils` modules distributed across client features, server‑side audit libraries, and shared scripts under the `src/` and `scripts/` directories.**

The project follows a **colocation pattern**: helpers live next to the features that use them rather than in a monolithic `utils/` folder. This design keeps dependencies explicit and makes imports predictable. This guide maps every significant utility location with exact paths and usage patterns.

---

## Client‑Side Utility Functions

The React frontend stores UI helpers inside individual feature modules. These handle formatting, normalization, and component‑specific logic.

### Keywords Feature Utilities

Located at [`src/client/features/keywords/utils.ts`](https://github.com/every-app/open-seo/blob/main/src/client/features/keywords/utils.ts), this module provides **score tier classification**, **compact number formatting**, and **search term parsing**.

```typescript
// Example: Using a number‑formatting helper in a component
import { formatCompactNumber } from "@/client/features/keywords/utils";

function TrafficBadge({ traffic }: { traffic: number | null }) {
  return <span>{formatCompactNumber(traffic)}</span>;
}

```

Key exports include `getScoreTierClass()` for CSS class mapping, `formatCompactNumber()` for readable traffic displays, and `parseSearchTerms()` for query string handling.

### Domain Feature Utilities

The [`src/client/features/domain/utils.ts`](https://github.com/every-app/open-seo/blob/main/src/client/features/domain/utils.ts) file contains **sorting algorithms**, **domain‑target normalization**, and **table‑building utilities**.

```typescript
// Example: Normalising a domain string on the client side
import { normalizeDomainTarget } from "@/client/features/domain/utils";

const userInput = "example.com/path";
const normalized = normalizeDomainTarget(userInput);
// normalized => "example.com/path"

```

These helpers ensure consistent URL handling across domain management screens.

### Lighthouse Issues Utilities

Found at [`src/client/features/lighthouse/issues/utils.tsx`](https://github.com/every-app/open-seo/blob/main/src/client/features/lighthouse/issues/utils.tsx), this module supplies small **React‑specific UI helpers** for rendering audit results. The `.tsx` extension signals JSX‑capable utilities used directly in issue components.

---

## Server‑Side Utility Functions

The audit engine relies on focused helpers for URL processing and workflow orchestration.

### URL Processing for Audits

The [`src/server/lib/audit/url-utils.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/url-utils.ts) module powers the site‑audit workflow with **URL parsing**, **canonicalization**, and **validation utilities**. These functions handle edge cases like protocol stripping, trailing‑slash normalization, and parameter sorting that standard URL libraries miss.

Server utilities are deliberately separated from client code to avoid bundling Node.js‑specific logic into the frontend.

---

## CLI and Script Utilities

Standalone tooling uses dedicated helpers in [`scripts/cli-utils.ts`](https://github.com/every-app/open-seo/blob/main/scripts/cli-utils.ts):

```typescript
// Example: Parsing CLI arguments in a script
import { parseArgs } from "@/scripts/cli-utils";

const args = parseArgs(process.argv.slice(2));
if (args.help) console.log("Usage: …");

```

This module handles **argument parsing**, **environment file loading**, and **local‑development configuration** for maintenance scripts and one‑off commands.

---

## Shared Cross‑Platform Utilities

Low‑level helpers used by both client and server live in the `src/shared/` directory:

- **[`src/shared/json.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/json.ts)** – Safe JSON parsing with fallback values
- **[`src/shared/gsc.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/gsc.ts)** – Google Search Console data transformations
- **[`src/shared/error-codes.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/error-codes.ts)** – Standardized error definitions

These files contain **no framework dependencies**, making them safe to import anywhere in the codebase.

---

## Import Path Conventions

All utility imports use **path aliases** defined in [`tsconfig.json`](https://github.com/every-app/open-seo/blob/main/tsconfig.json):

| Alias | Resolves To |
|-------|-------------|
| `@/client/*` | `src/client/*` |
| `@/server/*` | `src/server/*` |
| `@/shared/*` | `src/shared/*` |
| `@/scripts/*` | `scripts/*` |

This convention eliminates relative path fragility (`../../../utils`) and makes refactoring safer.

---

## Summary

- **Feature‑colocated utilities** live in `src/client/features/{domain,keywords,lighthouse}/utils.*`
- **Server audit utilities** reside in [`src/server/lib/audit/url-utils.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/audit/url-utils.ts)
- **CLI helpers** are isolated in [`scripts/cli-utils.ts`](https://github.com/every-app/open-seo/blob/main/scripts/cli-utils.ts)
- **Shared core utilities** populate `src/shared/` with zero framework coupling
- Every import uses `@/` aliases for maintainable cross‑module references

---

## Frequently Asked Questions

### Where is the main utils folder in open‑seo?

There is no single `utils/` folder. Instead, open‑seo distributes utilities across **feature directories** (`src/client/features/*/utils.ts`), **server libraries** (`src/server/lib/audit/`), and **shared modules** (`src/shared/*`). This colocation keeps code discoverable and prevents circular dependencies.

### How do I import a formatting utility in a React component?

Use the `@/client/features/keywords/utils` path alias. For example: `import { formatCompactNumber } from "@/client/features/keywords/utils"`. The path alias avoids brittle relative imports and works across the entire client codebase.

### What utilities are available for CLI scripts?

The [`scripts/cli-utils.ts`](https://github.com/every-app/open-seo/blob/main/scripts/cli-utils.ts) module exports `parseArgs()` for command‑line argument handling and environment‑loader functions for local‑development configuration. These are designed for Node.js runtime only and should not be imported into browser code.

### Are server utilities reusable on the client?

Most server utilities in `src/server/lib/` are **Node.js‑specific** and cannot run in the browser. For cross‑platform logic—such as URL normalization or date formatting—place code in `src/shared/` and keep it free of environment‑specific APIs.