|
| 1 | +# Code Style Conventions |
| 2 | + |
| 3 | +## TypeScript Standards |
| 4 | + |
| 5 | +### Strictness Level: MAXIMUM |
| 6 | + |
| 7 | +- **Strict Mode**: Fully enabled with all flags |
| 8 | +- **No `any` Types**: Use `unknown` if type is truly unknown |
| 9 | +- **No Type Assertions**: Use type guards instead of `as` casting |
| 10 | +- **Readonly Props**: Use `readonly` for component props |
| 11 | +- **Null Safety**: Proper null checking with type guards |
| 12 | + |
| 13 | +### Type Patterns |
| 14 | + |
| 15 | +```typescript |
| 16 | +// Component Props Pattern |
| 17 | +export interface ComponentProps { |
| 18 | + readonly children?: ReactNode; |
| 19 | + readonly className?: string; |
| 20 | +} |
| 21 | + |
| 22 | +// Utility Type Examples |
| 23 | +export type NonEmptyArray<T> = [T, ...T[]]; |
| 24 | + |
| 25 | +// Type Guards |
| 26 | +export function isNonNullable<T>(value: T): value is NonNullable<T> { |
| 27 | + return value != null; |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +## Naming Conventions |
| 32 | + |
| 33 | +### Files & Directories |
| 34 | + |
| 35 | +- **Components**: `PascalCase.tsx` (e.g., `StyledButton.tsx`) |
| 36 | +- **Utilities**: `camelCase.ts` (e.g., `assertionUtils.ts`) |
| 37 | +- **Types**: `PascalCase` with descriptive names |
| 38 | +- **Constants**: `UPPER_SNAKE_CASE` for site config |
| 39 | + |
| 40 | +### Code Naming |
| 41 | + |
| 42 | +```typescript |
| 43 | +// Functions: camelCase with descriptive verbs |
| 44 | +const getUserProfile = () => {}; |
| 45 | +const validateEmailAddress = () => {}; |
| 46 | + |
| 47 | +// Types: PascalCase with clear purpose |
| 48 | +interface UserProfile extends BaseProfile {} |
| 49 | +type ApiResponse<T> = Success<T> | Error; |
| 50 | + |
| 51 | +// Constants: UPPER_SNAKE_CASE |
| 52 | +const SITE_NAME = "Next TS App"; |
| 53 | +const API_BASE_URL = "https://api.example.com"; |
| 54 | +``` |
| 55 | + |
| 56 | +## Component Patterns |
| 57 | + |
| 58 | +### Standard Component Structure |
| 59 | + |
| 60 | +```typescript |
| 61 | +import { type ReactNode } from "react"; |
| 62 | +import { cn } from "@/utils/index"; |
| 63 | + |
| 64 | +export interface ComponentProps { |
| 65 | + readonly children?: ReactNode; |
| 66 | + readonly className?: string; |
| 67 | +} |
| 68 | + |
| 69 | +export function Component(props: ComponentProps) { |
| 70 | + const { children, className, ...rest } = props; |
| 71 | + |
| 72 | + return ( |
| 73 | + <div className={cn("base-styles", className)} {...rest}> |
| 74 | + {children} |
| 75 | + </div> |
| 76 | + ); |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +### Composition Patterns |
| 81 | + |
| 82 | +```typescript |
| 83 | +// Extend existing components rather than recreate |
| 84 | +export function StyledButton(props: StyledButtonProps) { |
| 85 | + const { className, ...rest } = props; |
| 86 | + return ( |
| 87 | + <Button |
| 88 | + className={cn(baseButtonStyles, className)} |
| 89 | + {...rest} |
| 90 | + /> |
| 91 | + ); |
| 92 | +} |
| 93 | + |
| 94 | +// Use render props for complex composition |
| 95 | +<Command render={<AriaCurrentLink {...linkProps} />}> |
| 96 | + {children} |
| 97 | +</Command> |
| 98 | +``` |
| 99 | + |
| 100 | +## Import/Export Conventions |
| 101 | + |
| 102 | +### Path Aliases (Required) |
| 103 | + |
| 104 | +```typescript |
| 105 | +// Always use path aliases for internal imports |
| 106 | +import { Component } from "@/components/Component"; |
| 107 | +import { utility } from "@/utils/utility"; |
| 108 | +import { CONFIG } from "@/utils/siteConfig"; |
| 109 | + |
| 110 | +// Not: import { Component } from "../../components/Component"; |
| 111 | +``` |
| 112 | + |
| 113 | +### Import Order (Auto-sorted by Prettier) |
| 114 | + |
| 115 | +1. Built-in Node.js modules |
| 116 | +2. React/Next.js framework modules |
| 117 | +3. Third-party packages |
| 118 | +4. Internal modules (by priority): |
| 119 | + - `@/lib/*` |
| 120 | + - `@/ui/*` |
| 121 | + - `@/components/*` |
| 122 | + - `@/hooks/*` |
| 123 | + - `@/stores/*` |
| 124 | + - `@/icons/*` |
| 125 | + - `@/utils/*` |
| 126 | + - `@/styles/*` |
| 127 | + - `@/app/*` |
| 128 | +5. Relative imports |
| 129 | +6. CSS files |
| 130 | + |
| 131 | +### Export Patterns |
| 132 | + |
| 133 | +```typescript |
| 134 | +// Named exports preferred |
| 135 | +export { Component, type ComponentProps }; |
| 136 | + |
| 137 | +// Barrel exports in index files |
| 138 | +export * from "./Component"; |
| 139 | +export * from "./utils"; |
| 140 | + |
| 141 | +// Default exports only for pages and layouts |
| 142 | +export default function Page() {} |
| 143 | +``` |
| 144 | + |
| 145 | +## CSS and Styling |
| 146 | + |
| 147 | +### TailwindCSS Patterns |
| 148 | + |
| 149 | +```typescript |
| 150 | +// Use cn() utility for class composition |
| 151 | +import { cn } from "@/utils/index"; |
| 152 | + |
| 153 | +const styles = cn( |
| 154 | + "base-styles", |
| 155 | + "responsive-modifier:style", |
| 156 | + condition && "conditional-style", |
| 157 | + className, |
| 158 | +); |
| 159 | +``` |
| 160 | + |
| 161 | +### Custom CSS (when needed) |
| 162 | + |
| 163 | +```css |
| 164 | +/* BEM methodology for custom CSS */ |
| 165 | +.component__element--modifier { |
| 166 | + /* Properties in clean order (via Stylelint) */ |
| 167 | +} |
| 168 | + |
| 169 | +/* CSS variables for theming */ |
| 170 | +@theme { |
| 171 | + --color-primary: hsl(210 100% 50%); |
| 172 | + --font-sans: var(--font-inter); |
| 173 | +} |
| 174 | +``` |
| 175 | + |
| 176 | +## Accessibility Standards |
| 177 | + |
| 178 | +### Built-in ARIA Support |
| 179 | + |
| 180 | +```typescript |
| 181 | +// Proper ARIA handling in components |
| 182 | +const ariaProps = ariaLabel |
| 183 | + ? { role: "img", "aria-label": ariaLabel } |
| 184 | + : { "aria-hidden": "true", focusable: "false" }; |
| 185 | + |
| 186 | +return <svg {...ariaProps} />; |
| 187 | +``` |
| 188 | + |
| 189 | +### Semantic HTML |
| 190 | + |
| 191 | +- Use semantic HTML elements |
| 192 | +- Provide proper heading hierarchy |
| 193 | +- Include alternative text for images |
| 194 | +- Ensure keyboard navigation |
| 195 | + |
| 196 | +## Error Handling |
| 197 | + |
| 198 | +### Type-Safe Error Handling |
| 199 | + |
| 200 | +```typescript |
| 201 | +// Use Result types instead of throwing |
| 202 | +type Result<T, E = Error> = |
| 203 | + | { success: true; data: T } |
| 204 | + | { success: false; error: E }; |
| 205 | + |
| 206 | +// Graceful degradation in components |
| 207 | +if (!data) { |
| 208 | + return <div>Loading...</div>; |
| 209 | +} |
| 210 | +``` |
| 211 | + |
| 212 | +## Code Organization |
| 213 | + |
| 214 | +### Utility Functions |
| 215 | + |
| 216 | +- **Pure Functions**: No side effects when possible |
| 217 | +- **Single Responsibility**: Each function has one clear purpose |
| 218 | +- **Type Guards**: Proper TypeScript type narrowing |
| 219 | +- **Immutable**: Work with immutable data structures |
| 220 | + |
| 221 | +### Component Organization |
| 222 | + |
| 223 | +- **Small Components**: Focus on single responsibility |
| 224 | +- **Composition**: Build complex UI through composition |
| 225 | +- **Props Interface**: Clear, readonly prop definitions |
| 226 | +- **Default Exports**: Only for pages, use named exports elsewhere |
| 227 | + |
| 228 | +## Performance Considerations |
| 229 | + |
| 230 | +### Bundle Optimization |
| 231 | + |
| 232 | +- **Dynamic Imports**: Use for large components |
| 233 | +- **Image Optimization**: Use Next.js Image component |
| 234 | +- **Bundle Analysis**: Regular bundle size monitoring |
| 235 | + |
| 236 | +### React Patterns |
| 237 | + |
| 238 | +- **Functional Components**: Use hooks over class components |
| 239 | +- **Memo Usage**: Only when performance measurement shows benefit |
| 240 | +- **Avoid Premature Optimization**: Profile before optimizing |
| 241 | + |
| 242 | +## Quality Assurance |
| 243 | + |
| 244 | +### ESLint Rules Enforced |
| 245 | + |
| 246 | +- Strict TypeScript checking |
| 247 | +- React hooks validation |
| 248 | +- Import organization |
| 249 | +- Accessibility compliance |
| 250 | +- No unused variables |
| 251 | +- Consistent naming |
| 252 | + |
| 253 | +### Automated Formatting |
| 254 | + |
| 255 | +- **Prettier**: Handles all code formatting |
| 256 | +- **Import Sorting**: Automatic import organization |
| 257 | +- **TailwindCSS**: Class sorting for consistency |
| 258 | + |
| 259 | +### Git Practices |
| 260 | + |
| 261 | +- **Conventional Commits**: Enforced commit message format |
| 262 | +- **Pre-commit Hooks**: Automatic formatting and spell checking |
| 263 | +- **Linear History**: Prefer rebase over merge commits |
| 264 | + |
| 265 | +This coding style ensures consistency, maintainability, and high code quality across the entire project. |
0 commit comments