diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fc455c2cfc4..903676e2b5e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,16 +1,109 @@ -**What changed? Why?** +## πŸ“ Description -**Notes to reviewers** +Provide a clear and concise description of what this PR does. -**How has it been tested?** +## πŸ”— Related Issues -Have you tested the following pages? +- Fixes # +- Related to # -BaseWeb -- [] base.org -- [] base.org/names -- [] base.org/builders -- [] base.org/ecosystem -- [] base.org/name/jesse -- [] base.org/manage-names -- [] base.org/resources +## πŸ§ͺ Type of Change + +- [ ] πŸ› Bug fix (non-breaking change which fixes an issue) +- [ ] ✨ New feature (non-breaking change which adds functionality) +- [ ] πŸ’₯ Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] πŸ“š Documentation update +- [ ] 🎨 Code style/formatting changes +- [ ] ♻️ Code refactoring (no functional changes) +- [ ] ⚑ Performance improvements +- [ ] πŸ§ͺ Test coverage improvements +- [ ] πŸ”§ Build/CI improvements + +## 🎯 Changes Made + +### Added +- + +### Changed +- + +### Removed +- + +## πŸ§ͺ Testing + +- [ ] Unit tests pass +- [ ] Integration tests pass +- [ ] E2E tests pass +- [ ] Manual testing completed +- [ ] Cross-browser testing (if applicable) + +## πŸ“Έ Screenshots/Videos + +### Before + +### After + +## πŸ” Review Checklist + +### Code Quality +- [ ] Code follows the project's style guidelines +- [ ] Self-review of the code has been performed +- [ ] Code is properly commented where necessary +- [ ] No console.log statements left in production code +- [ ] No unused imports or variables + +### Performance +- [ ] No performance regressions introduced +- [ ] Bundle size impact considered (if applicable) + +### Security +- [ ] No security vulnerabilities introduced +- [ ] Input validation implemented (if applicable) + +### Accessibility +- [ ] WCAG guidelines followed (if applicable) +- [ ] Keyboard navigation works +- [ ] Screen reader compatibility maintained + +## πŸš€ Deployment Notes + +- [ ] Environment variables updated (if needed) +- [ ] Database migrations required (if applicable) +- [ ] Feature flags configured (if applicable) + +## πŸ“‹ Additional Notes + +## πŸ”„ Breaking Changes + +## πŸ“Š Performance Impact + +## 🌐 Browser/Device Testing + +- [ ] Chrome (latest) +- [ ] Firefox (latest) +- [ ] Safari (latest) +- [ ] Edge (latest) +- [ ] Mobile Safari +- [ ] Chrome Mobile + +## 🎨 Design Review + +- [ ] Design review completed +- [ ] Design system compliance verified +- [ ] Responsive design tested + +## πŸ“ Documentation Updates + +- [ ] README.md +- [ ] API documentation +- [ ] Component documentation +- [ ] Deployment guides + +--- + +**Reviewer Guidelines:** +- Please test the changes locally if possible +- Check for any potential security issues +- Verify that the implementation matches the requirements +- Ensure code quality and maintainability standards are met diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000000..1d7b8e30239 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,134 @@ +# Changelog + +All notable changes to the Base Web project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- πŸš€ Comprehensive Quickstart section with step-by-step setup instructions +- πŸ—οΈ Detailed Architecture documentation with tech stack overview +- πŸ”§ Complete Development Workflow guide with prerequisites and commands +- πŸ§ͺ Extensive Testing documentation covering unit tests and E2E testing +- πŸš€ Production Deployment guide with environment variables and Docker setup +- πŸ” Troubleshooting section with common issues and solutions +- πŸ“ Visual Project Structure documentation +- πŸ“‹ Streamlined Pull Request template with comprehensive checklists +- πŸ“š Enhanced CONTRIBUTING.md with development guidelines and standards +- 🐳 Complete Docker documentation with development and production setups +- βš™οΈ Improved E2E testing documentation with detailed configuration +- πŸ“ Environment variables template (env.example) with categorized examples + +### Enhanced +- πŸ“– README.md structure and content for better developer experience +- πŸ”§ CONTRIBUTING.md with detailed coding conventions and Git workflow +- πŸ§ͺ E2E testing documentation with comprehensive setup instructions +- πŸ“‹ PR template streamlined for better review process + +### Documentation +- Added TypeScript/JavaScript coding standards +- Added React/Next.js best practices +- Added Git workflow with branch naming and commit conventions +- Added comprehensive testing guidelines +- Added code review process documentation +- Added common development tasks instructions +- Added Docker containerization guide +- Added environment configuration examples + +--- + +## [Previous Releases] + +### [1.0.0] - 2024-01-XX + +#### Added +- Initial Base Web project setup +- Next.js 15 with App Router configuration +- TypeScript setup with strict configuration +- Tailwind CSS with custom design system +- Wagmi v2 + Viem for blockchain interactions +- Three.js with React Three Fiber for 3D graphics +- Framer Motion for animations +- Jest + Playwright for testing +- ESLint and Prettier configuration +- GitHub Actions CI/CD pipeline +- Docker containerization +- Comprehensive component library +- Ecosystem page with project listings +- Basename registration system +- Wallet integration (MetaMask, Coinbase Wallet) +- Analytics integration (Datadog, Bugsnag) +- Performance monitoring with Million.js + +#### Technical Stack +- **Framework**: Next.js 15 with App Router +- **Language**: TypeScript 5.0+ +- **Styling**: Tailwind CSS with custom design system +- **Blockchain**: Wagmi v2 + Viem for Ethereum interactions +- **3D Graphics**: Three.js with React Three Fiber +- **Animation**: Framer Motion +- **Testing**: Jest + Playwright for E2E +- **Deployment**: Vercel with custom Docker configuration +- **Database**: PostgreSQL with Kysely +- **Caching**: Redis +- **Image Management**: Cloudinary +- **Analytics**: Datadog, Bugsnag +- **Monitoring**: Custom performance tracking + +--- + +## How to Update This Changelog + +When making changes to the project: + +1. **Add new entries** under the `[Unreleased]` section +2. **Use appropriate categories**: + - `Added` for new features + - `Changed` for changes in existing functionality + - `Deprecated` for soon-to-be removed features + - `Removed` for removed features + - `Fixed` for bug fixes + - `Security` for vulnerability fixes +3. **Use emojis** for better readability +4. **Link to issues/PRs** when relevant +5. **Update version** when releasing + +### Example Entry +```markdown +### Added +- πŸŽ‰ New user dashboard with analytics +- πŸ” Enhanced authentication with 2FA +- πŸ“± Mobile-responsive design improvements + +### Fixed +- πŸ› Resolved wallet connection timeout issues +- πŸ”§ Fixed build process for Windows users + +### Changed +- ♻️ Refactored authentication flow for better UX +- πŸ“ˆ Improved performance metrics collection +``` + +--- + +## Versioning + +This project uses [Semantic Versioning](https://semver.org/): + +- **MAJOR** version when you make incompatible API changes +- **MINOR** version when you add functionality in a backwards compatible manner +- **PATCH** version when you make backwards compatible bug fixes + +## Release Process + +1. Update version in `package.json` +2. Update this `CHANGELOG.md` +3. Create a release tag +4. Update documentation if needed +5. Deploy to production + +--- + +For questions about this changelog or the release process, please reach out in #developer-chat in the [Base Discord](https://base.org/discord). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c6d2bc8ee8..a6fa1fabc03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,12 +6,59 @@ The following is a set of guidelines for contributing to Base Web. These are jus ## Table of Contents +- [Quick Start](#quick-start) +- [Development Setup](#development-setup) - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Reporting Bugs](#reporting-bugs) - [Suggesting Enhancements](#suggesting-enhancements) - [Pull Requests](#pull-requests) -- [Coding Conventions](#coding-conventions) +- [Development Guidelines](#development-guidelines) + - [Coding Conventions](#coding-conventions) + - [Git Workflow](#git-workflow) + - [Testing Guidelines](#testing-guidelines) + - [Code Review Process](#code-review-process) +- [Project Structure](#project-structure) +- [Common Tasks](#common-tasks) + +## Quick Start + +If you're new to the project, here's how to get started: + +1. **Fork and clone** the repository +2. **Set up your development environment** (see [Development Setup](#development-setup)) +3. **Make your changes** following our [guidelines](#development-guidelines) +4. **Test your changes** thoroughly +5. **Submit a pull request** using our [template](.github/pull_request_template.md) + +## Development Setup + +### Prerequisites + +- **Node.js 20+** - Use [nvm](https://github.com/nvm-sh/nvm) for version management +- **Yarn 1.22+** - Package manager +- **Git** - Version control + +### Initial Setup + +```bash +# Clone your fork +git clone https://github.com/YOUR_USERNAME/web.git +cd web + +# Install dependencies +yarn install + +# Copy environment variables +cp env.example .env.local + +# Start development server +yarn workspace @app/web dev +``` + +### Environment Variables + +Copy `env.example` to `.env.local` and configure the necessary variables for your development environment. See the [README.md](README.md#environment-variables) for details. ## Code of Conduct @@ -45,12 +92,165 @@ This project and everyone participating in it is governed by our [Code of Conduc 6. **Wait for review**: Once your pull request is opened, it will be reviewed as soon as possible. Changes may be requested, and your responsiveness is appreciated. -## Coding Conventions +## Development Guidelines + +### Coding Conventions + +#### TypeScript/JavaScript +- Use **TypeScript** for all new code +- Follow **ESLint** and **Prettier** configurations +- Use **descriptive variable names** and **clear function names** +- Add **JSDoc comments** for complex functions and public APIs +- Prefer **functional components** with hooks over class components + +#### React/Next.js +- Use **Next.js 15 App Router** conventions +- Implement **proper error boundaries** and **loading states** +- Follow **React best practices** (proper key props, avoid inline functions in JSX) +- Use **Tailwind CSS** for styling with our design system +- Implement **responsive design** for all components + +#### File Organization +``` +src/ +β”œβ”€β”€ components/ # Reusable UI components +β”‚ β”œβ”€β”€ ui/ # Basic UI components +β”‚ β”œβ”€β”€ layout/ # Layout components +β”‚ └── features/ # Feature-specific components +β”œβ”€β”€ hooks/ # Custom React hooks +β”œβ”€β”€ utils/ # Utility functions +β”œβ”€β”€ types/ # TypeScript type definitions +└── constants/ # Application constants +``` + +### Git Workflow + +#### Branch Naming +- **Feature branches**: `feature/description` (e.g., `feature/user-authentication`) +- **Bug fixes**: `fix/description` (e.g., `fix/login-validation`) +- **Hotfixes**: `hotfix/description` (e.g., `hotfix/security-patch`) +- **Documentation**: `docs/description` (e.g., `docs/api-documentation`) + +#### Commit Messages +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +type(scope): description + +[optional body] + +[optional footer(s)] +``` -- Use clear and descriptive variable names. -- Comment your code where necessary. -- Follow the lint configurations. +Examples: +- `feat(auth): add user authentication system` +- `fix(ui): resolve button alignment issue` +- `docs(readme): update installation instructions` +- `refactor(api): simplify user data fetching` + +### Testing Guidelines + +#### Unit Tests +- Write tests for all new components and utilities +- Aim for **80%+ code coverage** +- Use **React Testing Library** for component tests +- Mock external dependencies appropriately + +#### End-to-End Tests +- Add E2E tests for critical user flows +- Use **Playwright** for browser automation +- Test across different browsers and devices +- Include accessibility testing + +#### Running Tests +```bash +# Unit tests +yarn test + +# E2E tests +yarn test:e2e + +# Test with coverage +yarn test --coverage + +# Watch mode for development +yarn test --watch +``` + +### Code Review Process + +#### Before Submitting +- [ ] Code follows project conventions +- [ ] All tests pass +- [ ] No linting errors +- [ ] Documentation updated (if needed) +- [ ] Screenshots included (for UI changes) + +#### Review Checklist +- [ ] Code is readable and well-commented +- [ ] No security vulnerabilities +- [ ] Performance implications considered +- [ ] Accessibility standards met +- [ ] Cross-browser compatibility verified + +## Project Structure + +``` +web/ +β”œβ”€β”€ apps/ +β”‚ β”œβ”€β”€ web/ # Main website application +β”‚ β”‚ β”œβ”€β”€ app/ # Next.js 15 App Router +β”‚ β”‚ β”œβ”€β”€ src/ # Source code +β”‚ β”‚ β”œβ”€β”€ public/ # Static assets +β”‚ β”‚ └── e2e/ # End-to-end tests +β”‚ └── bridge/ # Bridge application +β”œβ”€β”€ libs/ +β”‚ └── base-ui/ # Shared UI components +β”œβ”€β”€ tools/ # Build tools and CI +└── .github/ # GitHub templates and workflows +``` + +## Common Tasks + +### Adding a New Component + +1. Create component file in appropriate directory +2. Add TypeScript types and interfaces +3. Implement component with proper styling +4. Add unit tests +5. Export from appropriate index file +6. Update documentation + +### Adding a New Page + +1. Create page in `apps/web/app/` directory +2. Follow Next.js 15 App Router conventions +3. Add proper metadata and SEO +4. Implement responsive design +5. Add E2E tests for critical flows + +### Updating Dependencies + +1. Update package.json files +2. Run `yarn install` to update lock file +3. Test that everything still works +4. Update documentation if needed +5. Submit PR with clear description of changes + +### Database Changes + +1. Create migration files +2. Update TypeScript types +3. Test migrations on local database +4. Update API endpoints if needed +5. Document breaking changes --- -Feel free to customize this template according to the specific needs and nuances of Base Web. A well-crafted `CONTRIBUTING.md` can help your project attract quality contributions and foster a collaborative community. +## Getting Help + +- **Discord**: Join our [Base Discord](https://base.org/discord) and ask in `#developer-chat` +- **Issues**: Create a [GitHub issue](https://github.com/base/web/issues) for bugs or feature requests +- **Discussions**: Use [GitHub Discussions](https://github.com/base/web/discussions) for questions + +Thank you for contributing to Base Web! πŸš€ diff --git a/DOCKER.md b/DOCKER.md new file mode 100644 index 00000000000..74ffbd3f351 --- /dev/null +++ b/DOCKER.md @@ -0,0 +1,336 @@ +# Docker Setup for Base Web + +This document provides comprehensive instructions for running Base Web using Docker containers. + +## 🐳 Docker Overview + +Base Web uses Docker for consistent development and production environments. The project includes a multi-stage Dockerfile optimized for Next.js applications. + +## πŸ“‹ Prerequisites + +- **Docker** 20.10+ +- **Docker Compose** 2.0+ +- **Git** for cloning the repository + +## πŸš€ Quick Start with Docker + +### 1. Clone and Build + +```bash +git clone https://github.com/base/web.git +cd web +``` + +### 2. Environment Setup + +```bash +# Copy environment template +cp env.example .env.local + +# Edit environment variables +nano .env.local +``` + +### 3. Build Docker Image + +```bash +# Build the application image +docker build -t base-web . + +# Or build for specific architecture +docker build --platform linux/amd64 -t base-web . +``` + +### 4. Run Container + +```bash +# Run the container +docker run -p 3000:3000 \ + --env-file .env.local \ + base-web + +# Or run in detached mode +docker run -d -p 3000:3000 \ + --name base-web-container \ + --env-file .env.local \ + base-web +``` + +## πŸ› οΈ Development with Docker + +### Development Container + +```bash +# Build development image +docker build -t base-web-dev \ + --target development \ + . + +# Run with volume mounting for hot reload +docker run -p 3000:3000 \ + -v $(pwd):/repo \ + --env-file .env.local \ + base-web-dev +``` + +### Docker Compose Setup + +Create a `docker-compose.yml` file: + +```yaml +version: '3.8' + +services: + base-web: + build: . + ports: + - "3000:3000" + environment: + - NODE_ENV=development + volumes: + - .:/repo + - /repo/node_modules + env_file: + - .env.local + depends_on: + - postgres + - redis + + postgres: + image: postgres:15 + environment: + POSTGRES_DB: base_web + POSTGRES_USER: postgres + POSTGRES_PASSWORD: password + ports: + - "5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + + redis: + image: redis:7-alpine + ports: + - "6379:6379" + volumes: + - redis_data:/data + +volumes: + postgres_data: + redis_data: +``` + +Run with Docker Compose: + +```bash +# Start all services +docker-compose up + +# Start in detached mode +docker-compose up -d + +# Stop services +docker-compose down +``` + +## πŸ—οΈ Production Deployment + +### Multi-Stage Build + +The Dockerfile uses multi-stage builds for optimization: + +```dockerfile +# Stage 1: Dependencies +FROM node:20-alpine AS deps +WORKDIR /app +COPY package.json yarn.lock ./ +RUN yarn install --frozen-lockfile + +# Stage 2: Builder +FROM node:20-alpine AS builder +WORKDIR /app +COPY --from=deps /app/node_modules ./node_modules +COPY . . +RUN yarn build + +# Stage 3: Runner +FROM node:20-alpine AS runner +WORKDIR /app +ENV NODE_ENV=production +COPY --from=builder /app/dist ./dist +COPY --from=builder /app/public ./public +EXPOSE 3000 +CMD ["yarn", "start"] +``` + +### Production Environment Variables + +Required environment variables for production: + +```bash +# Database +DATABASE_URL=postgresql://user:password@postgres:5432/base_web + +# Redis +REDIS_URL=redis://redis:6379 + +# Analytics +DATADOG_CLIENT_TOKEN=your_token +BUGSNAG_API_KEY=your_key + +# Blockchain +NEXT_PUBLIC_BASE_RPC_URL=https://mainnet.base.org +``` + +## πŸ”§ Docker Commands Reference + +### Building Images + +```bash +# Build with cache +docker build --cache-from base-web -t base-web . + +# Build for multiple architectures +docker buildx build --platform linux/amd64,linux/arm64 -t base-web . + +# Build without cache +docker build --no-cache -t base-web . +``` + +### Container Management + +```bash +# List containers +docker ps -a + +# View logs +docker logs base-web-container + +# Execute commands in running container +docker exec -it base-web-container /bin/sh + +# Stop and remove container +docker stop base-web-container +docker rm base-web-container +``` + +### Image Management + +```bash +# List images +docker images + +# Remove unused images +docker image prune + +# Remove all unused images +docker image prune -a + +# Tag image for registry +docker tag base-web your-registry/base-web:latest +``` + +## 🚨 Troubleshooting + +### Common Issues + +**Port Already in Use** +```bash +# Find process using port 3000 +lsof -i :3000 + +# Kill process +kill -9 + +# Or use different port +docker run -p 3001:3000 base-web +``` + +**Permission Issues** +```bash +# Fix file permissions +sudo chown -R $USER:$USER . + +# Or run with user mapping +docker run -u $(id -u):$(id -g) base-web +``` + +**Build Failures** +```bash +# Clear Docker cache +docker builder prune + +# Check Dockerfile syntax +docker build --no-cache -t base-web . +``` + +**Memory Issues** +```bash +# Increase Docker memory limit +# In Docker Desktop: Settings > Resources > Memory +``` + +### Debugging + +**Inspect Container** +```bash +# Get container details +docker inspect base-web-container + +# View container logs +docker logs -f base-web-container + +# Access container shell +docker exec -it base-web-container /bin/sh +``` + +**Check Environment Variables** +```bash +# List environment variables in container +docker exec base-web-container env +``` + +## πŸ“Š Performance Optimization + +### Image Size Optimization + +- Use Alpine Linux base images +- Multi-stage builds to exclude dev dependencies +- .dockerignore to exclude unnecessary files +- Combine RUN commands to reduce layers + +### Runtime Optimization + +- Use specific Node.js versions +- Enable Docker layer caching +- Use health checks for better orchestration +- Configure resource limits + +## πŸ”’ Security Considerations + +### Best Practices + +- Use non-root user in containers +- Keep base images updated +- Scan images for vulnerabilities +- Use secrets management for sensitive data +- Implement proper network isolation + +### Security Scanning + +```bash +# Scan image for vulnerabilities +docker scan base-web + +# Use security-focused base image +FROM node:20-alpine +``` + +--- + +## πŸ“š Additional Resources + +- [Docker Documentation](https://docs.docker.com/) +- [Next.js Docker Examples](https://github.com/vercel/next.js/tree/canary/examples/with-docker) +- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/) + +For questions or issues, please reach out in #developer-chat in the [Base Discord](https://base.org/discord). diff --git a/README.md b/README.md index efa3d4fc42e..d65385f058f 100644 --- a/README.md +++ b/README.md @@ -133,4 +133,214 @@ By opening a PR to add your project, you authorize and license Coinbase on a non --- +## πŸš€ Quickstart + +### Requirements + +- Node.js >= 20 +- Yarn >= 1.22 + +### Installation + +```bash +git clone https://github.com/base/web.git +cd web +yarn install +yarn dev +``` + +## πŸ—οΈ Architecture + +This monorepo contains multiple applications and libraries: + +- **`apps/web`** - Main Base website application built with Next.js 15 +- **`apps/bridge`** - Base bridge application +- **`libs/base-ui`** - Shared UI component library + +### Tech Stack + +- **Framework**: Next.js 15 with App Router +- **Language**: TypeScript 5.0+ +- **Styling**: Tailwind CSS with custom design system +- **Blockchain**: Wagmi v2 + Viem for Ethereum interactions +- **3D Graphics**: Three.js with React Three Fiber +- **Animation**: Framer Motion +- **Testing**: Jest + Playwright for E2E +- **Deployment**: Vercel with custom Docker configuration + +## πŸ”§ Development Workflow + +### Prerequisites Setup + +1. Install Node.js 20+ using [nvm](https://github.com/nvm-sh/nvm): + ```bash + nvm install 20 + nvm use 20 + ``` + +2. Enable Yarn package manager: + ```bash + corepack enable + ``` + +3. Install dependencies: + ```bash + yarn install + ``` + +### Available Scripts + +| Command | Description | +|---------|-------------| +| `yarn dev` | Start development server for web app | +| `yarn build` | Build all applications | +| `yarn test` | Run unit tests | +| `yarn test:e2e` | Run end-to-end tests | +| `yarn lint` | Run ESLint on all packages | +| `yarn workspace @app/web dev` | Start specific app in development | + +### Development Commands + +```bash +# Start the main web application +yarn workspace @app/web dev + +# Build the entire project +yarn build + +# Run tests +yarn test + +# Run E2E tests +yarn test:e2e + +# Run E2E tests with UI +yarn test:e2e:ui +``` + +## πŸ§ͺ Testing + +### Unit Tests +```bash +yarn test +``` + +### End-to-End Tests +```bash +# Run all E2E tests +yarn test:e2e + +# Run with browser UI +yarn test:e2e:ui + +# Debug mode +yarn test:e2e:debug + +# Run in headed mode +yarn test:e2e:headed +``` + +### Test Configuration +- **Unit Tests**: Jest with React Testing Library +- **E2E Tests**: Playwright with custom wallet configurations +- **Test Coverage**: Configured for comprehensive coverage reporting + +## πŸš€ Deployment + +### Production Build +```bash +yarn build +yarn workspace @app/web start +``` + +### Environment Variables +Required environment variables for production: + +```bash +# Database +DATABASE_URL=postgresql://... + +# Redis +REDIS_URL=redis://... + +# External APIs +CLOUDINARY_URL=cloudinary://... + +# Analytics +DATADOG_CLIENT_TOKEN=... +BUGSNAG_API_KEY=... +``` + +### Docker Deployment +```bash +# Build Docker image +docker build -t base-web . + +# Run container +docker run -p 3000:3000 base-web +``` + +## πŸ” Troubleshooting + +### Common Issues + +**Node.js Version Issues** +```bash +# Ensure you're using Node.js 20+ +nvm use 20 +``` + +**Yarn Installation Issues** +```bash +# Clear yarn cache +yarn cache clean + +# Reinstall dependencies +rm -rf node_modules yarn.lock +yarn install +``` + +**Build Failures** +```bash +# Clear Next.js cache +rm -rf .next + +# Rebuild +yarn build +``` + +**E2E Test Issues** +```bash +# Install Playwright browsers +npx playwright install + +# Run tests in debug mode +yarn test:e2e:debug +``` + +### Performance Optimization + +- **Bundle Analysis**: Run `yarn workspace @app/web analyze` to analyze bundle size +- **Million.js**: Use `yarn workspace @app/web dev:million` for performance monitoring +- **Image Optimization**: All images are automatically optimized with Next.js Image component + +## πŸ“ Project Structure + +``` +web/ +β”œβ”€β”€ apps/ +β”‚ β”œβ”€β”€ web/ # Main website application +β”‚ β”‚ β”œβ”€β”€ app/ # Next.js 15 App Router +β”‚ β”‚ β”œβ”€β”€ src/ # Source code +β”‚ β”‚ β”œβ”€β”€ public/ # Static assets +β”‚ β”‚ └── e2e/ # End-to-end tests +β”‚ └── bridge/ # Bridge application +β”œβ”€β”€ libs/ +β”‚ └── base-ui/ # Shared UI components +β”œβ”€β”€ tools/ # Build tools and CI +└── docs/ # Documentation +``` + +--- + If you have any questions, please reach out to us in #developer-chat in the [Base Discord](https://base.org/discord). diff --git a/apps/web/app/(base-org)/brand/(1)/messaging/page.tsx b/apps/web/app/(base-org)/brand/(1)/messaging/page.tsx index 580690f3146..f98f5ac8749 100644 --- a/apps/web/app/(base-org)/brand/(1)/messaging/page.tsx +++ b/apps/web/app/(base-org)/brand/(1)/messaging/page.tsx @@ -7,7 +7,7 @@ import { WhatToAvoid } from 'apps/web/app/(base-org)/brand/(1)/messaging/section import { WritingGuidelines } from 'apps/web/app/(base-org)/brand/(1)/messaging/sections/6-writing-guidelines'; import { ToneAndVoice } from 'apps/web/app/(base-org)/brand/(1)/messaging/sections/7-tone-and-voice'; import { ClarityConcisionFlow } from 'apps/web/app/(base-org)/brand/(1)/messaging/sections/8-clarity-concision-flow'; -import { Naunces } from 'apps/web/app/(base-org)/brand/(1)/messaging/sections/9-naunces'; +import { Nuances } from 'apps/web/app/(base-org)/brand/(1)/messaging/sections/9-naunces'; import messagingImg from 'apps/web/public/images/backgrounds/messaging.webp'; import BrandIndex from 'apps/web/src/components/Brand/Index'; import { BRAND_PAGES_INDEX } from 'apps/web/app/(base-org)/brand/(main)/page'; @@ -47,7 +47,7 @@ export default function Page() { - + diff --git a/apps/web/app/(base-org)/brand/(1)/messaging/sections/7-tone-and-voice.tsx b/apps/web/app/(base-org)/brand/(1)/messaging/sections/7-tone-and-voice.tsx index 6fce04e325d..be72533ba50 100644 --- a/apps/web/app/(base-org)/brand/(1)/messaging/sections/7-tone-and-voice.tsx +++ b/apps/web/app/(base-org)/brand/(1)/messaging/sections/7-tone-and-voice.tsx @@ -92,7 +92,7 @@ const sectionContent: ListGridContent = {
- Tone in Writting: A Simple Guide + Tone in Writing: A Simple Guide ”…voice is what you say, and tone is how you say it.” diff --git a/apps/web/app/(base-org)/brand/(1)/messaging/sections/8-clarity-concision-flow.tsx b/apps/web/app/(base-org)/brand/(1)/messaging/sections/8-clarity-concision-flow.tsx index 60f42b70246..f87998fbeb6 100644 --- a/apps/web/app/(base-org)/brand/(1)/messaging/sections/8-clarity-concision-flow.tsx +++ b/apps/web/app/(base-org)/brand/(1)/messaging/sections/8-clarity-concision-flow.tsx @@ -66,10 +66,10 @@ const sectionContent: ListGridContent = { ), }, { - title: 'Naunces', + title: 'Nuances', content: (

- Naunces are short, punchy phrases that are used to grab attention and make a + Nuances are short, punchy phrases that are used to grab attention and make a statement. For example: "Base is for creators, builders, traders, and more."

), diff --git a/apps/web/app/(base-org)/brand/(1)/messaging/sections/9-naunces.tsx b/apps/web/app/(base-org)/brand/(1)/messaging/sections/9-naunces.tsx index 8dbaa020ed6..b76d4d5d8ae 100644 --- a/apps/web/app/(base-org)/brand/(1)/messaging/sections/9-naunces.tsx +++ b/apps/web/app/(base-org)/brand/(1)/messaging/sections/9-naunces.tsx @@ -1,6 +1,6 @@ import { ListGrid, ListGridContent } from 'apps/web/src/components/Brand/ListGridMasonry'; -export function Naunces() { +export function Nuances() { return ; } diff --git a/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/3-features/index.tsx b/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/3-features/index.tsx index 6fa98fdc502..f4add78ea27 100644 --- a/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/3-features/index.tsx +++ b/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/3-features/index.tsx @@ -63,7 +63,7 @@ export function Features() { id="primary-typeface-features" prefix="Primary Typeface" title="Features" - description="Base Sans is based on Modern Gothic, and includes unique customizations and alternative glyphs that makes it more ownable to Base, and more legible. Several letters were given a more geometric structure, to have better flow, consistency and appropriateness to the brand. In addition, there is a set of unique alternate shapes for the b, h, m, n, r, u and the symbols that are decisively geometric and are means for occasional display purposes, especially in developers setting. " + description="Base Sans is based on Modern Gothic, and includes unique customizations and alternative glyphs that make it more ownable to Base, and more legible. Several letters were given a more geometric structure, to have better flow, consistency and appropriateness to the brand. In addition, there is a set of unique alternate shapes for the b, h, m, n, r, u and the symbols that are decisively geometric and are meant for occasional display purposes, especially in developer settings." content={content} /> ); diff --git a/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/8-fallback-system-font/index.tsx b/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/8-fallback-system-font/index.tsx index fe04e8c4952..8449e432d01 100644 --- a/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/8-fallback-system-font/index.tsx +++ b/apps/web/app/(base-org)/brand/(4)/typography/sections/1-primary-typeface/8-fallback-system-font/index.tsx @@ -49,7 +49,7 @@ export function FallbackSystemFont() { id="primary-typeface-fallback-system-font" prefix="Primary Typeface" title="Fallback / System Font" - description="Base Sans is based on Modern Gothic, and includes unique customizations and alternative glyphs that makes it more ownable to Base, and more legible. Several letters were given a more geometric structure, to have better flow, consistency and appropriateness to the brand. In addition, there is a set of unique alternate shapes for the b, h, m, n, r, u and the symbols that are decisively geometric and are means for occasional display purposes, especially in developers setting. " + description="Base Sans is based on Modern Gothic, and includes unique customizations and alternative glyphs that make it more ownable to Base, and more legible. Several letters were given a more geometric structure, to have better flow, consistency and appropriateness to the brand. In addition, there is a set of unique alternate shapes for the b, h, m, n, r, u and the symbols that are decisively geometric and are meant for occasional display purposes, especially in developer settings." content={content} /> ); diff --git a/apps/web/e2e/E2Ereadme.md b/apps/web/e2e/E2Ereadme.md index dc2cb2c49d1..beff8e6d106 100644 --- a/apps/web/e2e/E2Ereadme.md +++ b/apps/web/e2e/E2Ereadme.md @@ -1,48 +1,101 @@ # End-to-End Tests for `apps/web` -This folder contains Playwright tests for the Base Web project against a local Next.js dev server... +This folder contains comprehensive Playwright tests for the Base Web project, including wallet integration, user registration flows, and blockchain interactions using the On-chain Test Kit. -## Contents +## πŸ“ Contents -- [`testFixture.ts`](./testFixture.ts) – extends Playwright's fixture system with the On-chain Test Kit wallets. -- [`appSession.ts`](./appSession.ts) – helper functions for the common onboarding & registration steps. -- [`tests/*.spec.ts`](./tests) – individual test cases (successful registration, rejection flow, …). +- [`testFixture.ts`](./testFixture.ts) – Extends Playwright's fixture system with On-chain Test Kit wallets and blockchain simulation +- [`appSession.ts`](./appSession.ts) – Helper functions for common onboarding & registration steps +- [`basenameHelpers.ts`](./basenameHelpers.ts) – Utility functions for basename operations +- [`tests/*.spec.ts`](./tests) – Individual test cases covering registration flows, wallet connections, and error scenarios +- [`walletConfig/`](./walletConfig) – Configuration files for MetaMask and Coinbase Wallet testing + +## 🎯 Test Coverage + +### Current Test Scenarios +- βœ… **Successful Registration Flow** - Complete user onboarding with wallet connection +- βœ… **Registration Rejection** - Handling user rejection of registration +- βœ… **Registration Failure** - Error handling for failed registration attempts +- βœ… **Wallet Connection** - MetaMask and Coinbase Wallet integration +- βœ… **Basename Validation** - Input validation and error messaging + +### Test Architecture +- **Playwright** for browser automation and testing +- **On-chain Test Kit** for blockchain simulation and wallet testing +- **Anvil** for local Ethereum node simulation +- **MetaMask** for wallet interaction testing --- -## Prerequisites +## πŸš€ Prerequisites + +### Required Dependencies +```bash +# Install Playwright and On-chain Test Kit +yarn add -D @playwright/test @coinbase/onchaintestkit + +# Install Playwright browsers +yarn playwright install --with-deps +``` -run yarn add -D @playwright/test @coinbase/onchaintestkit +### System Requirements +- **Node.js 20+** +- **Yarn 1.22+** +- **Git** for cloning the repository -> The scripts have been tested on macOS and Linux. Windows users should run the commands inside WSL 2. +> **Note:** Scripts have been tested on macOS and Linux. Windows users should run commands inside WSL 2 for best compatibility. --- -## Environment variables +## βš™οΈ Environment Configuration -Create a file called **`.env`** in `apps/web/` (it is listed in `.gitignore`). +### Required Environment Variables + +Create a file called **`.env`** in `apps/web/` (it is listed in `.gitignore`): ```dotenv -# E2E .env example ─────────────────────────────────────────── +# E2E Test Configuration ──────────────────────────────────────── -# the basename that the test will try to register +# Test basename for registration (must be unique and available) TEST_BASENAME=mytestname123 -# 12-word mnemonic that gets imported into MetaMask; **DO NOT USE A REAL WALLET** +# Test wallet mnemonic - NEVER USE A REAL WALLET! E2E_TEST_SEED_PHRASE="test test test test test test test test test test test junk" -# RPC endpoint that Anvil will fork from (Base mainnet in this example) +# RPC endpoint that Anvil will fork from (Base mainnet) E2E_TEST_FORK_URL=https://mainnet.base.org -# The block number to fork at. Omitting gives you the latest block. +# Specific block number to fork at (optional - latest if omitted) E2E_TEST_FORK_BLOCK_NUMBER=31397553 +# Local Anvil RPC endpoint NEXT_PUBLIC_CDP_BASE_RPC_ENDPOINT="http://localhost:8545/" + +# Enable E2E test mode E2E_TEST="true" + +# Additional test configuration +E2E_TEST_TIMEOUT=30000 +E2E_TEST_RETRIES=3 ``` -- **`TEST_BASENAME`** must be at least 3 alphanumeric lower-case characters. -- Any ETH the flow spends comes from Anvil's default funded developer accounts, so there is **no cost**. +### Environment Variable Details + +| Variable | Description | Required | Example | +|----------|-------------|----------|---------| +| `TEST_BASENAME` | Unique basename for test registration | βœ… | `mytestname123` | +| `E2E_TEST_SEED_PHRASE` | 12-word mnemonic for test wallet | βœ… | `"test test test..."` | +| `E2E_TEST_FORK_URL` | Base network RPC URL for forking | βœ… | `https://mainnet.base.org` | +| `E2E_TEST_FORK_BLOCK_NUMBER` | Specific block to fork from | ❌ | `31397553` | +| `NEXT_PUBLIC_CDP_BASE_RPC_ENDPOINT` | Local Anvil RPC endpoint | βœ… | `http://localhost:8545/` | +| `E2E_TEST` | Enable E2E test mode | βœ… | `true` | + +### Important Notes + +- **`TEST_BASENAME`** must be at least 3 alphanumeric lower-case characters and unique +- **Test wallet mnemonic** should NEVER be used for real funds - it's for testing only +- **No real ETH required** - tests use Anvil's default funded developer accounts +- **Block forking** allows testing against real blockchain state without costs --- diff --git a/apps/web/src/components/Basenames/UsernameProfileNotFound/index.tsx b/apps/web/src/components/Basenames/UsernameProfileNotFound/index.tsx index 4f343e850dd..c2b2b1bb894 100644 --- a/apps/web/src/components/Basenames/UsernameProfileNotFound/index.tsx +++ b/apps/web/src/components/Basenames/UsernameProfileNotFound/index.tsx @@ -37,7 +37,7 @@ export default function UsernameProfileNotFound() { redirect(`/names`); } - const title = `${username ?? 'Name'} is not found`; + const title = `${username ?? 'Name'} was not found`; const description = username ? "There's no profile associated with this name, but it could be yours!" : "This profile doesn't exist"; diff --git a/apps/web/src/components/WebGL/WebGLView.tsx b/apps/web/src/components/WebGL/WebGLView.tsx index ff7572d2e3e..2722a69cb53 100644 --- a/apps/web/src/components/WebGL/WebGLView.tsx +++ b/apps/web/src/components/WebGL/WebGLView.tsx @@ -49,7 +49,7 @@ float isInsideRoundedRect(vec2 uv, vec2 resolution, vec4 radii) { vec2 pos = (uv - 0.5) * resolution; vec2 halfSize = resolution * 0.5; - // supports differnt radius for each corner + // supports different radius for each corner vec4 r = radii; if (pos.x > 0.0 && pos.y > 0.0) r = vec4(radii.y, radii.y, radii.y, radii.y); // top-right else if (pos.x < 0.0 && pos.y > 0.0) r = vec4(radii.x, radii.x, radii.x, radii.x); // top-left diff --git a/env.example b/env.example new file mode 100644 index 00000000000..14601c28423 --- /dev/null +++ b/env.example @@ -0,0 +1,89 @@ +# Base Web Environment Variables Example +# Copy this file to .env.local and fill in your actual values + +# ============================================================================= +# DATABASE +# ============================================================================= +# PostgreSQL database URL for production +DATABASE_URL=postgresql://username:password@localhost:5432/base_web + +# ============================================================================= +# REDIS +# ============================================================================= +# Redis URL for caching and sessions +REDIS_URL=redis://localhost:6379 + +# ============================================================================= +# BLOCKCHAIN & WALLET +# ============================================================================= +# Base mainnet RPC URL +NEXT_PUBLIC_BASE_RPC_URL=https://mainnet.base.org + +# WalletConnect Project ID +NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id + +# ============================================================================= +# EXTERNAL APIS +# ============================================================================= +# Cloudinary configuration for image management +CLOUDINARY_URL=cloudinary://api_key:api_secret@cloud_name + +# Pinata API for IPFS +PINATA_API_KEY=your_pinata_api_key +PINATA_SECRET_API_KEY=your_pinata_secret_key + +# ============================================================================= +# ANALYTICS & MONITORING +# ============================================================================= +# Datadog configuration +DATADOG_CLIENT_TOKEN=your_datadog_client_token +DATADOG_APPLICATION_ID=your_datadog_application_id +DATADOG_SERVICE=base-web + +# Bugsnag for error tracking +BUGSNAG_API_KEY=your_bugsnag_api_key + +# ============================================================================= +# AUTHENTICATION +# ============================================================================= +# JWT secret for authentication +JWT_SECRET=your_jwt_secret_key_here + +# CDP (Coinbase Developer Platform) configuration +CDP_CLIENT_ID=your_cdp_client_id +CDP_CLIENT_SECRET=your_cdp_client_secret + +# ============================================================================= +# THIRD-PARTY INTEGRATIONS +# ============================================================================= +# Farcaster API +FARCASTER_API_KEY=your_farcaster_api_key + +# Guild.xyz integration +GUILD_API_KEY=your_guild_api_key + +# ============================================================================= +# DEVELOPMENT +# ============================================================================= +# Set to 'development' for local development +NODE_ENV=development + +# Enable debug mode +DEBUG=false + +# ============================================================================= +# FEATURE FLAGS +# ============================================================================= +# Enable/disable specific features +NEXT_PUBLIC_ENABLE_ANALYTICS=true +NEXT_PUBLIC_ENABLE_EXPERIMENTS=true + +# ============================================================================= +# SECURITY +# ============================================================================= +# CORS origins (comma-separated) +CORS_ORIGINS=http://localhost:3000,https://base.org + +# Rate limiting +RATE_LIMIT_WINDOW_MS=900000 +RATE_LIMIT_MAX_REQUESTS=100