diff --git a/.gitignore b/.gitignore index 0a7adec..e46e6ca 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ _/ GEMINI.md AGENT.md +CLAUDE.md # dependencies /node_modules diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 60380cc..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,99 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -This is a Next.js application showcasing a 10-hour loop of Ludwig doing the "Luddy" dance. It's a simple, single-page application with embedded YouTube content. - -## Technology Stack - -- **Framework**: Next.js 16.0.3 (Pages Router) -- **React**: 19.2.0 -- **Styling**: Tailwind CSS 4.1.17 -- **Runtime**: Node.js 24.x (CI tests on 20.x, 22.x, 24.x) -- **Package Manager**: pnpm 10.x+ -- **TypeScript**: 5.9 with strict mode -- **Testing**: Vitest 4.0 + React Testing Library -- **Linting**: Biome 2.3 - -## Development Commands - -```bash -# Development server -pnpm dev - -# Production build -pnpm build - -# Start production server -pnpm start - -# Linting -pnpm lint -``` - -## Docker - -### Multi-Stage Build -The Dockerfile uses an optimized 3-stage build: -1. **deps**: Install dependencies (Alpine, Node 24) -2. **builder**: Build the application with Next.js standalone output -3. **runner**: Minimal runtime image (234MB, 78% reduction from original) - -**Key optimizations**: -- Alpine Linux base (minimal footprint) -- Next.js standalone output mode (enabled in `next.config.mjs`) -- Non-root user for security -- NPM registry override for CI/CD compatibility -- Only production dependencies in final image - -```bash -# Build Docker image -docker buildx build --load -t luddy-dance . - -# Run container -docker run -p 3000:3000 luddy-dance -``` - -**Note**: The Dockerfile includes `registry=https://registry.npmjs.org/` override to ensure builds work in CI/CD environments with local `.npmrc` configurations. - -## Architecture - -### File Structure -- `pages/` - Next.js pages directory using Pages Router - - `_app.tsx` - App wrapper with global layout - - `index.tsx` - Main page component with YouTube embed -- `components/` - Reusable React components - - `layout.tsx` - Main layout wrapper with SEO and copyright - - `SEO.tsx` - SEO meta tags component - - `Copyright.tsx` - Footer copyright component -- `assets/styles/` - Global CSS styles -- `public/` - Static assets (images, SVGs, favicon) - - `favicon.svg` - Custom "L" favicon (purple/blue gradient) - - `favicon.ico` - Generated from SVG using sharp -- `scripts/` - Utility scripts - - `generate-favicon.mjs` - Generates favicon.ico from favicon.svg - -### Key Features -- YouTube iframe embedding with loading states -- Responsive design with Tailwind CSS -- Custom gradient backgrounds -- SEO optimization with meta tags -- Loading placeholder while iframe loads - -### Configuration -- **Path Aliases**: `@/*` maps to project root via tsconfig.json -- **Tailwind**: Configured for pages/, components/, and app/ directories -- **TypeScript**: Strict mode enabled with Next.js plugin -- **Next.js Config**: - - Standalone output mode for optimized Docker builds - - Comprehensive security headers (CSP, HSTS, etc.) - - Bundle analyzer integration - -## Important Notes - -- Uses Pages Router (not App Router) -- Single-page application focused on video content -- Responsive design with viewport-aware sizing -- Loading states for better UX with iframe content \ No newline at end of file diff --git a/README.md b/README.md index 951f934..1469f9d 100644 --- a/README.md +++ b/README.md @@ -1,259 +1,31 @@ -# ๐Ÿ•บ luddy.dance +# luddy.dance ๐Ÿ•บ -**10 hours of Ludwig doing the Luddy!** +Ten hours of Ludwig doing the Luddy. -A fun Next.js web app showcasing 10 hours of Ludwig's iconic dance. Built with modern web technologies and optimized for performance. +**[Watch at luddy.dance](https://luddy.dance)** -๐ŸŒ **Live Site**: [luddy.dance](https://luddy.dance) +Built with Next.js, React, TypeScript, and Tailwind CSS. The YouTube embed loads lazily when it enters the viewport. -## โœจ Features +## Quick start -- **๐ŸŽฌ YouTube Integration**: Embedded 10-hour Ludwig dance video with lazy loading -- **๐ŸŽจ Modern Design**: Gradient background with responsive layout -- **โšก Performance Optimized**: Lighthouse CI, lazy loading, optimized images -- **๐Ÿ›ก๏ธ Error Monitoring**: Comprehensive error tracking with structured logging -- **๐Ÿ” SEO Ready**: Meta tags, Open Graph, Twitter Cards, structured data -- **โ™ฟ Accessible**: ARIA labels, semantic HTML, screen reader friendly -- **๐Ÿงช Well Tested**: Vitest + React Testing Library -- **๐Ÿš€ CI/CD Ready**: GitHub Actions with automated testing and performance monitoring - -## ๐Ÿš€ Tech Stack - -### Core -- **Framework**: [Next.js 16.0.3](https://nextjs.org) with React 19.2 -- **Language**: TypeScript 5.9 -- **Styling**: [Tailwind CSS 4.1.17](https://tailwindcss.com) -- **Runtime**: Node.js 24.x -- **Package Manager**: [pnpm](https://pnpm.io) - -### Development & Quality -- **Linting**: [Biome 2.3](https://biomejs.dev) for code quality and formatting -- **Testing**: [Vitest 4.0](https://vitest.dev) + [React Testing Library](https://testing-library.com) -- **Bundle Analysis**: [@next/bundle-analyzer](https://www.npmjs.com/package/@next/bundle-analyzer) - -### Monitoring & Performance -- **Error Tracking**: [logan-logger](https://github.com/llbbl/logan-logger-ts) with structured logging -- **Performance Testing**: [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci) -- **Environment-based Logging**: Production-optimized logging controls - -### DevOps -- **CI/CD**: GitHub Actions with automated testing, linting, and performance monitoring -- **Containerization**: Optimized Docker with multi-stage builds (Alpine-based, 234MB) -- **Node Version Testing**: CI matrix testing on Node 20.x, 22.x, and 24.x - -## ๐Ÿƒโ€โ™‚๏ธ Quick Start - -### Prerequisites -- **Node.js**: 24.x (recommended) or 20.x/22.x -- **pnpm**: Latest version (10.x+) - -### Installation +Requires Node.js 22 or newer and pnpm 11. ```bash -# Clone the repository -git clone git@github.com:llbbl/luddy.dance.git -cd luddy.dance - -# Install dependencies +corepack enable pnpm install - -# Start development server pnpm dev ``` -Open [http://localhost:3000](http://localhost:3000) to see the app. - -### Available Scripts - -```bash -# Development -pnpm dev # Start development server -pnpm build # Build for production -pnpm start # Start production server - -# Code Quality -pnpm lint # Run Biome linting -pnpm biome:check # Check code formatting -pnpm biome:fix # Fix linting and formatting issues - -# Testing -pnpm test # Run all tests -pnpm test:ui # Run tests with UI - -# Performance & Analysis -pnpm analyze # Analyze bundle size -pnpm lighthouse # Run Lighthouse CI -``` - -## ๐Ÿ› ๏ธ Development - -### Environment Variables - -Copy the example environment file: - -```bash -cp .env.example .env.local -``` - -**Available Variables**: -- `NODE_ENV`: `development` | `production` -- `NEXT_PUBLIC_ENABLE_LOGGING`: Set to `true` to force enable logging in production - -### Project Structure - -``` -luddy.dance/ -โ”œโ”€โ”€ components/ # React components -โ”‚ โ”œโ”€โ”€ ErrorBoundary.tsx # Error boundary with fallback UI -โ”‚ โ”œโ”€โ”€ SEO.tsx # SEO meta tags and structured data -โ”‚ โ””โ”€โ”€ layout.tsx # Main layout wrapper -โ”œโ”€โ”€ lib/ # Utilities and libraries -โ”‚ โ””โ”€โ”€ logger.ts # Structured logging with logan-logger -โ”œโ”€โ”€ pages/ # Next.js pages -โ”‚ โ”œโ”€โ”€ _app.tsx # App wrapper -โ”‚ โ””โ”€โ”€ index.tsx # Home page with video -โ”œโ”€โ”€ public/ # Static assets -โ”œโ”€โ”€ tests/ # Test files -โ”œโ”€โ”€ .github/workflows/ # GitHub Actions CI/CD -โ”œโ”€โ”€ docs/ # Documentation -โ””โ”€โ”€ scripts/ # Utility scripts -``` - -### Code Quality Standards - -- **Linting**: Biome with TypeScript and React rules -- **Formatting**: Automatic code formatting with Biome -- **Testing**: Component and integration tests with Vitest -- **Performance**: Lighthouse CI with performance budgets -- **Accessibility**: ARIA labels, semantic HTML, screen reader support - -## ๐Ÿš€ Deployment - -### Docker (Recommended) - -The app uses an optimized multi-stage Docker build: - -**Features**: -- 3-stage build (deps โ†’ builder โ†’ runner) -- Alpine Linux base image (minimal size) -- Next.js standalone output mode -- Non-root user for security -- **78% size reduction** (1.05GB โ†’ 234MB) - -```bash -# Build image -docker buildx build --load -t luddy-dance . - -# Run container -docker run -p 3000:3000 luddy-dance -``` - -**Note**: The Dockerfile includes registry override for public npm registry to ensure builds work in CI/CD environments. - -### Self-Hosting - -```bash -# Build for production -pnpm build - -# Start production server -pnpm start -``` - -## ๐Ÿ“Š Performance - -The app is optimized for performance: - -- **Bundle Size**: ~105kB total (excellent for web apps) -- **Core Web Vitals**: Optimized for Google's performance standards -- **Lighthouse Score**: Monitored via CI with performance budgets -- **Image Optimization**: WebP images with Next.js optimization -- **Lazy Loading**: YouTube iframe loads only when visible - -### Performance Budgets - -- **First Contentful Paint**: < 3 seconds -- **Largest Contentful Paint**: < 4 seconds -- **Cumulative Layout Shift**: < 0.1 -- **Scripts**: < 150KB -- **Total Resources**: < 500KB - -## ๐Ÿงช Testing - -Run the test suite: +Open [localhost:3000](http://localhost:3000). ```bash -# Run all tests +pnpm lint pnpm test - -# Run tests in watch mode -pnpm test:watch - -# Run tests with coverage -pnpm test:coverage -``` - -### Test Coverage - -- **Component rendering**: Smoke tests for all major components -- **User interactions**: Event handling and state updates -- **Error boundaries**: Error handling and fallback UI -- **Accessibility**: Screen reader compatibility - -## ๐Ÿ› Troubleshooting - -### Common Issues - -**Build Failures**: -```bash -# Clear Next.js cache -rm -rf .next pnpm build ``` -**TypeScript Errors**: -```bash -# Check TypeScript -pnpm biome:check -``` - -**Performance Issues**: -```bash -# Analyze bundle -pnpm analyze -``` - -### Logging - -Development logging is enabled by default. In production, set `NEXT_PUBLIC_ENABLE_LOGGING=true` to enable detailed logging. - -## ๐Ÿค Contributing - -We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. - -### Quick Contribution Steps - -1. Fork the repository -2. Create a feature branch: `git checkout -b feature/amazing-feature` -3. Make your changes -4. Run tests: `pnpm test` -5. Run linting: `pnpm lint` -6. Commit changes: `git commit -m 'Add amazing feature'` -7. Push to branch: `git push origin feature/amazing-feature` -8. Open a Pull Request - -## ๐Ÿ“„ License - -This project is open source and available under the [MIT License](LICENSE). - -## ๐Ÿ™ Acknowledgments - -- **Ludwig** for the iconic dance moves -- **Next.js** team for the amazing framework -- **Open source community** for the excellent tools and libraries - ---- - -**Made with โค๏ธ for the Ludwig community** +## Documentation -*Keep dancing! ๐Ÿ•บ* \ No newline at end of file +- [Development guide](docs/development.md) +- [Deployment guide](docs/deployment.md) +- [Contributing](CONTRIBUTING.md) diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..ea99a6d --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,28 @@ +# Deployment + +## Next.js production server + +```bash +pnpm install --frozen-lockfile +pnpm build +pnpm start +``` + +Set `NODE_ENV=production`. Browser logging is disabled by default; set `NEXT_PUBLIC_ENABLE_LOGGING=true` only when production diagnostics are needed. + +## Docker + +The repository includes a multi-stage Dockerfile that builds Next.js standalone output and runs it as a non-root user. + +```bash +docker build -t luddy-dance . +docker run --rm -p 3000:3000 luddy-dance +``` + +Docker Compose is also available: + +```bash +docker compose up --build +``` + +Both options expose the application on [localhost:3000](http://localhost:3000). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..9384713 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,43 @@ +# Development + +## Requirements + +- Node.js 22 or newer +- pnpm 11.20.0, managed through Corepack + +## Setup + +```bash +corepack enable +pnpm install +pnpm dev +``` + +The development server runs at [localhost:3000](http://localhost:3000). + +To configure the runtime locally, copy `.env.example` to `.env.local`. Logging is enabled in development and can be enabled explicitly with `NEXT_PUBLIC_ENABLE_LOGGING=true`. + +## Commands + +| Command | Purpose | +| --- | --- | +| `pnpm dev` | Start the development server | +| `pnpm lint` | Check formatting, lint rules, and accessibility rules with Biome | +| `pnpm test` | Run the Vitest suite once | +| `pnpm test:ui` | Open the Vitest UI | +| `pnpm build` | Create a production build | +| `pnpm start` | Serve a production build | +| `pnpm analyze` | Build with bundle analysis enabled | +| `pnpm biome:fix` | Apply safe Biome formatting and lint fixes | + +Before opening a pull request, run: + +```bash +pnpm lint +pnpm exec tsc --noEmit +pnpm test +pnpm build +``` + +If a build behaves unexpectedly after framework changes, remove only the generated `.next` directory and rebuild. +