Code Style Guide

Coding standards and conventions for the Constellation project.

Table of Contents

1. TypeScript/JavaScript
2. React Components
3. File Organization
4. Naming Conventions
5. Import Organization
6. Code Formatting

---

TypeScript/JavaScript

Use Strict Type Mode

// ✅ GOOD
function processUser(user: User): Promise<void> {
  // ...
}

// ❌ BAD
function processUser(user: any): any {
  // ...
}

Prefer Const/Let Over Var

// ✅ GOOD
const CONSTANT_VALUE = 'value';
let mutableValue = 0;

// ❌ BAD
var oldStyle = 'avoid this';

Use Template Literals

// ✅ GOOD
const message = `Hello, ${name}! You have ${count} items.`;

// ❌ BAD
const message = 'Hello, ' + name + '! You have ' + count + ' items.';

Avoid Double Negatives

// ✅ GOOD
const isAvailable = true;
if (isAvailable) { }

// ❌ BAD
const isNotUnavailable = true;
if (!isNotUnavailable) { }

Use Nullish Coalescing

// ✅ GOOD
const value = config.value ?? 'default';

// ❌ BAD
const value = config.value || 'default'; // Fails for falsy values

Destructuring

// ✅ GOOD
const { name, email } = user;
const { title = 'Untitled' } = props;

// ❌ BAD
const name = user.name;
const email = user.email;

---

React Components

Naming Convention

// ✅ GOOD - PascalCase for components
export function UserProfile() { }
export const WorkspaceCard = () => { };

// ❌ BAD - camelCase for components
export function userProfile() { }
export const workspaceCard = () => { };

Functional Components Only

// ✅ GOOD
export function MyComponent() {
  return <div>Content</div>;
}

// ❌ BAD - Class components (legacy)
class MyComponent extends React.Component { }

Component Structure

'use client';

import React from 'react';
import { useHook } from '@/src/hooks/use-hook';
import { Button } from '@/src/components/ui/Button';

interface ComponentProps {
  title: string;
  onChange?: (value: string) => void;
}

export function MyComponent({ title, onChange }: ComponentProps) {
  const [state, setState] = React.useState('');

  return (
    <div>
      <h1>{title}</h1>
      <Button onClick={() => setState('new')}>Click me</Button>
    </div>
  );
}

Order: 1. Imports 2. Type/Interface definitions 3. Component declaration 4. Props interface 5. Hook usage 6. State and effects 7. Event handlers 8. Render JSX

Props Interface

// ✅ GOOD
interface CardProps {
  title: string;
  description?: string;
  onClose: () => void;
  children?: React.ReactNode;
}

export function Card({ title, description, onClose, children }: CardProps) {
  // ...
}

// ❌ BAD - Inline props without type
export function Card(props: any) {
  // ...
}

Use 'use client' For Interactive Components

// ✅ GOOD
'use client';

import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

Avoid Direct DOM Manipulation

// ✅ GOOD
export function InputField({ value, onChange }: Props) {
  return (
    <input
      value={value}
      onChange={(e) => onChange(e.target.value)}
    />
  );
}

// ❌ BAD
export function InputField() {
  useEffect(() => {
    document.getElementById('input').value = 'test'; // Direct manipulation
  }, []);

  return <input id="input" />;
}

Key in Lists

// ✅ GOOD
{items.map((item) => (
  <Item key={item.id} {...item} />
))}

// ❌ BAD - Using index as key
{items.map((item, index) => (
  <Item key={index} {...item} />
))}

Conditional Rendering

// ✅ GOOD - Ternary for simple conditions
{isLoading ? <Spinner /> : <Content />}

// ✅ GOOD - Logical AND for show/hide
{isVisible && <Content />}

// ✅ GOOD - Early return for complex logic
if (!isReady) return null;

// ❌ BAD - Inline if-else
{if (isLoading) return <Spinner />} {/* Syntax error */}

---

File Organization

File Structure

src/
├── components/
│   ├── ui/                          # Shadcn/ui components
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   └── index.ts                 # Export barrel
│   ├── common/                      # Shared components
│   │   ├── Header.tsx
│   │   ├── Footer.tsx
│   │   └── Header.test.tsx
│   └── workspace/                   # Feature-specific
│       ├── WorkspaceCard.tsx
│       ├── WorkspaceCard.test.tsx
│       └── WorkspaceList.tsx
├── hooks/
│   ├── use-mobile.tsx
│   ├── use-mobile.test.tsx
│   └── index.ts                     # Export barrel
├── lib/
│   ├── api.ts                       # API client
│   ├── utils.ts                     # Utilities
│   ├── auth.ts                      # Auth logic
│   └── schemas/                     # Zod schemas
│       ├── user.ts
│       └── workspace.ts
├── services/
│   ├── userService.ts
│   ├── workspaceService.ts
│   └── apiClient.ts
└── types/
    ├── user.ts
    ├── workspace.ts
    └── index.ts                     # Export barrel

One Component Per File

// ✅ GOOD
MyComponent.tsx          # Component
MyComponent.test.tsx     # Tests
MyComponent.stories.tsx  # Storybook (if using)

// ❌ BAD
MyComponents.tsx         # Multiple components in one file

Barrel Exports

// ✅ GOOD - src/components/ui/index.ts
export { Button } from './Button';
export { Card } from './Card';
export { Dialog } from './Dialog';

// Usage
import { Button, Card } from '@/src/components/ui';

---

Naming Conventions

Constants

// ✅ GOOD - UPPER_SNAKE_CASE
const MAX_ATTEMPTS = 3;
const API_BASE_URL = 'https://api.example.com';
const FEATURE_FLAGS = { BETA_EDITOR: true };

// ❌ BAD
const maxAttempts = 3;
const api_url = 'https://api.example.com';

Functions & Variables

// ✅ GOOD - camelCase
function getUserData() { }
const userName = 'John';
const isActive = true;

// ❌ BAD
function get_user_data() { }
const user_name = 'John';
const IsActive = true;

Boolean Variables

// ✅ GOOD - prefix with is/has/can
const isLoading = true;
const hasError = false;
const canEdit = true;
const shouldRefresh = false;

// ❌ BAD
const loading = true;
const error = false;

Event Handlers

// ✅ GOOD - prefix with on
function handleClick() { }
function handleSubmit() { }
const onClick = () => { };

// ❌ BAD
function click() { }
function submit() { }

API-related Functions

// ✅ GOOD - clear intent
async function fetchUserData() { }
async function createWorkspace() { }
function deleteWorkspace() { }

// ❌ BAD
async function getUser() { }
async function addWorkspace() { }

---

Import Organization

Import Order

// 1. External packages
import React, { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import { z } from 'zod';

// 2. Internal modules (absolute imports)
import { Button } from '@/src/components/ui/Button';
import { useWorkspace } from '@/src/hooks/use-workspace';
import { apiClient } from '@/src/lib/api';
import type { User } from '@/src/types/user';

// 3. Relative imports (if necessary)
import { helper } from './helper';

// 4. Side effects
import './styles.css';

Absolute Imports

// ✅ GOOD - Absolute imports
import { Button } from '@/src/components/ui/Button';
import { useWorkspace } from '@/src/hooks/use-workspace';

// ❌ BAD - Relative imports (hard to refactor)
import { Button } from '../../components/ui/Button';
import { useWorkspace } from '../../../hooks/use-workspace';

Type Imports

// ✅ GOOD - Separate type imports
import { Button } from '@/src/components/ui/Button';
import type { ButtonProps } from '@/src/components/ui/Button';

// ❌ BAD - Mixed imports
import { Button, type ButtonProps } from '@/src/components/ui/Button';

---

Code Formatting

Line Length

Keep lines under 100 characters for readability.

// ✅ GOOD
const formattedText = `Welcome ${userName}, you have ${itemCount} items`;

// ❌ BAD - Too long
const excessivelyLongVariableNameThatMakesLineUnreadablyLongWhenUsed = 'value';

Function Parameters

// ✅ GOOD
export function processUserData(
  userId: string,
  options: ProcessOptions,
  callback: (result: Result) => void
): Promise<void> {
  // ...
}

// ❌ BAD
export function processUserData(userId: string, options: ProcessOptions, callback: (result: Result) => void): Promise<void> {
  // ...
}

Object Formatting

// ✅ GOOD - Single line for simple objects
const config = { timeout: 5000, retries: 3 };

// ✅ GOOD - Multi-line for complex objects
const config = {
  timeout: 5000,
  retries: 3,
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
};

Comments

// ✅ GOOD - Explains why, not what
// Cache user data for 5 minutes to reduce API calls
const USER_CACHE_TTL = 300000;

// ✅ GOOD - Explains non-obvious code
// Convert timestamp to milliseconds (API returns seconds)
const timestampMs = timestamp * 1000;

// ❌ BAD - Obvious comments
// Set loading to true
setLoading(true);

// ❌ BAD - Outdated comments
// This fixes bug #123 (bug no longer exists)
const value = config.value ?? 0;

JSDoc for Public APIs

// ✅ GOOD
/**
 * Formats a date for display
 * @param date - The date to format
 * @param locale - Optional locale string (default: 'en-US')
 * @returns Formatted date string
 * @example
 * formatDate(new Date('2024-01-15'))
 * // Returns: 'Jan 15, 2024'
 */
export function formatDate(date: Date, locale: string = 'en-US'): string {
  // ...
}

---

Tools & Automation

ESLint

# Check code style
bun lint

# Auto-fix issues
bun lint --fix

Prettier

Configured automatically for: - Indentation (2 spaces) - Line length (100 characters) - Semicolons - Single quotes - Trailing commas

TypeScript Strict Mode

Enable in tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

---

Common Patterns

Custom Hook Pattern

// ✅ GOOD
export function useUserData(userId: string) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    (async () => {
      try {
        const data = await apiClient.get(`/users/${userId}`);
        setUser(data);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    })();
  }, [userId]);

  return { user, loading, error };
}

Component with API Call

// ✅ GOOD
'use client';

interface UserCardProps {
  userId: string;
}

export function UserCard({ userId }: UserCardProps) {
  const { user, loading, error } = useUserData(userId);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!user) return null;

  return (
    <div className="p-4 border rounded">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

Error Handling

// ✅ GOOD
async function fetchData() {
  try {
    const response = await apiClient.get('/data');
    return response;
  } catch (error) {
    logger.error('Failed to fetch data', error);
    throw new Error('Failed to fetch data');
  }
}

---

Checklist Before Commit

• ✅ All TypeScript types are correct
• ✅ No any types used (except where necessary)
• ✅ Components are properly named (PascalCase)
• ✅ Imports are organized correctly
• ✅ No console.log statements (use logger)
• ✅ Error handling is present
• ✅ Tests are written
• ✅ ESLint passes: bun lint
• ✅ Code is readable and well-commented
• ✅ No hardcoded values in components

---

Related Documentation

• 📝 CONTRIBUTING.md - Contribution guidelines
• 🧪 TESTING.md - Testing standards
• 🏗️ ARCHITECTURE.md - Architecture patterns

---

Last Updated: January 2026