Local Development - GitHub Wrapped

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+

JavaScript runtime required for Next.js.Check version:

node --version
# Should output v18.x.x or higher

pnpm (recommended)

Fast, disk-efficient package manager.Install:

npm install -g pnpm

Or use npm/yarn if preferred.

Git

Version control system.Check version:

git --version

PostgreSQL (optional)

Required only if using authentication.Can use hosted services like Supabase or Neon.

Initial Setup

Clone the Repository

git clone https://github.com/yourusername/github-wrapped.git
cd github-wrapped

Install Dependencies

pnpm install

This installs all packages listed in package.json.

First install may take 2-3 minutes. Subsequent installs are cached and much faster.

Configure Environment Variables

Create a .env.local file in the project root:

touch .env.local

Add the following variables:

.env.local

# Optional: GitHub Personal Access Token
# Get one at: https://github.com/settings/tokens
# Increases rate limit from 60/hour to 5,000/hour
GITHUB_TOKEN=ghp_your_token_here

# Optional: Redis Cache (for production-like caching)
# Sign up at: https://upstash.com
UPSTASH_REDIS_REST_URL=https://your-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your_token_here

# Required for Authentication (optional feature)
# PostgreSQL connection string
DATABASE_URL=postgresql://user:password@localhost:5432/github_wrapped

# better-auth configuration
BETTER_AUTH_SECRET=your-random-secret-here
BETTER_AUTH_URL=http://localhost:3000

# GitHub OAuth App (for auth feature)
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

Only GITHUB_TOKEN is recommended for development. Other variables are optional.

Set Up Database (if using auth)

If you’re using authentication features:

# Generate Prisma client
pnpm prisma generate

# Run database migrations
pnpm prisma migrate dev

Skip this step if you’re not working on auth features.

Start Development Server

pnpm dev

This starts the Next.js development server on http://localhost:3000.

▲ Next.js 16.0.7
- Local:        http://localhost:3000
- Environments: .env.local

✓ Ready in 2.3s

Available Scripts

The project includes several npm scripts defined in package.json:

# Start development server with hot reload
pnpm dev

# Runs on http://localhost:3000
# Auto-reloads on file changes

Development Workflow

Hot Reload

Next.js provides automatic hot reload for:

React components - Instant updates without losing state
API routes - Automatic restart on changes
Styles - Live CSS updates
TypeScript - Type checking in background

If hot reload stops working, restart the dev server with Ctrl+C then pnpm dev.

File Watching

The dev server watches these directories:

app/ - Pages and API routes
components/ - React components
lib/ - Business logic
types/ - Type definitions
public/ - Static assets

TypeScript Integration

TypeScript errors appear in:

Terminal - Real-time type checking
Browser - Overlay with error details
IDE - Inline errors (VS Code, etc.)

# Manual type check
npx tsc --noEmit

Debugging Tips

Browser DevTools

React DevTools

Install React DevTools browser extension.Features:

Inspect component tree
View props and state
Track re-renders
Profile performance

Network Tab

Monitor API requests:

Open DevTools (F12)
Go to Network tab
Filter by “Fetch/XHR”
Inspect API calls to /api/wrapped, /api/validate, etc.

Look for:

Response times
Status codes
Request/response payloads
Rate limit headers

Console Logging

Use strategic console logs:

// Client components
console.log('User input:', { owner, repo, year })

// API routes
console.log('Fetching wrapped data for:', owner, repo)

// Services
console.log('GitHub API response:', data)

Remove console.logs before committing to production!

VS Code Debugger

Add .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "pnpm dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    }
  ]
}

Then press F5 to start debugging with breakpoints.

Common Issues

Port 3000 already in use

Error:

Error: listen EADDRINUSE: address already in use :::3000

Solutions:

# Option 1: Kill process on port 3000
# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Option 2: Use different port
pnpm dev -- -p 3001

TypeScript errors on startup

Error:

Type error: Cannot find module '@/types'

Solution:

# Reinstall dependencies
rm -rf node_modules .next
pnpm install

# Restart dev server
pnpm dev

GitHub API rate limit exceeded

Error:

{ "error": "API rate limit exceeded" }

Solutions:

Add GITHUB_TOKEN to .env.local
Wait for rate limit reset (check headers)
Use cache to avoid repeated requests

Check remaining requests:

curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/rate_limit

Redis connection failed

Error:

Error connecting to Redis

Solution:The app automatically falls back to in-memory cache. This is expected in development.To use Redis in development:

Sign up for Upstash Redis
Create a database
Add credentials to .env.local

Module not found errors

Error:

Module not found: Can't resolve '@/components/Button'

Solution:

# Clear Next.js cache
rm -rf .next

# Restart dev server
pnpm dev

Testing Features Locally

Test Repository Input

Go to http://localhost:3000
Enter a repository (e.g., facebook/react)
Select year (e.g., 2024)
Click “Generate Wrapped”

Test API Endpoints

Use curl or Postman to test API routes:

# Validate repository
curl -X POST http://localhost:3000/api/validate \
  -H "Content-Type: application/json" \
  -d '{"owner":"facebook","repo":"react"}'

# Generate wrapped
curl -X POST http://localhost:3000/api/wrapped \
  -H "Content-Type: application/json" \
  -d '{"owner":"facebook","repo":"react","year":2024}'

Test Dark Mode

Click the theme toggle in the navbar
Verify all components render correctly
Check localStorage: localStorage.getItem('theme')

Test Mobile Responsiveness

Open DevTools (F12)
Click device toolbar (Ctrl+Shift+M)
Test different screen sizes:
- Mobile: 375px (iPhone)
- Tablet: 768px (iPad)
- Desktop: 1920px

Performance Profiling

Next.js Build Analysis

# Analyze bundle size
pnpm build

# Output shows page sizes:
# ┌ ○ /               1.2 kB
# ├ ○ /wrapped/[...] 2.5 kB
# └ λ /api/wrapped   0 B

React Profiler

Install React DevTools
Open Profiler tab
Click “Record”
Interact with the app
Stop recording
Analyze render times

Environment-Specific Configuration

Development Mode

Development mode includes:

Hot reload
Detailed error messages
Unminified code
Source maps
Rate limit bypass (in lib/github.ts:23)

Production Mode

Production builds include:

Minified code
Optimized images
Static generation
Tree shaking
Code splitting

Next Steps

Project Structure

Learn about the codebase organization

Architecture

Understand the system design

Contributing

Start contributing to the project

API Reference

Explore API endpoints

Join our Discord community for real-time help with development!

Architecture

Contributing

​Prerequisites

Node.js 18+

pnpm (recommended)

Git

PostgreSQL (optional)

​Initial Setup

​Available Scripts

​Development Workflow

​Hot Reload

​File Watching

​TypeScript Integration

​Debugging Tips

​Browser DevTools

​Common Issues

​Testing Features Locally

​Test Repository Input

​Test API Endpoints

​Test Dark Mode

​Test Mobile Responsiveness

​Performance Profiling

​Next.js Build Analysis

​React Profiler

​Environment-Specific Configuration

​Development Mode

​Production Mode

​Next Steps

Project Structure

Architecture

Contributing

API Reference

Build docs developers (and LLMs) love

Prerequisites

Initial Setup

Available Scripts

Development Workflow

Hot Reload

File Watching

TypeScript Integration

Debugging Tips

Browser DevTools

Common Issues

Testing Features Locally

Test Repository Input

Test API Endpoints

Test Dark Mode

Test Mobile Responsiveness

Performance Profiling

Next.js Build Analysis

React Profiler

Environment-Specific Configuration

Development Mode

Production Mode

Next Steps