Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v18 or higher)
  • pnpm (v10.11.0 or higher)
  • Docker and Docker Compose (for local database)
  • Git for cloning the repository

​
Setup Steps

Follow these steps to get TypeHero running locally:
1

Fork and Clone the Repository

First, fork the TypeHero repository on GitHub, then clone your fork:
git clone https://github.com/YOUR_USERNAME/typehero.git
cd typehero
2

Create Environment File

Copy the example environment file and configure it:
cp .env.example .env
See the Environment Variables page for detailed configuration.
3

Start Database Services

Start the local MySQL database and Redis using Docker Compose:
docker compose up -d
This will start:
  • MySQL database on port 3306
  • Redis on port 6379
See the Database Setup page for more details.
4

Configure GitHub OAuth

Create a new GitHub OAuth application:
  1. Go to GitHub OAuth Apps
  2. Fill in the required details:
    • Homepage URL: http://localhost:3000
    • Authorization callback URL: http://localhost:3000/api/auth/callback/github
  3. Click “Generate a new client secret”
  4. Copy the Client ID and Client Secret to your .env file:
GITHUB_ID=your_client_id
GITHUB_SECRET=your_client_secret
5

Setup UploadThing

Configure file upload service:
  1. Visit uploadthing.com
  2. Create a new project
  3. Copy the legacy secrets (not SDK v7+) to your .env:
UPLOADTHING_SECRET="your_uploadthing_secret"
UPLOADTHING_APP_ID="your_uploadthing_app_id"
6

Setup Algolia Search

Configure search functionality:
  1. Go to algolia.com
  2. Create a new application
  3. Copy your credentials to .env:
NEXT_PUBLIC_ALGOLIA_APP_ID=your_app_id
NEXT_PUBLIC_ALGOLIA_API_KEY=your_api_key
7

Generate NextAuth Secret

Generate a secure secret for NextAuth:
openssl rand -base64 32
Add it to your .env:
NEXTAUTH_SECRET="generated_secret_here"
NEXTAUTH_URL="http://localhost:3000"
8

Install Dependencies

Install all project dependencies using pnpm:
pnpm install
9

Setup Database Schema

Push the Prisma schema and seed the database:
pnpm db:push
pnpm db:seed
This will:
  • Create all database tables
  • Seed initial data including challenges and tracks
10

Start Development Server

Launch the development server:
pnpm dev
The application will be available at http://localhost:3000
11

Login and Test

  1. Navigate to http://localhost:3000
  2. Login using your GitHub account
  3. Start exploring the application!

​
Make Yourself an Admin

To access admin features during development:
1

Login First

Ensure you’ve logged into your local instance at least once.
2

Open Prisma Studio

Launch the database GUI:
pnpm db:studio
This opens Prisma Studio in your browser.
3

Update User Role

  1. Click on the User table
  2. Find your username
  3. Click to edit the record
  4. Change the roles field to include ADMIN
  5. Save the changes

​
Available Scripts

Here are the most commonly used development scripts: 
# Run development server
pnpm dev

# Run all checks (format, lint, typecheck)
pnpm checks

# Fix formatting and linting issues
pnpm checks:fix

​
Troubleshooting

If you’re having trouble connecting to the database:
  1. Ensure Docker containers are running: docker ps
  2. Check the DATABASE_URL in your .env matches the docker-compose configuration
  3. Try restarting the containers: docker compose restart
To rebuild and reseed from scratch:
pnpm refresh
If that doesn’t work, manually drop the database:
docker exec -it typehero-db bash
mysql -u root -p -h 127.0.0.1 typehero
# Enter password: dev
DROP DATABASE typehero;
exit
exit
pnpm refresh
If port 3000, 3306, or 6379 is already in use:
  1. Find the process: lsof -i :3000 (replace with port number)
  2. Kill it: kill -9 <PID>
  3. Or change the port in your configuration
Try these steps:
  1. Clear pnpm cache: pnpm store prune
  2. Delete node_modules and lock file: rm -rf node_modules pnpm-lock.yaml
  3. Reinstall: pnpm install

​
Next Steps

Environment Variables

Learn about all available configuration options

Database Setup

Deep dive into database configuration and management

Contributing Guide

Ready to contribute? Check out our guidelines

Architecture

Understand the project structure

​
Join the Community

Need help or want to discuss development?

Build docs developers (and LLMs) love

Get started for freeTalk to us