Skip to content
This repository was archived by the owner on May 29, 2026. It is now read-only.
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 128 additions & 0 deletions .cursor/rules/development-workflow.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
---
description:
globs:
alwaysApply: false
---
# Development Workflow and Optimization Tools

## Package Management
ZapDev uses **Bun** as the primary package manager. Always use `bun` commands instead of npm/yarn for consistency and performance.

## Available Scripts

### Core Development
```bash
bun run dev # Start development server
bun run build # Production build
bun run start # Start production server
bun run lint # ESLint checking
```

### Performance and Analysis
```bash
bun run perf-check # Comprehensive performance analysis
bun run bundle-analyze # Visual bundle size analysis
bun run lighthouse # Lighthouse performance audit
bun run analyze # Build with bundle analyzer
```

### Optimization Scripts
```bash
bun run optimize-bundle # Bundle optimization
bun run remove-console # Remove console logs
bun run fix-chat # Chat API fixes
bun run fix-db # Database fixes
```

## Performance Analysis Workflow

### 1. Regular Performance Checks
- **Tool**: [scripts/performance-check.js](mdc:scripts/performance-check.js)
- **Usage**: `bun run perf-check`
- **Analyzes**: Bundle size, CSS performance, image optimization, dependencies

### 2. Bundle Analysis
- **Configuration**: [next.config.mjs](mdc:next.config.mjs) with `ANALYZE=true`
- **Visual Analysis**: Opens webpack-bundle-analyzer in browser
- **Identifies**: Large dependencies, unused code, optimization opportunities

### 3. Lighthouse Auditing
- **Command**: `bun run lighthouse`
- **Output**: HTML report in project root
- **Metrics**: Performance, Accessibility, Best Practices, SEO

## Code Quality Standards

### TypeScript Configuration
- **Strict Mode**: Enabled for type safety
- **Build Errors**: Ignored during development for faster iteration
- **ESLint**: Ignored during builds for deployment speed

### Performance Optimization Guidelines
1. **Always check device capabilities** using [components/performance-optimizer.tsx](mdc:components/performance-optimizer.tsx)
2. **Use fallback systems** for critical features like WebContainer
3. **Implement loading states** with [components/loading-fallback.tsx](mdc:components/loading-fallback.tsx)
4. **Optimize for mobile first** with responsive performance classes

## Build Optimization

### Next.js Configuration
- **CSS Optimization**: `optimizeCss: true`
- **Package Imports**: Tree-shaking for framer-motion, lucide-react
- **Console Removal**: Automatic in production builds
- **Image Optimization**: Modern formats (AVIF, WebP)

### Bundle Size Targets
- **Total Bundle**: < 5MB for optimal performance
- **Initial Load**: < 1MB for fast first paint
- **Individual Chunks**: < 500KB for efficient loading

## Development Environment Setup

### Required Dependencies
```json
{
"runtime": "bun",
"node_version": ">=18.0.0",
"package_manager": "bun"
}
```

### Environment Variables
- **NEXT_PUBLIC_APP_URL**: Production domain for metadata
- **ANALYZE**: Set to "true" for bundle analysis
- **NODE_ENV**: Development/production environment

## Testing Strategy

### Performance Testing
1. **Build Analysis**: `bun run build && bun run perf-check`
2. **Lighthouse**: `bun run lighthouse` after starting dev server
3. **Bundle Size**: `bun run bundle-analyze` for visual analysis

### Device Testing
- **Low-end Device Simulation**: DevTools performance throttling
- **Network Simulation**: Slow 3G/2G connection testing
- **Reduced Motion**: Test with accessibility preferences

## Deployment Checklist

1. ✅ **Performance Check**: `bun run perf-check` passes
2. ✅ **Bundle Analysis**: No unexpected large dependencies
3. ✅ **Lighthouse Score**: >90 for Performance, Accessibility, SEO
4. ✅ **TypeScript**: No build-breaking errors
5. ✅ **Environment Variables**: All production vars configured
6. ✅ **SEO Metadata**: Sitemap and robots.txt generated
7. ✅ **Fallback Systems**: WebContainer fallbacks tested

## Monitoring and Maintenance

### Regular Tasks
- **Weekly**: Run performance checks
- **Monthly**: Update dependencies and analyze bundle changes
- **Quarterly**: Comprehensive Lighthouse audit and optimization review

### Performance Regression Prevention
- **Bundle Size Monitoring**: Alert if total size exceeds 5MB
- **Core Web Vitals**: Monitor LCP, FID, CLS metrics
- **Error Tracking**: Monitor WebContainer fallback usage rates
73 changes: 73 additions & 0 deletions .cursor/rules/performance-optimization.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
description: perfomance
globs:
alwaysApply: false
---
# Performance Optimization Guidelines

## Core Performance Principles

ZapDev is optimized for **all device types**, from high-end computers to low-end mobile devices. Every feature must work reliably across different performance capabilities.

## Performance Monitoring Components

### PerformanceOptimizer Component
- **Location**: [components/performance-optimizer.tsx](mdc:components/performance-optimizer.tsx)
- **Purpose**: Automatically detects device capabilities and applies appropriate optimizations
- **Key Features**:
- Device capability detection (CPU cores, RAM, connection speed)
- Automatic animation disabling on low-end devices
- Reduced motion support for accessibility
- Performance monitoring with Largest Contentful Paint tracking

### CSS Performance Standards
- **Location**: [app/globals.css](mdc:app/globals.css)
- **Optimizations Applied**:
- Infinite animations converted to user-triggered only
- Backdrop-filter reduced from 10px to 4px blur
- Glass effects optimized for mobile (2px blur on small screens)
- Performance utilities added (.reduce-motion, .performance-mode)
- Responsive performance classes for low-end devices

## Bundle Optimization

### Next.js Configuration
- **Location**: [next.config.mjs](mdc:next.config.mjs)
- **Key Settings**:
- `optimizeCss: true` - CSS optimization enabled
- `optimizePackageImports` - Tree-shaking for framer-motion and lucide-react
- `removeConsole: true` in production
- Modern image formats (AVIF, WebP) configured

### Performance Monitoring Scripts
- **Performance Check**: [scripts/performance-check.js](mdc:scripts/performance-check.js)
- **Usage**: `bun run perf-check`
- **Analyzes**: Bundle size, CSS optimization, image optimization, dependencies

## Performance Best Practices

1. **Always use performance-optimized components** from [components/loading-fallback.tsx](mdc:components/loading-fallback.tsx)
2. **Implement lazy loading** for images and heavy components
3. **Use reduced motion classes** for accessibility
4. **Test on low-end devices** using performance mode
5. **Monitor bundle size** regularly with `bun run bundle-analyze`

## Device Capability Detection

```typescript
// Example from PerformanceOptimizer
const isLowEndDevice = () => {
const hardwareConcurrency = navigator.hardwareConcurrency || 1;
const deviceMemory = (navigator as any).deviceMemory || 1;
const connection = (navigator as any).connection;

return hardwareConcurrency < 4 || deviceMemory < 4 || isSlowConnection;
};
```

## Animation Guidelines

- **Infinite animations**: Only on user interaction (hover/focus)
- **Heavy effects**: Disabled automatically on low-end devices
- **Glass effects**: Reduced blur on mobile devices
- **Transitions**: Maximum 0.3s duration for responsiveness
143 changes: 143 additions & 0 deletions .cursor/rules/seo-and-accessibility.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
---
description: SEO
globs:
alwaysApply: false
---
# SEO and Accessibility Standards

## SEO Architecture

ZapDev implements comprehensive SEO optimization for maximum search engine visibility and user accessibility.

## Metadata Implementation
- **Layout**: [app/layout.tsx](mdc:app/layout.tsx)
- **Structured Data**: JSON-LD schema for SoftwareApplication
- **Open Graph**: Complete social media optimization
- **Twitter Cards**: Summary with large image support

## Site Structure

### Sitemap Generation
- **Dynamic Sitemap**: [app/sitemap.ts](mdc:app/sitemap.ts)
- **Auto-generated**: Updates with page changes
- **Priority System**: Homepage (1.0) → Chat (0.9) → Pricing (0.8)

### Robots.txt
- **Location**: [public/robots.txt](mdc:public/robots.txt)
- **Crawl Control**: Allows main sections, blocks sensitive areas
- **Sitemap Reference**: Points to dynamic sitemap.xml

### Web Manifest
- **PWA Support**: [public/site.webmanifest](mdc:public/site.webmanifest)
- **App-like Experience**: Standalone display mode
- **Shortcuts**: Quick access to Chat and Pricing
- **Icons**: Multiple sizes for all devices

## Technical SEO Features

### Performance Optimization
```typescript
// From layout.tsx
export const metadata: Metadata = {
title: {
default: 'ZapDev - Build Amazing Apps with AI',
template: '%s | ZapDev', // SEO-friendly title templates
},
robots: {
index: true,
follow: true,
googleBot: {
'max-image-preview': 'large',
'max-snippet': -1,
},
},
};
```

### Resource Preloading
- **DNS Prefetch**: API endpoints (api.groq.com, openrouter.ai)
- **Preconnect**: Google Fonts
- **Critical Resources**: Favicon and core assets

## Accessibility Standards

### Color and Contrast
- **WCAG AA Compliance**: Minimum 4.5:1 contrast ratio
- **Theme Support**: Both dark and light themes accessible
- **Color Independence**: No information conveyed by color alone

### Motion and Animation
- **Reduced Motion**: Respects `prefers-reduced-motion: reduce`
- **Performance Mode**: Auto-disables animations on low-end devices
- **User Control**: Animations can be disabled via system preferences

### Keyboard Navigation
- **Focus Management**: Clear focus indicators on all interactive elements
- **Tab Order**: Logical navigation sequence
- **Focus Rings**: Visible 2px outline using brand colors

### Screen Reader Support
- **Semantic HTML**: Proper heading hierarchy (h1 → h2 → h3)
- **ARIA Labels**: Descriptive labels for complex interactions
- **Role Attributes**: `role="main"` for primary content areas
- **Alt Text**: Descriptive alternative text for all images

## Content Strategy

### Structured Data Schema
```json
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "ZapDev",
"applicationCategory": "DeveloperApplication",
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
}
}
```

### Meta Tags Best Practices
- **Description Length**: 150-160 characters for optimal display
- **Keyword Strategy**: Focus on AI development, no-code, app building
- **Local SEO**: Not applicable (global SaaS product)

## Performance SEO

### Core Web Vitals Optimization
- **LCP Target**: < 2.5 seconds
- **FID Target**: < 100 milliseconds
- **CLS Target**: < 0.1
- **Performance Monitoring**: Built into [components/performance-optimizer.tsx](mdc:components/performance-optimizer.tsx)

### Image Optimization
- **Modern Formats**: WebP and AVIF support configured
- **Lazy Loading**: `loading="lazy"` for non-critical images
- **Responsive Images**: Multiple sizes for different devices
- **Alt Text**: Required for all images

## Monitoring and Testing

### Available Tools
```bash
# Performance analysis
bun run perf-check

# Lighthouse audit
bun run lighthouse

# Bundle analysis
bun run bundle-analyze
```

### SEO Checklist
- ✅ Structured data implemented
- ✅ Meta tags optimized
- ✅ Sitemap.xml auto-generated
- ✅ Robots.txt configured
- ✅ PWA manifest included
- ✅ Performance optimized
- ✅ Accessibility compliance
- ✅ Mobile-first responsive design
Loading