Code Patterns & Conventions

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

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.

PreviousSystem Architecture NextTroubleshooting Guide

Last updated 1 month ago

Good morning

hashtagTable of Contents

hashtagGeneral Principles

hashtag1. Clarity Over Cleverness

hashtag2. Explicit Over Implicit

hashtag3. Early Returns

hashtagTypeScript Conventions

hashtagType Definitions

hashtagType Imports

hashtagStrict Typing

hashtagAvoid any

hashtagReact Patterns

hashtagServer Components (Default)

hashtagClient Components (When Needed)

hashtagComponent Structure

hashtagProps Destructuring

hashtagCustom Hooks

hashtagNext.js Patterns

hashtagServer Components for Data Fetching

hashtagParallel Data Fetching

hashtagDynamic Imports

hashtagServer Actions

hashtagStandard Server Action Pattern

hashtagActionResult Pattern

hashtagRevalidation

hashtagComponent Patterns

hashtagCompound Components

hashtagRender Props

hashtagControlled vs Uncontrolled

hashtagStyling Conventions

hashtagChakra UI v3 Patterns

hashtagCustom Styling

hashtagError Handling

hashtagTry-Catch Pattern

hashtagError Boundaries

hashtagFile Naming

hashtagConventions

hashtagFolder Structure

hashtagImport Conventions

hashtagOrder

hashtagAbsolute Imports

hashtagType Imports

hashtagTesting Patterns

hashtagTest Structure

hashtagTest File Naming

hashtagDocumentation

hashtagJSDoc Comments

hashtagComponent Documentation

hashtagInline Comments

hashtagBest Practices Summary

hashtagDo's ✅

hashtagDon'ts ❌

Table of Contents

General Principles

1. Clarity Over Cleverness

2. Explicit Over Implicit

3. Early Returns

TypeScript Conventions

Type Definitions

Type Imports

Strict Typing

Avoid `any`

React Patterns

Server Components (Default)

Client Components (When Needed)

Component Structure

Props Destructuring

Custom Hooks

Next.js Patterns

Server Components for Data Fetching

Parallel Data Fetching

Dynamic Imports

Server Actions

Standard Server Action Pattern

ActionResult Pattern

Revalidation

Component Patterns

Compound Components

Render Props

Controlled vs Uncontrolled

Styling Conventions

Chakra UI v3 Patterns

Custom Styling

Error Handling

Try-Catch Pattern

Error Boundaries

File Naming

Conventions

Folder Structure

Import Conventions

Order

Absolute Imports

Type Imports

Testing Patterns

Test Structure

Test File Naming

Documentation

JSDoc Comments

Component Documentation

Inline Comments

Best Practices Summary

Do's ✅

Don'ts ❌