Skip to content
Nexical Ecosystem

Coding Standards

This document establishes the authoritative coding standards for the project.

Core Philosophy

Section titled “Core Philosophy”

AI-Native Context

Section titled “AI-Native Context”
  • Context is King: Write code that explains itself. Generative AI relies on clear variable names and explicit types.
  • Explicit over Implicit: Avoid “magic” logic.
  • Small Blast Radius: Keep functions and components focused.

Strictness

Section titled “Strictness”
  • Sanity over Speed: We prefer verbose, type-safe code.
  • Zero Warnings: The main branch must be warning-free.

TypeScript Standards

Section titled “TypeScript Standards”

Type Safety

Section titled “Type Safety”
  • No any: Strictly forbidden. Use unknown + Zod.
  • No ts-ignore: Fix the underlying issue.

Return Types

Section titled “Return Types”
  • Explicit Returns: All exported functions MUST have an explicit return type.

Uniform Service Response

Section titled “Uniform Service Response”

All public methods in Services and Actions MUST return a ServiceResponse<T> object:

interface ServiceResponse<T> {
  success: boolean;
  data: T | null;
  error: string | null;
}

Files & Imports

Section titled “Files & Imports”

Import Aliases

Section titled “Import Aliases”
  • @/ refers to src/.
  • @modules/ refers to modules/.
  • @tests/ refers to tests/.

Forbidden

Section titled “Forbidden”
  • Deep relative imports that traverse up the tree (e.g., ../../components).

Styling & CSS

Section titled “Styling & CSS”

We use a utility-first approach powered by Tailwind CSS.

  • No Arbitrary Values: Use theme tokens (w-32), not arbitrary strings (w-[123px]).
  • Semantic Colors: Use bg-destructive, not bg-red-500.

Documentation

Section titled “Documentation”
  • JSDoc: All exported members must have JSDoc explaining why it exists.