React & JavaScript Guidelines

These guidelines apply to any React or JavaScript project at Hydred. They are designed to keep codebases readable, consistent, and easy to maintain across teams.

---

Tech Stack

Technology	Purpose	Docs
Next.js	React framework, routing, SSR	https://nextjs.org/docs
TypeScript	Static typing	https://www.typescriptlang.org/docs
Tailwind CSS	Utility-first styling	https://tailwindcss.com/docs
shadcn/ui	UI component library	https://ui.shadcn.com
Zod	Schema validation	https://zod.dev
React Hook Form	Form state management	https://react-hook-form.com
ESLint	Code linting	https://eslint.org/docs/latest
Prettier	Code formatting	https://prettier.io/docs/en

---

1. General Principles

• Write simple, clear, and intentional code.
• Prefer readability over cleverness.
• Keep components and functions focused on a single responsibility.
• Avoid introducing unnecessary dependencies.
• Fix the root cause rather than patching symptoms.

---

2. Project Structure

Keep related code together and place new functionality in the most appropriate existing folder rather than creating scattered files. A typical structure looks like:

src/
├── app/              # route-level pages, layouts, and global app shell
├── components/
│   ├── layouts/      # layout-level shared UI
│   ├── shared/       # reusable cross-cutting components
│   └── ui/           # primitive UI components (shadcn/ui — do not modify)
├── lib/              # shared utilities and helpers
├── config/           # configuration and app constants
└── data/             # static or mock data

---

3. Naming Conventions

Type	Convention	Example
React components	PascalCase	DesktopHeader.tsx
Variables & functions	camelCase	getUserData
Hooks	camelCase with use prefix	useAuth
Route folders	kebab-case	user-profile/
Utility files	kebab-case	format-date.ts

Use descriptive names that explain intent. Avoid short names like data or temp unless the context is very clear.

---

4. TypeScript

• Prefer strong typing over any.
• Define interfaces or types for props, API responses, and shared data shapes.
• Use type inference where it improves clarity, but do not rely on implicit any.
• Keep types close to where they are used unless they are shared across multiple modules.
• Use Zod for runtime validation when handling user input, API payloads, or form data.

// Good
interface UserProfile {
  id: string;
  name: string;
  email: string;
}

// Bad
const user: any = fetchUser();

---

5. React & Component Guidelines

• Keep components small and composable.
• Split complex UI into smaller presentational and container components.
• Use server components by default in Next.js — only make a component client-side when interactivity is required.
• Keep side effects, data fetching, and browser APIs inside the smallest necessary component.
• Avoid large inline conditional blocks — extract helpers when logic becomes hard to follow.
• Import hooks directly from React instead of accessing them through the React namespace.

// Good
import { useState } from "react";

// Bad
React.useState();

Good Component Example

export function ProfileCard({ name }: { name: string }) {
  return <h1 className="text-xl font-semibold">{name}</h1>;
}

Bad Component Example

export function Component() {
  const x = Math.random();

  return (
    <div>
      <h1>{x}</h1>
      <div>{JSON.stringify({ a: 1, b: 2 })}</div>
      <button onClick={() => alert("clicked")}>Click</button>
    </div>
  );
}

---

6. Styling

We use Tailwind CSS for styling and shadcn/ui for UI primitives.

• Use Tailwind CSS utility classes for styling.
• Keep styling consistent — avoid mixing multiple styling approaches in the same project.
• Always check shadcn/ui for an existing component before building a new one.
• Never modify files inside components/ui/ directly — these are managed by shadcn/ui.
• Use the cn utility helper for combining class names when conditional logic is needed.

// Good
import { cn } from "@/lib/utils";

<button className={cn("px-4 py-2 rounded", isActive && "bg-blue-500")}>
  Click
</button>

// Bad
<button style={{ padding: "8px 16px" }} className="rounded">
  Click
</button>

---

7. Accessibility

• Use semantic HTML whenever possible.
• Ensure all interactive elements are keyboard accessible.
• Provide meaningful labels and alt text for images and icons.
• Favor accessible defaults over custom behavior that is difficult to use without a mouse.

// Good
<button aria-label="Close dialog">✕</button>

// Bad
<div onClick={closeDialog}>✕</div>

---

8. Code Quality & Formatting

• Run formatting before committing changes.
• Keep imports organized and remove unused code.
• Follow the repository linting and formatting rules.
• Write comments for non-obvious logic only — avoid commenting on obvious code.

Run before every commit:

pnpm lint
pnpm prettier:write

---