Skip to main content

Local Development Setup

Get CheerKeeper running on your local machine for development.

Prerequisites​

  • Node.js 18+ (LTS recommended)
  • npm or pnpm
  • PostgreSQL (or use Neon for cloud database)
  • Git

Repository Structure​

cheerkeeper/
├── cheerkeeper-admin/    # Next.js web admin dashboard
├── cheerkeeper-app/      # Expo React Native mobile app
├── cheerkeeper-docs/     # This documentation site
└── packages/             # Shared packages

Admin Dashboard Setup​

1. Clone the Repository​

git clone https://github.com/cheerkeeper/cheerkeeper.git
cd cheerkeeper/cheerkeeper-admin

2. Install Dependencies​

npm install

3. Environment Variables​

Copy the example environment file:

cp .env.example .env

Required variables:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/cheerkeeper"

# Auth
JWT_SECRET="your-jwt-secret-min-32-chars"
JWT_REFRESH_SECRET="your-refresh-secret-min-32-chars"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-nextauth-secret"

# Google OAuth (optional)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# AI Features (optional)
ANTHROPIC_API_KEY="your-anthropic-api-key"

4. Database Setup​

Initialize the database:

npx prisma db push

Optionally seed with sample data:

npx prisma db seed

5. Start Development Server​

npm run dev

Open http://localhost:3000

Mobile App Setup​

1. Navigate to App Directory​

cd cheerkeeper/cheerkeeper-app

2. Install Dependencies​

npm install

3. Start Expo​

npx expo start

4. Run on Device/Simulator​

  • Press i for iOS Simulator
  • Press a for Android Emulator
  • Scan QR code with Expo Go app for physical device

Development Workflow​

Running Both Admin and Mobile​

Open two terminals:

Terminal 1 - Admin:

cd cheerkeeper-admin
npm run dev

Terminal 2 - Mobile:

cd cheerkeeper-app
npx expo start

Database GUI​

View and edit data with Prisma Studio:

cd cheerkeeper-admin
npx prisma studio

Opens at http://localhost:5555

Code Formatting​

npm run lint        # Check for issues
npm run lint:fix    # Auto-fix issues
npm run format      # Format with Prettier

Type Checking​

npm run typecheck

Tech Stack Reference​

Admin Dashboard​

  • Framework: Next.js 16 (App Router)
  • Language: TypeScript
  • Styling: Tailwind CSS + shadcn/ui
  • Database: PostgreSQL + Prisma ORM
  • Auth: JWT + NextAuth.js (Google OAuth)
  • State: TanStack Query

Mobile App​

  • Framework: Expo SDK 54
  • Language: TypeScript
  • Navigation: Expo Router
  • Storage: expo-sqlite + AsyncStorage

Common Issues​

Database Connection Failed​

  • Verify PostgreSQL is running
  • Check DATABASE_URL format
  • Ensure database exists

Prisma Errors​

# Reset Prisma client
npx prisma generate

# Reset database (⚠️ deletes data)
npx prisma db push --force-reset

Port Already in Use​

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

Expo Issues​

# Clear cache
npx expo start --clear

# Reset dependencies
rm -rf node_modules && npm install

Next Steps​