From b5d3cfdd9a976a3c6484d6a4975d87ad2ac0cbac Mon Sep 17 00:00:00 2001 From: Arjan Singh <1598641+arjansingh@users.noreply.github.com> Date: Thu, 28 Aug 2025 16:21:03 -0700 Subject: [PATCH] chore: claude repo setup and claude.md updates (#5248) * chore: add setup_repo command for claude code * docs: update CLAUDE.md with monorepo guidance * chore: ignore CLAUDE.local.md * ci: add .nvmrc enforce v22, the current lts release * chore: node 24 it is! * fix .claude/commands/setup_repo.md Co-authored-by: Alexander Brown * fix: .claude/commands/setup_repo.md Co-authored-by: Alexander Brown * fix: update CLAUDE.md Co-authored-by: Alexander Brown --------- Co-authored-by: Alexander Brown --- .claude/commands/setup_repo.md | 158 +++++++++++++++++++++++++++++++++ .gitignore | 1 + .nvmrc | 1 + CLAUDE.md | 42 +++++++-- 4 files changed, 196 insertions(+), 6 deletions(-) create mode 100644 .claude/commands/setup_repo.md create mode 100644 .nvmrc diff --git a/.claude/commands/setup_repo.md b/.claude/commands/setup_repo.md new file mode 100644 index 000000000..48605271e --- /dev/null +++ b/.claude/commands/setup_repo.md @@ -0,0 +1,158 @@ +# Setup Repository + +Bootstrap the ComfyUI Frontend monorepo with all necessary dependencies and verification checks. + +## Overview + +This command will: +1. Install pnpm package manager (if not present) +2. Install all project dependencies +3. Verify the project builds successfully +4. Run unit tests to ensure functionality +5. Start development server to verify frontend boots correctly + +## Prerequisites Check + +First, let's verify the environment: + +```bash +# Check Node.js version (should be >= 24) +node --version + +# Check if we're in a git repository +git status +``` + +## Step 1: Install pnpm + +```bash +# Check if pnpm is already installed +pnpm --version 2>/dev/null || { + echo "Installing pnpm..." + npm install -g pnpm +} + +# Verify pnpm installation +pnpm --version +``` + +## Step 2: Install Dependencies + +```bash +# Install all dependencies using pnpm +echo "Installing project dependencies..." +pnpm install + +# Verify node_modules exists and has packages +ls -la node_modules | head -5 +``` + +## Step 3: Verify Build + +```bash +# Run TypeScript type checking +echo "Running TypeScript checks..." +pnpm typecheck + +# Build the project +echo "Building project..." +pnpm build + +# Verify dist folder was created +ls -la dist/ +``` + +## Step 4: Run Unit Tests + +```bash +# Run unit tests +echo "Running unit tests..." +pnpm test:unit + +# If tests fail, show the output and stop +if [ $? -ne 0 ]; then + echo "❌ Unit tests failed. Please fix failing tests before continuing." + exit 1 +fi + +echo "✅ Unit tests passed successfully" +``` + +## Step 5: Verify Development Server + +```bash +# Start development server in background +echo "Starting development server..." +pnpm dev & +SERVER_PID=$! + +# Wait for server to start (check for port 5173 or similar) +echo "Waiting for server to start..." +sleep 10 + +# Check if server is running +if curl -s http://localhost:5173 > /dev/null 2>&1; then + echo "✅ Development server started successfully at http://localhost:5173" + + # Kill the background server + kill $SERVER_PID + wait $SERVER_PID 2>/dev/null +else + echo "❌ Development server failed to start or is not accessible" + kill $SERVER_PID 2>/dev/null + wait $SERVER_PID 2>/dev/null + exit 1 +fi +``` + +## Step 6: Final Verification + +```bash +# Run linting to ensure code quality +echo "Running linter..." +pnpm lint + +# Show project status +echo "" +echo "🎉 Repository setup complete!" +echo "" +echo "Available commands:" +echo " pnpm dev - Start development server" +echo " pnpm build - Build for production" +echo " pnpm test:unit - Run unit tests" +echo " pnpm test:component - Run component tests" +echo " pnpm typecheck - Run TypeScript checks" +echo " pnpm lint - Run ESLint" +echo " pnpm format - Format code with Prettier" +echo "" +echo "Next steps:" +echo "1. Run 'pnpm dev' to start developing" +echo "2. Open http://localhost:5173 in your browser" +echo "3. Check README.md for additional setup instructions" +``` + +## Troubleshooting + +If any step fails: + +1. **pnpm installation fails**: Try using `curl -fsSL https://get.pnpm.io/install.sh | sh -` +2. **Dependencies fail to install**: Try clearing cache with `pnpm store prune` and retry +3. **Build fails**: Check for TypeScript errors and fix them first +4. **Tests fail**: Review test output and fix failing tests +5. **Dev server fails**: Check if port 5173 is already in use + +## Manual Verification Steps + +After running the setup, manually verify: + +1. **Dependencies installed**: `ls node_modules | wc -l` should show many packages +2. **Build artifacts**: `ls dist/` should show built files +3. **Server accessible**: Open http://localhost:5173 in browser +4. **Hot reload works**: Edit a file and see changes reflect + +## Environment Requirements + +- Node.js >= 24 +- Git repository +- Internet connection for package downloads +- Available ports (typically 5173 for dev server) \ No newline at end of file diff --git a/.gitignore b/.gitignore index aa68ddd07..db0b8454c 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ dist-ssr *.local # Claude configuration .claude/*.local.json +CLAUDE.local.md # Editor directories and files .vscode/* diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 000000000..a45fd52cc --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +24 diff --git a/CLAUDE.md b/CLAUDE.md index 922d1f853..0aee6cc32 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,22 +1,52 @@ # ComfyUI Frontend Project Guidelines +## Repository Setup + +For first-time setup, use the Claude command: +``` +/setup_repo +``` +This bootstraps the monorepo with dependencies, builds, tests, and dev server verification. + +**Prerequisites:** Node.js >= 24, Git repository, available ports (5173, 6006) + ## Quick Commands - `pnpm`: See all available commands +- `pnpm dev`: Start development server (port 5173, via nx) - `pnpm typecheck`: Type checking -- `pnpm lint`: Linting +- `pnpm build`: Build for production (via nx) +- `pnpm lint`: Linting (via nx) - `pnpm format`: Prettier formatting - `pnpm test:component`: Run component tests with browser environment - `pnpm test:unit`: Run all unit tests +- `pnpm test:browser`: Run E2E tests via Playwright - `pnpm test:unit -- tests-ui/tests/example.test.ts`: Run single test file +- `pnpm storybook`: Start Storybook development server (port 6006) +- `pnpm knip`: Detect unused code and dependencies + +## Monorepo Architecture + +The project now uses **Nx** for build orchestration and task management: + +- **Task Orchestration**: Commands like `dev`, `build`, `lint`, and `test:browser` run via Nx +- **Caching**: Nx provides intelligent caching for faster rebuilds +- **Configuration**: Managed through `nx.json` with plugins for ESLint, Storybook, Vite, and Playwright +- **Dependencies**: Nx handles dependency graph analysis and parallel execution + +Key Nx features: +- Build target caching and incremental builds +- Parallel task execution across the monorepo +- Plugin-based architecture for different tools ## Development Workflow -1. Make code changes -2. Run tests (see subdirectory CLAUDE.md files) -3. Run typecheck, lint, format -4. Check README updates -5. Consider docs.comfy.org updates +1. **First-time setup**: Run `/setup_repo` Claude command +2. Make code changes +3. Run tests (see subdirectory CLAUDE.md files) +4. Run typecheck, lint, format +5. Check README updates +6. Consider docs.comfy.org updates ## Git Conventions