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

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 and 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 at the repository root. The configuration enforces spaces for indentation, double-quoted strings, and required semicolons at statement endings. CSS files and package.json are explicitly excluded from linting to avoid conflicts with package management and styling workflows.

To check formatting manually, run:

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)
• kebab-case for utility functions and hooks (e.g., 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)

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

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:

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.

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 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. 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) 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).

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.

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