# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a React + TypeScript + Vite project called "perfviz" - a modern web application built with the latest versions of React (19.1.0), TypeScript (5.8.3), and Vite (7.0.4). ## Development Commands - **Start development server**: `npm run dev` - Runs Vite dev server with HMR on http://localhost:5173/ - **Build for production**: `npm run build` - TypeScript compilation followed by Vite build - **Lint code**: `npm run lint` - Run ESLint on the entire codebase - **Preview production build**: `npm run preview` - Preview the production build locally ## Architecture ### Build System - **Vite** as the build tool with React plugin for Fast Refresh - **ES modules** configuration (`"type": "module"` in package.json) - **Bundler module resolution** with TypeScript extensions allowed in imports ### TypeScript Configuration - **Dual TypeScript configs**: - `tsconfig.app.json` for application code (`src/` directory) - `tsconfig.node.json` for build tooling (Vite config) - **Strict TypeScript** with unused locals/parameters checking enabled - **React JSX transform** (`react-jsx`) for React 19+ compatibility ### Code Quality - **ESLint** with TypeScript support and React-specific rules: - React Hooks rules for proper hooks usage - React Refresh rules for HMR compatibility - TypeScript recommended rules - **Globals configured** for browser environment ### Application Structure - **Entry point**: `src/main.tsx` renders the App component in React 19 StrictMode - **Root component**: `src/App.tsx` contains the main application logic - **3D Viewer**: `src/BabylonViewer.tsx` React component wrapping Babylon.js 3D scene - **Styling**: CSS modules with `src/index.css` and `src/App.css` - **Assets**: Static assets in `public/` and component assets in `src/assets/` ## Key Dependencies - **React 19.1.0** with modern features and concurrent rendering - **TypeScript 5.8.3** with latest language features - **Vite 7.0.4** for fast development and optimized builds - **ESLint 9.30.1** with typescript-eslint for code quality - **BabylonJS 8.21.1** for 3D graphics and visualization ## Development Notes - The project uses **React 19's new JSX transform** and concurrent features - **HMR (Hot Module Replacement)** is enabled through Vite's React plugin - **Strict mode** is enabled in development for better debugging - **Browser targets** are ES2022+ for modern JavaScript features - **Lines of code per function**: Functions should not exceed 50 lines. If they do, add a comment `//@LONGFUNCTION` to indicate this. - **Lines of code per function**: Functions should have a hard limit of 200 lines, if we exceed this, prompt with approaches to refactor. - **File size limits**: TypeScript files should not exceed 100 lines. If a file is over 100 lines but functions are under 150 lines, add `//@LONGFILE` comment at the top and warn the user. Files over 250 lines must be prompted to refactor. - **Imports**: Ensure all imports are used, remove unused imports, and ensure imports are alphabetized and at the top of the file. - **Code Style**: Follow consistent coding style with mostly widely used indentation, spacing, and comments for clarity. - **Error Handling**: Use try/catch blocks for asynchronous operations and provide meaningful error messages. - **CSS versus Styled Components**: Use CSS modules for styling instead of styled-components for better performance and simplicity. ## Babylon.js Integration - **Version**: Using Babylon.js 8.21.1 (modern version 8+) - **Camera Management**: Use `scene.activeCamera` instead of deprecated `camera.attachToCanvas()` - **ArcRotateCamera Controls**: Use `camera.attachControl(canvas, true)` for mouse interaction - **Scene Setup**: Cameras, lights, and meshes are added directly to the scene object - **Engine Integration**: Engine handles canvas interaction and render loop - **React Integration**: Proper cleanup with engine disposal in useEffect return function - **Version-Specific Documentation**: ALWAYS check Babylon.js documentation for version 8.21.1 specifically to avoid deprecated methods and ensure current API usage - **API Verification**: Before suggesting any Babylon.js code, verify method signatures and availability in the current version -