# Kaneo Coding Standards: Formatting, TypeScript, and Git Conventions Explained

> Discover Kaneo coding standards: Biome formatting, TypeScript import ordering, Conventional Commits, and pre-commit hooks for seamless development. Learn how we maintain code quality.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: best-practices
- Published: 2026-08-10

---

**Kaneo maintains strict coding standards through automated tooling, requiring Biome-formatted TypeScript with specific import ordering, Conventional Commits for Git history, and mandatory pre-commit hooks that run linting and full builds across the monorepo.**

The `usekaneo/kaneo` repository follows a comprehensive set of coding standards designed to keep its monorepo architecture consistent across backend and frontend packages. These coding standards for Kaneo are documented in [`CLAUDE.md`](https://github.com/usekaneo/kaneo/blob/main/CLAUDE.md) and [`CONTRIBUTING.md`](https://github.com/usekaneo/kaneo/blob/main/CONTRIBUTING.md), with enforcement handled automatically by Biome, Husky, and CI pipelines to ensure every contribution meets quality benchmarks before reaching production.

## Code Formatting with Biome

All source code must adhere to the formatting rules defined in [`biome.json`](https://github.com/usekaneo/kaneo/blob/main/biome.json) at the repository root. The configuration enforces **spaces for indentation**, **double-quoted strings**, and **required semicolons** at statement endings. CSS files and [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) are explicitly excluded from linting to avoid conflicts with package management and styling workflows.

To check formatting manually, run:

```bash
pnpm lint

```

Biome automatically fixes violations during the pre-commit phase, ensuring that only compliant code enters the Git history.

## TypeScript Conventions and Naming

The codebase follows opinionated TypeScript patterns that prioritize type safety and readability. Developers should **prefer `type` over `interface`** unless specifically extending or merging declarations, and rely on type inference when the type is obvious from context.

File naming follows distinct casing rules based on content type:

- **PascalCase** for React components (e.g., [`TaskItem.tsx`](https://github.com/usekaneo/kaneo/blob/main/TaskItem.tsx))
- **kebab-case** for utility functions and hooks (e.g., [`use-task.ts`](https://github.com/usekaneo/kaneo/blob/main/use-task.ts))
- **Hooks must start with `use`** to comply with React conventions

## Import Organization Rules

Imports must follow a strict three-tier hierarchy enforced by Biome's auto-organize feature:

1. **External packages** (e.g., `react`, `hono`)
2. **Internal packages** using `@/` aliases (e.g., `@/components/ui/card`)
3. **Relative imports** (e.g., [`./task-item.css`](https://github.com/usekaneo/kaneo/blob/main/./task-item.css))

This ordering separates third-party dependencies from internal modules and local assets. The following example from `apps/web` demonstrates the correct structure:

```tsx
import { useTranslation } from "react-i18next";          // 1️⃣ external
import { Card } from "@/components/ui/card";            // 2️⃣ internal alias
import "./task-item.css";                               // 3️⃣ relative

export default function TaskItem({ id }: { id: string }) {
  const { t } = useTranslation();

  return (
    <Card className="task-item">
      <h3>{t("tasks:labels.title")}</h3>
    </Card>
  );
}

```

## Git Standards and Conventional Commits

All commit messages must follow the **Conventional Commit** format using prefixes such as `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, and `chore:`. This standardization enables automated changelog generation and semantic versioning.

The enforcement mechanism resides in `.husky/commit-msg`, which runs `commitlint` against every commit message. An example of a compliant commit message:

```

feat: add bulk delete endpoint for tasks

- New POST /tasks/bulk-delete route
- Validation via Valibot schema
- Updated OpenAPI docs

```

## Pre-Commit Validation Pipeline

The `.husky/pre-commit` hook executes a strict validation pipeline that blocks non-compliant code. Before any commit completes, the system runs:

1. `biome ci .` to lint and format all staged files
2. `pnpm run build` to verify the entire monorepo compiles without errors

This dual-check ensures that neither formatting violations nor build-breaking changes reach the repository.

## Monorepo Structure Standards

Kaneo organizes code into a strict directory hierarchy:

- `apps/api/` – Backend Hono/Node.js application
- `apps/web/` – Frontend React + Vite application  
- `packages/` – Shared code consumed by both applications

Within these boundaries, backend code follows a pattern of routes, controllers, and fetchers. For example, controllers in `apps/api/src/` use PascalCase filenames and import database utilities via `@/` aliases:

```ts
import { db } from "@/database";
import { taskTable } from "@/database/schema";
import { eq } from "drizzle-orm";

export async function getTask(taskId: string) {
  const [task] = await db.select().from(taskTable).where(eq(taskTable.id, taskId));
  return task;
}

```

## Testing and Localization Requirements

The codebase requires passing tests before merge, executed via:

- `pnpm test` – Unit tests
- `pnpm test:integration` – API integration tests

These commands run in the CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/usekaneo/kaneo/blob/main/.github/workflows/ci.yml).

For internationalization, all UI strings must reside in `i18n/` JSON files using dot-separated, namespaced keys (e.g., `"tasks:labels.title"`). The repository provides helper scripts to validate translations:

- `pnpm i18n:check` – Verify translation consistency
- `pnpm i18n:report` – Generate translation coverage reports

## Summary

- **Formatting**: Biome enforces spaces, double quotes, and semicolons via [`biome.json`](https://github.com/usekaneo/kaneo/blob/main/biome.json) and `pnpm lint`
- **TypeScript**: Prefer `type` over `interface`; use PascalCase for components and kebab-case for utilities
- **Imports**: Strict three-tier order (external → internal `@/` → relative) auto-organized by Biome
- **Git**: Conventional Commits required, enforced by `.husky/commit-msg`
- **Pre-commit**: `.husky/pre-commit` runs `biome ci .` and full monorepo builds
- **Structure**: Backend in `apps/api/`, frontend in `apps/web/`, shared code in `packages/`
- **Quality**: Tests via `pnpm test` and `pnpm test:integration`; i18n strings in namespaced JSON files

## Frequently Asked Questions

### What formatter does Kaneo use for code standards?

Kaneo uses **Biome** as its formatter and linter, configured in [`biome.json`](https://github.com/usekaneo/kaneo/blob/main/biome.json). It handles import sorting, indentation, quote style, and semicolon enforcement. Developers trigger formatting manually with `pnpm lint` or automatically via the pre-commit hook.

### How should I name React components in Kaneo?

React components must use **PascalCase** filenames (e.g., [`TaskItem.tsx`](https://github.com/usekaneo/kaneo/blob/main/TaskItem.tsx)) and be stored in the appropriate `apps/web/src/` directory. Custom hooks must begin with the `use` prefix and typically use kebab-case filenames (e.g., [`use-task.ts`](https://github.com/usekaneo/kaneo/blob/main/use-task.ts)).

### What commit message format does Kaneo require?

Kaneo requires **Conventional Commits** with specific type prefixes including `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, and `chore:`. The `.husky/commit-msg` hook runs `commitlint` to validate every message before it is accepted into the repository.

### What checks run before I can commit code to Kaneo?

The `.husky/pre-commit` hook runs two critical checks: `biome ci .` for linting and formatting validation, followed by `pnpm run build` to ensure the entire monorepo compiles successfully. Both must pass before Git accepts the commit.