glam/frontend/COMMANDS.md

GLAM Frontend - Quick Command Reference

🚀 Getting Started

# Navigate to project
cd /Users/kempersc/apps/glam/frontend

# Install dependencies (first time only)
npm install

# Start development server
npm run dev
# → Opens http://localhost:5173

---

🧪 Testing Commands

# Run tests in watch mode (recommended during development)
npm run test

# Run tests with interactive UI
npm run test:ui
# → Opens http://localhost:51204/__vitest__/

# Run tests once (CI/CD)
npm run test:run

# Run tests with coverage report
npm run test:coverage
# → Generates HTML report in coverage/

---

🔨 Build Commands

# Type check
npx tsc --noEmit

# Build for production
npm run build
# → Output in dist/

# Preview production build
npm run preview
# → Opens http://localhost:4173

# Lint code
npm run lint

# Format code (if prettier script added)
npx prettier --write src/

---

📦 Package Management

# Install new dependency
npm install <package>

# Install dev dependency
npm install -D <package>

# Update dependencies
npm update

# Check for outdated packages
npm outdated

# Audit for security issues
npm audit

---

🔍 Debugging

# Check Node.js version
node --version

# Check npm version
npm --version

# Clear npm cache
npm cache clean --force

# Reinstall node_modules
rm -rf node_modules package-lock.json
npm install

# Check for TypeScript errors
npx tsc --noEmit

---

📊 Project Analysis

# Count lines of code
find src -name "*.ts" -o -name "*.tsx" | xargs wc -l

# Find TODO comments
rg "TODO|FIXME" src/

# List all test files
find tests -name "*.test.ts"

# Check bundle size (after build)
npm run build
ls -lh dist/assets/

---

🧹 Cleanup

# Remove build artifacts
rm -rf dist/

# Remove test coverage
rm -rf coverage/

# Remove node_modules (nuclear option)
rm -rf node_modules/

# Clean everything and reinstall
rm -rf node_modules/ dist/ coverage/
npm install

---

🔧 Development Workflow

Starting a New Feature

# 1. Create feature branch (if using git)
git checkout -b feature/graph-visualization

# 2. Start dev server
npm run dev

# 3. Open test UI in another terminal
npm run test:ui

# 4. Create your files
touch src/components/visualizations/GraphView/ForceDirectedGraph.tsx
touch tests/unit/force-directed-graph.test.tsx

# 5. Write tests first (TDD)
# Edit tests/unit/force-directed-graph.test.tsx

# 6. Implement feature
# Edit src/components/visualizations/GraphView/ForceDirectedGraph.tsx

# 7. Verify tests pass
npm run test:run

# 8. Check types
npx tsc --noEmit

# 9. Lint
npm run lint

---

🎯 Most Used Commands (Quick Reference)

# Development
npm run dev              # Start dev server
npm run test            # Run tests (watch mode)

# Before commit
npm run test:run        # Run all tests
npx tsc --noEmit       # Check types
npm run lint           # Lint code

# Production
npm run build          # Build for production
npm run preview        # Preview build

---

🔗 Useful URLs

# Development Server
http://localhost:5173

# Vitest UI
http://localhost:51204/__vitest__/

# Preview Server  
http://localhost:4173

# Backend API (when running)
http://localhost:8000

---

📁 Important Directories

src/                    # Source code
├── components/        # React components
├── lib/              # Core libraries
├── hooks/            # Custom React hooks
├── stores/           # Zustand stores
├── types/            # TypeScript types
├── pages/            # Page components
└── styles/           # Global styles

tests/                 # Test files
├── unit/             # Unit tests
├── integration/      # Integration tests
└── e2e/              # E2E tests

docs/plan/frontend/   # Documentation
dist/                 # Build output (generated)
coverage/             # Coverage reports (generated)
node_modules/         # Dependencies (generated)

---

🆘 Troubleshooting

Port already in use

# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

# Or use different port
npm run dev -- --port 3000

Module not found

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Type errors

# Check TypeScript version
npm list typescript

# Rebuild TypeScript
npx tsc --noEmit

Test failures

# Clear test cache
npx vitest --run --clearCache

# Run specific test
npm run test -- tests/unit/rdf-parser.test.ts

# Debug test
npm run test:ui
# Then click on test to see details

Vite issues

# Clear Vite cache
rm -rf node_modules/.vite

# Restart dev server
npm run dev

---

🎓 Learning Commands

# View package documentation
npm docs <package-name>

# View package homepage
npm home <package-name>

# View package repository
npm repo <package-name>

# List installed packages
npm list

# List outdated packages
npm outdated

# Check package info
npm info <package-name>

---

📝 Git Commands (if using version control)

# Check status
git status

# Stage changes
git add src/ tests/

# Commit
git commit -m "feat: add force-directed graph component"

# Push
git push origin feature/graph-visualization

# View log
git log --oneline --graph --all

---

🔄 Continuous Integration

# Run full CI check locally
npm run test:run && \
npx tsc --noEmit && \
npm run lint && \
npm run build

# Single line version
npm run test:run && npx tsc --noEmit && npm run lint && npm run build

---

💡 Pro Tips

# Watch mode for TypeScript
npx tsc --noEmit --watch

# Parallel test execution
npm run test -- --threads

# Test specific file pattern
npm run test -- --grep="parser"

# Update snapshots (if using snapshot tests)
npm run test -- --update

# Run tests in specific directory
npm run test -- tests/unit/

# Generate coverage for specific files
npm run test:coverage -- --include="src/lib/**"

---

Quick Access:

• Documentation: /docs/plan/frontend/
• Session Summary: SESSION_SUMMARY.md
• Progress Dashboard: PROGRESS_DASHBOARD.md
• README: README.md

Need Help?

• Check README.md for full documentation
• Review SESSION_SUMMARY.md for implementation details
• Read /docs/plan/frontend/07-quick-start-guide.md for setup

---

Last Updated: November 22, 2024