CodeBelt Code Style Guide

Opinionated TypeScript and React code style for consistency, maintainability, and scalability. Apply these rules when writing new code, reviewing existing code, or refactoring.

Quick Reference

File Placement

Code Type	Location
React component	`components/pages/`, `components/shared/`, or `components/ui/`
API logic	`services/{provider}/{service}/`
Reusable function	`utils/{utilName}/`
React hook	`hooks/use{HookName}/`
Third-party config	`libs/{libraryName}/`

File Extensions

Extension	Purpose
`.ts{x}`	Main code (`.tsx` only when file contains JSX)
`.test.ts`	Tests (placed next to the file being tested)
`.types.ts`	TypeScript types
`.utils.ts{x}`	Helper functions (components only — not in `utils/` folders)
`.utils.test.ts`	Tests for component helper functions
`.schemas.ts`	Zod validation schemas
`.schemas.test.ts`	Tests for schemas
`.constants.ts{x}`	Static objects and constants

Naming Conventions

Context	Convention	Example
Component folders	camelCase	`userCard/`
Component files	PascalCase	`UserCard.tsx`
Everything else	camelCase	`httpClient.ts`
Variables/params	Descriptive (no single chars)	`event` not `e`
Constants	camelCase	`maxRetries` not `MAX_RETRIES`
State updater args	`previous` prefix	`previousData`, `previousState`
Internal handlers	`handle` prefix	`handleSubmit`, `handleFilterChange`
Callback props	`on` prefix	`onSubmit`, `onFilterChange`

Exports

All files use named exports only:

export function Component() {}

No default exports. No barrel files in application code.

Component Files

One component per .tsx file — no exceptions. Every component, no matter how small, gets its own subfolder and file.

Workflows

Creating a New Component

Create folder: components/{pages|shared|ui}/{componentName}/
Create component file: {ComponentName}.tsx with Props type and JSX only
Extract types to {ComponentName}.types.ts (if needed beyond Props)
Extract constants to {ComponentName}.constants.ts (if any)
Extract helpers to {ComponentName}.utils.ts (if any)
Verify: one component per file, Props not exported, named export

Creating a New Service

Create folder: services/{provider}/{serviceName}/
Create main file: {serviceName}Service.ts with fetch functions and query hooks
Create schema file: {serviceName}Service.schemas.ts with Zod schemas
Create constants file: {serviceName}Service.constants.ts with query keys
Verify: schema and type share same name, comment with HTTP method and path

Creating a New Hook

Create folder: hooks/use{HookName}/
Create hook file: use{HookName}.ts
Create test file: use{HookName}.test.ts

Creating a New Utility

Create folder: utils/{utilName}/
Create main utility file: {utilName}.ts — all helper functions go here (no .utils.ts file)
Create constants file: {utilName}.constants.ts (if any)
Create test file: {utilName}.test.ts

Note: Unlike components, utility folders do not use .utils.ts files. The main {utilName}.ts file itself is the utility — adding a .utils.ts beside it would be redundant.

Detailed References

Component patterns and hierarchy: See COMPONENTS.md
Service and schema patterns: See SERVICES.md
Testing patterns: See TESTING.md
Common mistakes to avoid: See MISTAKES.md

codebelt-code-style

Safety Notice

Copy this and send it to your AI assistant to learn