perfViz/CLAUDE.md

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
• CSS: Use CSS modules for styling components, avoid inline styles for better performance and maintainability