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

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, this module provides score tier classification, compact number formatting, and search term parsing.

// 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 file contains sorting algorithms, domain‑target normalization, and table‑building utilities.

// 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, 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 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:

// 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 – Safe JSON parsing with fallback values
• src/shared/gsc.ts – Google Search Console data transformations
• 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:

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
• CLI helpers are isolated in 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 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.

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