Code Patterns & Conventions

This document outlines the coding patterns, conventions, and best practices used in development at Innox Technologies.

Table of Contents

• General Principles

• TypeScript Conventions

• React Patterns

• Next.js Patterns

• Server Actions

• Component Patterns

• Styling Conventions

• Error Handling

• File Naming

• Import Conventions

• Testing Patterns

• Documentation

General Principles

1. Clarity Over Cleverness

// ❌ Bad - Clever but unclear
const u = users?.find(u => u.id === id)?.n ?? 'Unknown';

// ✅ Good - Clear and explicit
const user = users?.find(user => user.id === currentUserId);
const userName = user?.name ?? 'Unknown';

2. Explicit Over Implicit

// ❌ Bad - Implicit any
function processData(data) {
  return data.map(item => item.value);
}

// ✅ Good - Explicit types
interface DataItem {
  value: number;
}

function processData(data: DataItem[]): number[] {
  return data.map(item => item.value);
}

3. Early Returns

// ❌ Bad - Deep nesting
async function getUser(id: string) {
  if (id) {
    const session = await auth();
    if (session) {
      const user = await db.find(id);
      if (user) {
        return user;
      }
    }
  }
  return null;
}

// ✅ Good - Early returns
async function getUser(id: string) {
  if (!id) return null;

  const session = await auth();
  if (!session) return null;

  const user = await db.find(id);
  return user ?? null;
}

TypeScript Conventions

Type Definitions

File Location: src/types/index.ts

Pattern: Centralized type definitions

// ✅ Good - Centralized types
// src/types/index.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: UserRole;
}

export type UserRole = "admin" | "manager" | "viewer";

// Usage in other files
import type { User } from "@/types";

Interface vs Type:

// ✅ Use interface for objects that can be extended
interface User {
  id: string;
  email: string;
}

interface AdminUser extends User {
  permissions: string[];
}

// ✅ Use type for unions, primitives, and utility types
type UserRole = "admin" | "manager" | "viewer";
type Nullable<T> = T | null;
type ActionResult<T> = { success: true; data: T } | { success: false; error: string };

Type Imports

Pattern: Use type keyword for type-only imports

// ✅ Good - Type-only import
import type { User, UserRole } from "@/types";
import { Button } from "@/components/ui/button";

// ❌ Bad - Mixed imports
import { User, UserRole } from "@/types";

Strict Typing

// ✅ Good - Explicit types
function calculateTotal(price: number, quantity: number): number {
  return price * quantity;
}

// ❌ Bad - Implicit any
function calculateTotal(price, quantity) {
  return price * quantity;
}

Avoid any

// ❌ Bad
function processData(data: any) {
  return data.value;
}

// ✅ Good - Use unknown or specific type
function processData(data: { value: number }) {
  return data.value;
}

// ✅ Better - Use generic for flexibility
function processData<T extends { value: number }>(data: T): number {
  return data.value;
}

React Patterns

Server Components (Default)

Pattern: Use Server Components by default

// ✅ Good - Server Component (no "use client")
export default async function UsersPage() {
  const session = await auth();
  const users = await getUsers();
  return <UserList users={users} />;
}

Client Components (When Needed)

Pattern: Only use Client Components for interactivity

// ✅ Good - Client Component for interactivity
"use client";

import { useState } from "react";

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

When to use Client Components:

• Event handlers (onClick, onChange)

• React hooks (useState, useEffect, useContext)

• Browser APIs (window, localStorage, navigator)

• Third-party libraries that require hooks

Component Structure

Pattern: Consistent component structure

// ✅ Good - Consistent structure
"use client";

/**
 * Button Component
 *
 * Reusable button with variants and sizes
 */

import { useState } from "react";
import { Button as ChakraButton } from "@chakra-ui/react";

interface ButtonProps {
  variant?: "primary" | "secondary";
  size?: "sm" | "md" | "lg";
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = "primary", size = "md", children, onClick }: ButtonProps) {
  const [isPressed, setIsPressed] = useState(false);

  return (
    <ChakraButton
      variant={variant}
      size={size}
      onClick={onClick}
      onMouseDown={() => setIsPressed(true)}
      onMouseUp={() => setIsPressed(false)}
    >
      {children}
    </ChakraButton>
  );
}

Props Destructuring

Pattern: Destructure props with defaults

// ✅ Good - Destructured with defaults
interface CardProps {
  title?: string;
  isEditable?: boolean;
  children: React.ReactNode;
}

export function Card({ title, isEditable = false, children }: CardProps) {
  return (
    <div>
      {title && <h2>{title}</h2>}
      {isEditable && <button>Edit</button>}
      {children}
    </div>
  );
}

Custom Hooks

Pattern: Extract reusable logic into custom hooks

// ✅ Good - Custom hook for session
"use client";

import { useSession } from "next-auth/react";

export function useAuth() {
  const { data: session, status } = useSession();

  return {
    user: session?.user,
    isLoading: status === "loading",
    isAuthenticated: !!session,
    role: session?.user?.role,
  };
}

// Usage
const { user, isAuthenticated, role } = useAuth();

Next.js Patterns

Server Components for Data Fetching

Pattern: Fetch data in Server Components, pass to Client Components

// ✅ Good - Server Component fetches data
export default async function DashboardPage() {
  const session = await auth();
  const stats = await getDashboardStats();

  return <DashboardClient stats={stats} session={session} />;
}

// Client Component receives data as props
"use client";
export function DashboardClient({ stats, session }: { stats: Stats; session: Session }) {
  return <div>Welcome {session.user.name}</div>;
}

Parallel Data Fetching

Pattern: Fetch independent data in parallel

// ✅ Good - Parallel fetching
export default async function DashboardPage() {
  const [users, stats, analytics] = await Promise.all([
    getUsers(),
    getStats(),
    getAnalytics(),
  ]);

  return <DashboardView users={users} stats={stats} analytics={analytics} />;
}

// ❌ Bad - Sequential fetching
export default async function DashboardPage() {
  const users = await getUsers();
  const stats = await getStats();
  const analytics = await getAnalytics();

  return <DashboardView users={users} stats={stats} analytics={analytics} />;
}

Dynamic Imports

Pattern: Lazy load heavy components

// ✅ Good - Dynamic import for heavy component
import dynamic from "next/dynamic";

const HeavyChart = dynamic(() => import("@/components/charts/HeavyChart"), {
  loading: () => <div>Loading chart...</div>,
  ssr: false, // Disable SSR if needed
});

export default function AnalyticsPage() {
  return <HeavyChart data={chartData} />;
}

Server Actions

Standard Server Action Pattern

Pattern: Consistent structure for all Server Actions

// ✅ Good - Standard Server Action pattern
"use server";

import { auth } from "@/lib/auth/config";
import type { ActionResult } from "@/types";
import { canManageUsers } from "@/lib/constants/permissions";

export async function updateUser(
  userId: string,
  data: Partial<User>
): Promise<ActionResult<User>> {
  // 1. Authenticate
  const session = await auth();
  if (!session?.user) {
    return { success: false, error: "Unauthorized" };
  }

  // 2. Authorize
  if (!canManageUsers(session.user.role)) {
    return { success: false, error: "Forbidden: Insufficient permissions" };
  }

  // 3. Validate
  if (!userId) {
    return { success: false, error: "User ID is required" };
  }

  // 4. Execute
  try {
    const updatedUser = await db.users.update({
      where: { id: userId },
      data,
    });
    return { success: true, data: updatedUser };
  } catch (error) {
    console.error("Failed to update user:", error);
    return { success: false, error: "Failed to update user" };
  }
}

ActionResult Pattern

Type: Always return ActionResult<T>

// src/types/index.ts
export type ActionResult<T = void> =
  | { success: true; data: T extends void ? undefined : T }
  | { success: false; error: string };

// Usage
export async function deleteUser(userId: string): Promise<ActionResult<void>> {
  // ...
  return { success: true, data: undefined };
}

export async function getUser(userId: string): Promise<ActionResult<User>> {
  // ...
  return { success: true, data: user };
}

Revalidation

Pattern: Revalidate cache after mutations

import { revalidatePath } from "next/cache";

export async function createUser(data: CreateUserInput): Promise<ActionResult<User>> {
  const user = await db.users.create({ data });

  // Revalidate users page
  revalidatePath("/users");
  revalidatePath("/dashboard");

  return { success: true, data: user };
}

Component Patterns

Compound Components

Pattern: Components that work together

// ✅ Good - Compound components
interface CardProps {
  children: React.ReactNode;
}

export function Card({ children }: CardProps) {
  return <div className="card">{children}</div>;
}

interface CardHeaderProps {
  title: string;
}

export function CardHeader({ title }: CardHeaderProps) {
  return <div className="card-header">{title}</div>;
}

// Usage
<Card>
  <CardHeader title="Users" />
  <CardBody>
    <UserList />
  </CardBody>
</Card>

Render Props

Pattern: Pass rendering logic as prop

// ✅ Good - Render prop for flexibility
interface DataListProps<T> {
  data: T[];
  render: (item: T) => React.ReactNode;
}

export function DataList<T>({ data, render }: DataListProps<T>) {
  return <ul>{data.map(item => <li key={item.id}>{render(item)}</li>)}</ul>;
}

// Usage
<DataList data={users} render={(user) => <span>{user.name}</span>} />

Controlled vs Uncontrolled

Pattern: Prefer controlled components

// ✅ Good - Controlled component
interface InputProps {
  value: string;
  onChange: (value: string) => void;
}

export function ControlledInput({ value, onChange }: InputProps) {
  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
}

Styling Conventions

Chakra UI v3 Patterns

Use Semantic Tokens:

// ✅ Good - Using semantic tokens
<Box bg="bg.subtle">
  <Text color="text.primary">Primary text</Text>
  <Text color="text.secondary">Secondary text</Text>
  <Button colorPalette="primary">Primary action</Button>
</Box>

// ❌ Bad - Hardcoded colors
<Box bg="#F8F9FC">
  <Text color="#0B1C3F">Text</Text>
</Box>

Responsive Patterns:

// ✅ Good - Responsive with Chakra
<Box
  display={{ base: "none", lg: "flex" }}
  p={{ base: 4, md: 6, lg: 8 }}
  fontSize={{ base: "sm", md: "md" }}
>
  Responsive content
</Box>

Custom Styling

Pattern: Use Chakra props, avoid inline styles

// ✅ Good - Chakra props
<Box p={4} bg="bg.subtle" borderRadius="md">
  Content
</Box>

// ❌ Bad - Inline styles
<Box style={{ padding: "16px", backgroundColor: "#F8F9FC" }}>
  Content
</Box>

Error Handling

Try-Catch Pattern

Pattern: Consistent error handling with logging

export async function fetchData(id: string): Promise<ActionResult<Data>> {
  try {
    const data = await db.find(id);
    if (!data) {
      return { success: false, error: "Data not found" };
    }
    return { success: true, data };
  } catch (error) {
    console.error("Failed to fetch data:", error);
    return { success: false, error: "Failed to fetch data" };
  }
}

Error Boundaries

Pattern: Client-side error boundaries

"use client";

import { Component, ReactNode } from "react";

interface Props {
  children: ReactNode;
  fallback?: ReactNode;
}

interface State {
  hasError: boolean;
}

export class ErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback ?? <div>Something went wrong</div>;
    }
    return this.props.children;
  }
}

File Naming

Conventions

// Components: PascalCase
Button.tsx
UserProfile.tsx
DataTable.tsx

// Utilities: camelCase
formatDate.ts
calculateTotal.ts
httpClient.ts

// Types: camelCase
userTypes.ts
apiTypes.ts

// Hooks: camelCase with 'use' prefix
useAuth.ts
useForm.ts
useDebounce.ts

// Server Actions: camelCase
userActions.ts
authActions.ts

Folder Structure

src/
├── app/
│   ├── (view)/
│   │   ├── dashboard/
│   │   │   └── page.tsx
│   │   └── users/
│   │       └── page.tsx
│   └── actions/
│       ├── users.ts
│       └── analytics.ts
├── components/
│   ├── ui/
│   │   ├── button.tsx
│   │   └── input.tsx
│   ├── layout/
│   │   ├── header.tsx
│   │   └── sidebar.tsx
│   └── navigation/
│       └── brand-logo.tsx
├── lib/
│   ├── auth/
│   ├── constants/
│   └── theme/
└── types/
    └── index.ts

Import Conventions

Order

Pattern: Consistent import order

// 1. React and Next.js
import { useState } from "react";
import { redirect } from "next/navigation";

// 2. Third-party libraries
import { Box, Button } from "@chakra-ui/react";
import { auth } from "@/lib/auth/config";

// 3. Internal imports (absolute paths with @)
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import type { User } from "@/types";

// 4. Relative imports
import { formatDate } from "../utils/formatDate";

Absolute Imports

Pattern: Use @/ for project root

// ✅ Good - Absolute imports
import { Button } from "@/components/ui/button";
import { auth } from "@/lib/auth/config";
import type { User } from "@/types";

// ❌ Bad - Relative imports
import { Button } from "../../../components/ui/button";
import { auth } from "../../lib/auth/config";

Type Imports

Pattern: Use type keyword for type-only imports

// ✅ Good - Type-only import
import type { User, UserRole } from "@/types";

// ❌ Bad - Regular import for types
import { User, UserRole } from "@/types";

Testing Patterns

Test Structure

Pattern: AAA pattern (Arrange, Act, Assert)

describe("getUser", () => {
  it("should return user for valid ID", async () => {
    // Arrange
    const userId = "123";
    const expectedUser = { id: userId, name: "John" };

    // Act
    const result = await getUser(userId);

    // Assert
    expect(result.success).toBe(true);
    expect(result.data).toEqual(expectedUser);
  });
});

Test File Naming

// Test files: *.test.tsx or *.spec.tsx
button.test.tsx
useAuth.spec.ts

// Co-located with component
components/
├── button.tsx
└── button.test.tsx

Documentation

JSDoc Comments

Pattern: Document exported functions and types

/**
 * Creates a new user in the system
 *
 * @param email - User's email address
 * @param name - User's full name
 * @param role - User's role (admin | manager | viewer)
 * @returns ActionResult containing the created user or error
 *
 * @example
 * ```typescript
 * const result = await createUser("[email protected]", "John Doe", "viewer");
 * if (result.success) {
 *   console.log("User created:", result.data);
 * }
 * ```
 */
export async function createUser(
  email: string,
  name: string,
  role: UserRole
): Promise<ActionResult<User>> {
  // Implementation
}

Component Documentation

Pattern: Document component purpose and props

/**
 * Button Component
 *
 * Reusable button following brand guidelines:
 * - Primary variant uses brand.warmGold
 * - Consistent styling across the app
 *
 * @example
 * ```tsx
 * <Button variant="primary" onClick={handleClick}>
 *   Click me
 * </Button>
 * ```
 */
interface ButtonProps {
  /**
   * Button variant
   * @default "primary"
   */
  variant?: "primary" | "secondary" | "ghost";
  /**
   * Button size
   * @default "md"
   */
  size?: "sm" | "md" | "lg";
  /**
   * Loading state
   */
  isLoading?: boolean;
  /**
   * Button content
   */
  children: React.ReactNode;
}

Inline Comments

Pattern: Explain WHY, not WHAT

// ✅ Good - Explains WHY
// Use secondary variant for destructive actions to prevent accidental clicks
<Button variant="secondary" colorPalette="danger">
  Delete
</Button>

// ❌ Bad - States WHAT
// Red button for delete
<Button variant="secondary" colorPalette="danger">
  Delete
</Button>

Best Practices Summary

Do's ✅

• Use Server Components by default

• Use TypeScript strictly

• Use absolute imports with @/

• Destructure props with defaults

• Handle errors consistently with ActionResult

• Document exported functions and components

• Use semantic tokens for styling

• Fetch data in parallel when possible

• Implement permission checks in Server Actions

• Follow consistent naming conventions

Don'ts ❌

• Don't use Client Components unnecessarily

• Don't use any type

• Don't use relative imports for deep paths

• Don't ignore TypeScript errors

• Don't skip error handling

• Don't hardcode colors

• Don't use client-side fetch for data

• Don't skip permission checks

• Don't commit commented code

• Don't mix UI logic with business logic

For architecture details, see ARCHITECTURE.md. For troubleshooting, see TROUBLESHOOTING.md.