Conventions

Code conventions and patterns used in this codebase

This guide covers the conventions and patterns used in this codebase to keep things consistent and maintainable.

Feature Directory Structure

Features live in src/features/ and follow a flat-first approach. Only add subfolders when navigating becomes painful.

Guidelines

When to Add Subfolders

Add structure only when you have clear logical groupings:

Small features stay flat:

Code Style

Imports

• Prefer the ~ alias for imports from the root
• In ./packages/*, use relative imports instead

// good
import { Button } from '~/interface/Button'

// avoid in src/
import { Button } from '../../../interface/Button'

Console Output

Use console.info() instead of console.log():

// good
console.info('server started')

// avoid
console.log('server started')

Node Built-ins

Use the node: prefix for built-in modules:

// good
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// avoid
import { readFile } from 'fs/promises'

Comments

Write few, lowercase comments. Code should be self-documenting:

// good - explains why, not what
// zero doesn't support this query yet
const users = await db.query.users.findMany()

// avoid - obvious from the code
// Get all users from database
const users = await db.query.users.findMany()

Exports

Prefer named exports over default exports, especially in routes. React Refresh doesn’t support default exports, so named exports ensure HMR works properly. One uses the last export of a file as the page component when there’s no default export:

// good - HMR works, last export used as page
export function HomePage() { ... }

// avoid - breaks HMR
export default function HomePage() { ... }

Environment Variables

Never modify /src/server/env-server.ts directly - it’s auto-generated.

To add new environment variables:

1. Add to the env section in package.json
2. Run bun env:update
3. Optionally add an example value to .env.development

Verification

After making changes, verify your work:

• Small changes: bun check:all
• Larger changes: bun run ci --dry-run