Skip to content

Commit cd75e80

Browse files
committed
refactor(components): ♻️ simplify NextImage component interface
- Remove blur hash functionality and related props - Update dependencies: ESLint, TypeScript, Prettier, Tailwind - Move Sentry from dependencies to devDependencies - Add WCAG to spell check dictionary for accessibility
1 parent 732ef51 commit cd75e80

File tree

11 files changed

+2010
-642
lines changed

11 files changed

+2010
-642
lines changed

CLAUDE.md

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Development Commands
6+
7+
### Core Development
8+
9+
- `pnpm dev` - Start development server with Turbopack
10+
- `pnpm build` - Build production version
11+
- `pnpm start` - Start production server
12+
- `pnpm build:start` - Build and start production server
13+
14+
### Code Quality & Linting
15+
16+
- `pnpm lint` - Run all linters (Prettier, ESLint, TypeScript, Knip, Markdown, Spell check, CSS)
17+
- `pnpm lint:types` - TypeScript type checking
18+
- `pnpm lint:eslint` - ESLint linting
19+
- `pnpm lint:prettier` - Prettier formatting check
20+
- `pnpm fix` - Auto-fix ESLint issues
21+
- `pnpm fix:prettier` - Auto-format with Prettier
22+
23+
### Testing & Analysis
24+
25+
- `pnpm build:analyze` - Bundle analysis with webpack-bundle-analyzer
26+
- `pnpm build:sourcemap` - Build with source maps and analysis
27+
- `pnpm lint:knip` - Check for unused dependencies, exports, and types
28+
29+
### Maintenance
30+
31+
- `pnpm clean` - Clean build artifacts and caches
32+
- `pnpm check:update` - Interactive dependency updates
33+
- `pnpm check:packages` - Check for duplicate packages
34+
35+
## Architecture Overview
36+
37+
### Technology Stack
38+
39+
- **Framework**: Next.js 15 with App Router
40+
- **Runtime**: React 19 with TypeScript in strict mode
41+
- **Styling**: TailwindCSS 4 with PostCSS
42+
- **Build Tool**: Turbopack (development), Webpack (production)
43+
- **Package Manager**: pnpm
44+
- **PWA**: Serwist service worker
45+
- **Error Tracking**: Sentry (configured but commented out)
46+
- **Development Tools**: Turbo monorepo tooling
47+
48+
### Project Structure
49+
50+
- `src/app/` - Next.js App Router pages and layouts
51+
- `src/components/` - Reusable React components
52+
- `src/ui/` - Root-level UI components (Providers, TailwindIndicator)
53+
- `src/utils/` - Utility functions and configurations
54+
- `src/styles/` - Global styles and font configurations
55+
- `src/icons/` - SVG icon system with automated builds
56+
- `scripts/` - Build scripts and automation tools
57+
58+
### Key Configurations
59+
60+
- **TypeScript**: Strict mode enabled with path aliases (@/components/_, @/utils/_, etc.)
61+
- **ESLint**: Comprehensive setup with React, TypeScript, accessibility, and Next.js rules
62+
- **Build**: Turbopack for development, configurable Sentry and bundle analysis
63+
- **PWA**: Service worker disabled in development/local, enabled in production
64+
65+
### Development Patterns
66+
67+
- Uses App Router with TypeScript strict mode
68+
- Path aliases for clean imports (@/components/, @/utils/, etc.)
69+
- Automated icon building system
70+
- Comprehensive linting with Turbo pipeline orchestration
71+
- Environment-specific configurations (development vs production)
72+
73+
### Environment Variables
74+
75+
Required environment variables are validated at build time unless `SKIP_ENV_VALIDATION=true`.
76+
77+
### Code Quality Tools
78+
79+
The project uses a comprehensive toolchain:
80+
81+
- ESLint with React, TypeScript, and accessibility rules
82+
- Prettier for code formatting
83+
- Stylelint for CSS
84+
- Markdownlint for documentation
85+
- CSpell for spell checking
86+
- Knip for dead code elimination
87+
- Commitlint for conventional commits
88+
89+
## Project Documentation
90+
91+
Important documentation files are maintained in the `docs/` directory. When starting work on this project, please load these memory files:
92+
93+
- **`docs/project_overview.md`** - Project purpose, tech stack, and architecture
94+
- **`docs/suggested_commands.md`** - All development commands organized by category
95+
- **`docs/code_style_conventions.md`** - TypeScript, React, and styling standards
96+
- **`docs/frontend_rules.md`** - Comprehensive accessibility and frontend code quality rules
97+
- **`docs/task_completion_checklist.md`** - Quality gates and completion requirements
98+
- **`docs/project_structure.md`** - Directory layout and key files explanation
99+
100+
These files contain essential information for understanding and working with the codebase effectively.

cspell.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
"timelessco",
4949
"unenc",
5050
"unrs",
51-
"wbmp"
51+
"wbmp",
52+
"WCAG"
5253
]
5354
}

docs/code_style_conventions.md

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
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

Comments
 (0)