Helping you become a better software engineer through coding challenges that build real applications.

You Build It is an interactive coding challenges platform designed to help developers improve their programming skills through hands-on, practical projects. Unlike traditional algorithmic challenges, our platform focuses on building real-world applications and tools that you'll actually use.

• 🔍 Interactive Challenge Browser - Browse challenges by difficulty, category, and required skills
• 📚 Rich Content Experience - Challenges stored in database with MDX content and syntax highlighting
• 🎨 Modern UI/UX - Beautiful, responsive design with smooth animations
• 🌙 Dark Mode Support - Seamless light/dark theme switching for comfortable coding sessions
• 🔧 Real-World Projects - Build actual tools like Docker, grep, JSON parsers, web servers, and more
• 📊 Skill Tracking - Track the technologies and concepts you learn
• 🚀 Progressive Difficulty - From beginner-friendly to advanced challenges
• 🔐 User Authentication - Secure authentication powered by Clerk
• 💳 Subscription Management - Tiered access (FREE/PRO) with Stripe integration
• 📖 Database-Driven Content - Scalable challenge management with PostgreSQL

• Node.js 18.0 or higher
• pnpm 9.0 or higher (package manager)
• Git for version control
• PostgreSQL (for production) or SQLite (for development)

1. Clone the repository with submodules:

   git clone --recurse-submodules https://github.com/youbuildit/youbuildit.dev.git
   cd youbuildit.dev

   Note: If you've already cloned without submodules, you can initialize them with:

   git submodule update --init --recursive

2. Install dependencies:

   pnpm install

3. Configure environment variables:

   # Copy the example environment file
   cp .env.example .env

   Edit the .env file and add your environment variables (see Environment Variables section below).

4. Run the development server:

   pnpm dev

5. Open your browser: Navigate to http://localhost:3000 to see the application.

├── app/                    # Next.js App Router
│   ├── api/               # API routes
│   │   ├── challenges/    # Challenges API endpoint
│   │   └── commit/        # Commit tracking API
│   ├── challenge/         # Individual challenge pages
│   ├── challenges/        # Challenge browser page
│   ├── layout.tsx         # Root layout
│   └── page.tsx          # Homepage
├── components/            # Reusable React components
│   ├── mdx/              # MDX-specific components
│   ├── sections/         # Page sections (Hero, Features, etc.)
│   └── ui/               # Base UI components
├── prisma/               # Database schema and migrations
│   ├── schema.prisma     # Database schema definition
│   └── migrations/       # Database migration files
├── lib/                  # Utility functions and configuration
├── public/               # Static assets
├── styles/               # Global styles and CSS
└── types/                # TypeScript type definitions

• Next.js 15.5.2 - React framework with App Router
• TypeScript - Type-safe JavaScript
• React 19.1.1 - UI library
• Tailwind CSS - Utility-first CSS framework
• PostgreSQL - Primary database for production
• Prisma - Type-safe database client and ORM

• Framer Motion - Animations and transitions
• shadcn/ui - Copy-paste React components built on Radix UI
• Radix UI - Headless UI primitives
• Clerk - User authentication and management
• Stripe - Payment processing and subscription management
• React Markdown - Markdown rendering for challenge content
• React Syntax Highlighter - Code syntax highlighting
• Lucide React - Icon library
• Heroicons - Additional icon set
• Axios - HTTP client for API requests
• clsx - Utility for constructing className strings
• tailwind-merge - Merge Tailwind CSS classes without conflicts

• ESLint - Code linting with Next.js and Prettier integration
• Prettier - Code formatting
• Husky - Git hooks for pre-commit validation
• lint-staged - Run linters on staged files
• PostCSS - CSS processing
• Autoprefixer - CSS vendor prefixing

The application uses environment variables for configuration. Copy .env.example to .env and configure the following variables:

For development (SQLite):

# Use the default SQLite setup from .env.example
PRISMA_DATABASE_URL="file:./prisma/dev.db"

# Push the schema to create the database
pnpm db:push

For production (PostgreSQL):

# Set up PostgreSQL connection string
PRISMA_DATABASE_URL="postgresql://user:password@localhost:5432/youbuildit"

# Run migrations
pnpm db:migrate

1. Create a Clerk application:

   • Go to Clerk Dashboard
   • Create a new application
   • Copy the publishable key and secret key

2. Add to your .env file:

   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_clerk_publishable_key
   CLERK_SECRET_KEY=sk_test_your_clerk_secret_key

3. Set up Clerk Webhooks:

   Clerk webhooks are required to sync user data between Clerk and your database.

   For Local Development:

   Since Clerk needs to reach your local server, you'll need to use a tunneling service:

   # Install ngrok if you haven't already
   brew install ngrok
   
   # Sign up and get your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken
   ngrok config add-authtoken YOUR_AUTHTOKEN
   
   # Start your development server
   pnpm dev
   
   # In another terminal, expose your local server
   ngrok http 3000

   Copy the https:// URL from ngrok (e.g., https://abc123.ngrok.io)

   Configure Webhook in Clerk Dashboard:

   1. Go to Clerk Dashboard → Configure → Webhooks
   2. Click "Add Endpoint"
   3. Set Endpoint URL to: https://YOUR_NGROK_URL.ngrok.io/api/webhooks/clerk
   4. Subscribe to events: user.created, user.updated, user.deleted
   5. Copy the signing secret from the webhook details

   Add webhook secret to your .env file:

   CLERK_WEBHOOK_SECRET=whsec_your_webhook_signing_secret

1. Create a Stripe account:

   • Go to Stripe Dashboard
   • Get your API keys from the Developers section
   • Create products and prices for PRO tier
   • Set up webhooks endpoint: /api/webhooks/stripe

2. Add to your .env file:

   STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key
   STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
   STRIPE_PRO_MONTHLY_PRICE_ID=price_your_pro_monthly_price_id
   # ... other price IDs

1. Create a GitHub Personal Access Token:

   • Go to GitHub Settings > Developer settings > Personal access tokens
   • Click "Generate new token (classic)"
   • Select scopes: public_repo (for public repositories)
   • Copy the generated token

2. Add to your .env file:

   GITHUB_TOKEN=ghp_your_token_here

# .env

# Database
PRISMA_DATABASE_URL="file:./prisma/dev.db"

# Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_clerk_key
CLERK_SECRET_KEY=sk_test_your_clerk_secret
CLERK_WEBHOOK_SECRET=whsec_your_webhook_secret

# Payments
STRIPE_SECRET_KEY=sk_test_your_stripe_key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_key
STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

# Stripe Price IDs
STRIPE_PRO_MONTHLY_PRICE_ID=price_your_pro_monthly_id
STRIPE_PRO_YEARLY_PRICE_ID=price_your_pro_yearly_id

# Optional
GITHUB_TOKEN=ghp_your_github_token

• Database-Driven Content: Challenges are stored in PostgreSQL with full metadata and MDX content
• Tiered Access: FREE challenges available to all, PRO challenges require subscription
• Rich Metadata: Each challenge includes difficulty, category, skills, estimated time, and more
• Paywall Integration: Non-subscribers see premium challenges with subscription prompts
• Search & Filtering: Advanced filtering by difficulty, category, and skills
• Progress Tracking: User challenge completion tracked in database

• GET /api/challenges - Fetch all challenges with access control and metadata
• GET /api/challenges/random - Get random challenge (with tier filtering)
• GET /api/user/subscription - Get current user subscription status
• POST /api/subscriptions/checkout - Create Stripe checkout session
• POST /api/subscriptions/portal - Access Stripe customer portal
• POST /api/webhooks/clerk - Handle Clerk webhook events (user sync)
• POST /api/webhooks/stripe - Handle Stripe webhook events
• POST /api/commit - Track challenge completion and progress

• Responsive Design: Mobile-first approach with Tailwind CSS
• Animation System: Smooth page transitions and micro-interactions with Framer Motion
• Accessibility: Built with semantic HTML and ARIA attributes
• Dark Mode Support: Full dark mode implementation with automatic system preference detection and manual toggle

The platform offers two subscription tiers with different access levels:

• FREE Tier: Access to 14+ basic challenges covering fundamental concepts
• PRO Tier: Access to all FREE challenges plus 17+ advanced challenges and premium features

All challenges are visible to users, but premium challenges show a subscription prompt for non-subscribers. This allows users to browse all content while maintaining a clear upgrade path.

• Database Storage: Challenge content stored in PostgreSQL with full-text search capabilities
• MDX Rendering: Challenge content rendered from database-stored MDX with React components
• Subscription Control: Content access controlled by user subscription tier
• Syntax Highlighting: Automatic syntax highlighting for code blocks
• Admin Interface: Database-driven content management for scalable challenge creation

• pnpm dev - Start development server
• pnpm build - Build for production
• pnpm start - Start production server
• pnpm db:push - Push schema changes to database (development)
• pnpm db:migrate - Deploy database migrations (production)
• pnpm lint - Run ESLint
• pnpm lint:fix - Run ESLint with auto-fix
• pnpm format - Format code with Prettier
• pnpm format:check - Check code formatting with Prettier
• pnpm prepare - Setup Husky git hooks (runs automatically after install)

The easiest way to deploy is using the Vercel Platform:

1. Push your code to GitHub
2. Import your repository to Vercel
3. Add environment variables in the Vercel dashboard
4. Deploy with automatic builds on every push

• Netlify: Use the pnpm build command and deploy the .next folder
• Docker: Create a Dockerfile based on the Next.js Docker example
• Traditional Hosting: Build static files with pnpm build and serve the output

Check out the Next.js deployment documentation for more details.

• Next.js Documentation - Comprehensive Next.js guide
• Learn Next.js - Interactive tutorial
• React Documentation - Official React docs

• TypeScript Handbook - Complete TypeScript guide
• Next.js with TypeScript - TypeScript integration

• Tailwind CSS Documentation - Utility-first CSS framework
• shadcn/ui Documentation - Component library guide
• Framer Motion - Animation library
• Radix UI - Unstyled UI primitives

• MDX Documentation - Markdown with React components
• Gray Matter - Front matter parsing

Build fails with TypeScript errors:

pnpm lint
pnpm build

Styling issues:

• Clear .next cache: rm -rf .next
• Restart development server: pnpm dev

Challenges not loading:

• Check database connection: PRISMA_DATABASE_URL
• Verify database schema is up to date: pnpm db:push or pnpm db:migrate
• Check authentication setup (Clerk keys)
• Verify challenge data exists in database

1. Search existing issues in the repository
2. Check the documentation for relevant sections
3. Create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs actual behavior
   • System information (OS, Node.js version)

We welcome contributions! Here's how you can help:

• 🐛 Bug Reports: Found a bug? Let us know!
• 💡 Feature Requests: Have an idea? Share it!
• 📝 Documentation: Help improve the docs
• 🎨 Design: UI/UX improvements
• 🗺 Challenges: New coding challenges (see below)

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following the coding standards
4. Test your changes: pnpm lint && pnpm build
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

Challenges are now managed through the database system:

• Challenge Issues: Report typos, errors, or improvements in challenge content
• New Challenges: Submit new challenge ideas through GitHub issues
• Content Management: Challenge content is stored in PostgreSQL for better scalability

• Code Style: Follow existing patterns and use ESLint
• TypeScript: Maintain type safety, avoid any types
• Components: Create reusable, accessible components
• Performance: Consider loading times and bundle size
• Accessibility: Follow WCAG guidelines
• Responsive Design: Ensure mobile compatibility

The project uses automated tools to maintain code quality:

• Pre-commit Hooks: Husky automatically runs ESLint and Prettier on staged files before each commit
• Staged Files: lint-staged ensures only modified files are processed, improving performance
• Automatic Formatting: Code is automatically formatted with Prettier during the pre-commit process
• Lint Fixes: ESLint auto-fixes are applied when possible during pre-commit

We use conventional commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test additions or changes
• chore: Build process or auxiliary tool changes

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with Next.js and React
• Styled with Tailwind CSS
• Animations powered by Framer Motion
• Icons from Lucide
• Fonts by Vercel

Ready to build something amazing? 🚀 Start with your first challenge!