# Community Rule A Next.js application for community decision-making and governance documentation. ## πŸš€ Getting Started Run the development server: ```bash npm run dev ``` Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. ## πŸ§ͺ Testing Framework This project uses a simplified, component‑first testing model: - **Component tests (Vitest + RTL)** live in `tests/components/` with a single file per component. - **E2E tests (Playwright)** cover critical user journeys and visual regression. ### Quick Test Commands ```bash # All component tests with coverage npm test # Component tests only (new structure) npm run test:component # E2E tests only npm run test:e2e ``` ### Test Coverage - βœ… **428 Unit Tests** (94.88% coverage - exceeds 85% target) - βœ… **92 E2E Tests** across 4 browsers - βœ… **23 Visual Regression Tests** per browser - βœ… **Performance Budgets** with Lighthouse CI - βœ… **WCAG 2.1 AA Compliance** with automated testing - βœ… **Bundle Analysis** with automated monitoring - βœ… **Web Vitals Tracking** with real-time metrics ### CI/CD Pipeline - **Gitea Actions** with 7 parallel jobs - **Cross-browser testing** (Chromium, Firefox, WebKit, Mobile) - **Visual regression testing** - **Performance monitoring** - **Code coverage reporting** πŸ“– **For detailed testing documentation, see `docs/TESTING_GUIDE.md` and [docs/README.md](docs/README.md)** ## ⚑ Performance Optimizations This project includes comprehensive performance optimizations for sub-2-second load times: ### Frontend Optimizations - **βœ… Code Splitting**: Dynamic imports for non-critical components - **βœ… React.memo**: Applied to all 30+ components to prevent unnecessary re-renders - **βœ… Image Optimization**: Enhanced `next/image` with lazy loading and blur placeholders - **βœ… Font Optimization**: Preloading and fallbacks for all fonts - **βœ… Bundle Analysis**: Real-time monitoring with performance budgets - **βœ… Error Boundaries**: Comprehensive error handling ### Performance Monitoring ```bash # Individual monitoring tools npm run bundle:analyze # Analyze bundle sizes and budgets npm run performance:monitor # Performance metrics and Lighthouse CI npm run web-vitals:track # Core Web Vitals tracking # Comprehensive testing npm run test:performance # All performance tests npm run monitor:all # All monitoring tools ``` ### Performance Targets - **Bundle Size**: <250KB gzipped (currently 101KB) βœ… - **Core Web Vitals**: All metrics in "Good" range βœ… - **Lighthouse Score**: >90 on all critical pages βœ… - **Load Time**: <2 seconds on 3G connections βœ… ## πŸ“š Storybook Development This project includes Storybook for component development and documentation. The setup automatically detects the environment and applies the appropriate configuration. ### Local Development For local Storybook development: ```bash npm run storybook:local # or simply npm run storybook ``` This will: - Start Storybook at `http://localhost:6006` - Use relative paths for assets (no base path) ### GitHub Pages Deployment For GitHub Pages deployment with base path: ```bash npm run storybook:build:github ``` This will: - Build Storybook with `/communityrulestorybook/` base path - Generate files ready for GitHub Pages deployment ### CI/CD Integration The CI pipeline automatically uses the GitHub Pages configuration when building Storybook. ### Configuration The Storybook configuration automatically detects the environment: - **Local development**: No base path, relative assets - **CI/Production**: Base path `/communityrulestorybook/` for GitHub Pages ## πŸ“‹ Available Scripts ### Development - `npm run dev` - Start Next.js development server - `npm run build` - Build Next.js application for production - `npm run start` - Start Next.js production server ### Testing - `npm test` - Run all component tests with coverage - `npm run test:component` - Run tests in `tests/components/` only - `npm run test:watch` - Run tests in watch mode - `npm run test:ui` - Run tests with UI - `npm run test:e2e` - Run E2E tests only - `npm run e2e` - Alias for Playwright E2E tests - `npm run e2e:ui` - Run E2E tests with UI - `npm run e2e:serve` - Start dev server and run E2E tests - `npm run lhci` - Run performance tests - `npm run test:sb` - Run Storybook tests ### Storybook - `npm run storybook:local` - Start Storybook for local development - `npm run storybook:github` - Start Storybook with GitHub Pages configuration - `npm run storybook:build` - Build Storybook for local deployment - `npm run storybook:build:github` - Build Storybook for GitHub Pages - `npm run storybook` - Start Storybook with current configuration ## πŸ—οΈ Project Structure ``` community-rule/ β”œβ”€β”€ app/ # Next.js app directory β”‚ β”œβ”€β”€ components/ # React components β”‚ β”œβ”€β”€ hooks/ # Custom React hooks β”‚ β”œβ”€β”€ layout.tsx # Root layout β”‚ └── page.tsx # Homepage β”œβ”€β”€ config/ # Project-specific configuration β”‚ β”œβ”€β”€ gitea-runner.yaml # Gitea runner configuration β”‚ └── runner-config.yaml # Runner configuration β”œβ”€β”€ docs/ # Documentation β”‚ β”œβ”€β”€ README.md # Documentation index β”‚ └── guides/ # Comprehensive guides β”‚ β”œβ”€β”€ testing.md # Testing strategy β”‚ β”œβ”€β”€ testing-framework.md # Testing framework details β”‚ β”œβ”€β”€ testing-quick-reference.md # Quick reference β”‚ β”œβ”€β”€ performance.md # Performance optimization β”‚ β”œβ”€β”€ visual-regression.md # Visual testing β”‚ └── content-creation.md # Content guidelines β”œβ”€β”€ scripts/ # Utility scripts β”‚ β”œβ”€β”€ start-runner.sh # Start Gitea runner β”‚ β”œβ”€β”€ status-runner.sh # Check runner status β”‚ └── stop-runner.sh # Stop Gitea runner β”œβ”€β”€ tests/ # Test files β”‚ β”œβ”€β”€ components/ # Component tests (Vitest + RTL) β”‚ β”œβ”€β”€ pages/ # Page-level tests β”‚ β”œβ”€β”€ e2e/ # E2E tests (Playwright) β”‚ β”œβ”€β”€ utils/ # Test utilities (componentTestSuite, etc.) β”‚ β”œβ”€β”€ msw/ # MSW server setup β”‚ └── accessibility/ # E2E accessibility checks β”œβ”€β”€ .storybook/ # Storybook configuration β”œβ”€β”€ .gitea/ # Gitea Actions workflows β”‚ └── workflows/ β”‚ └── ci.yaml # CI/CD pipeline └── public/ # Static assets ``` ## πŸ”§ Technology Stack - **Framework**: Next.js 15 + React 19 - **Styling**: Tailwind CSS 4 - **Testing**: Vitest + Playwright + Lighthouse CI - **Documentation**: Storybook 9 - **CI/CD**: Gitea Actions - **Hosting**: Gitea (Git hosting) ## πŸ“– Documentation - **[Documentation Index](docs/README.md)** - Complete documentation guide - **[Testing Guides](docs/guides/)** - Testing strategy, framework, and quick reference - **[Performance Guide](docs/guides/performance.md)** - Performance optimization guide - **[Visual Regression Guide](docs/guides/visual-regression.md)** - Visual testing guide - **[Storybook](http://localhost:6006)** - Component documentation (local) ## 🀝 Contributing 1. **Fork the repository** 2. **Create a feature branch**: `git checkout -b feature/amazing-feature` 3. **Write tests first** (see [Testing Guide](docs/guides/testing.md)) 4. **Make your changes** 5. **Run tests**: `npm test && npm run e2e` 6. **Commit changes**: `git commit -m "feat: add amazing feature"` 7. **Push to branch**: `git push origin feature/amazing-feature` 8. **Create Pull Request** ### Development Workflow - All changes must have tests - CI pipeline runs automatically on PRs - Visual regression tests ensure UI consistency - Performance budgets must be met - Accessibility standards must be maintained ## πŸ“„ License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.