Skip to main content
This guide walks you through setting up GitRead for local development, from installing dependencies to running the development server.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js - Latest LTS version recommended
  • npm or yarn - Package manager
  • Python 3.10.0 - For reference if working with the ingestion service
  • Git - Version control

​
Required accounts

You’ll also need accounts for these services:

​
Installation

1

Clone the repository

git clone https://github.com/vmath20/gitread.git
cd gitread
2

Install Node.js dependencies

npm install
Or if you prefer yarn:
yarn install
This will install all required dependencies including:
  • Next.js 14
  • React 18
  • Clerk authentication
  • Supabase client
  • Stripe integration
  • OpenAI SDK (for OpenRouter)
3

Install Python dependencies (optional)

If you plan to work with or understand the ingestion service logic:
pip install -r requirements.txt
The main application calls a hosted Python API for repository ingestion, so this step is primarily for reference.
4

Configure environment variables

Create a .env.local file in the root directory:
touch .env.local
Add all required environment variables. See the environment variables guide for a complete reference.
5

Set up the Supabase database

  1. Go to your Supabase project dashboard
  2. Navigate to the SQL Editor
  3. Run the migrations in supabase/migrations/ in order:
    • 20240320000000_rls_policies.sql
    • 20240320000000_add_credit_transaction.sql
This creates the necessary tables:
  • user_credits - Stores user credit balances
  • generated_readmes - Stores README generation history
  • processed_stripe_events - Tracks processed payment events
Row Level Security (RLS) policies are automatically applied to protect user data.
6

Start the development server

npm run dev
The application will start on http://localhost:3000

​
Project structure

Understanding the codebase structure: 
vmath20-gitread/
├── app/                     # Next.js App Router
│   ├── api/                 # Backend API routes
│   │   ├── create-checkout-session/ # Stripe checkout
│   │   ├── credits/           # User credit management
│   │   ├── generate/          # README generation logic
│   │   ├── readme-history/    # User README history
│   │   └── verify-payment/    # Stripe payment verification
│   ├── components/          # React components (UI elements)
│   ├── utils/               # Utility functions, Supabase client
│   ├── (pages)/             # UI Pages (Home, Terms, Privacy)
│   ├── layout.tsx           # Root layout with ClerkProvider
│   └── page.tsx             # Main application page
├── middleware.ts            # Next.js middleware (routing, auth)
├── public/                  # Static assets (images, favicons)
├── scripts/                 # Python scripts
│   └── git_ingest.py        # Ingestion service reference
├── supabase/                # Supabase migrations
│   └── migrations/          # SQL migration files
├── package.json             # Node.js dependencies
├── requirements.txt         # Python dependencies
├── tailwind.config.js       # Tailwind CSS configuration
└── tsconfig.json            # TypeScript configuration

​
Key API endpoints

The application provides these API routes:
  • POST /api/generate - Generate README from repository URL
  • GET /api/credits - Fetch current user’s credit balance
  • POST /api/credits - Update user’s credit balance
  • POST /api/create-checkout-session - Create Stripe checkout session
  • POST /api/verify-payment - Verify Stripe payment and update credits
  • GET /api/readme-history - Retrieve user’s generated READMEs
  • POST /api/readme-history - Save generated README to history

​
Development workflow

​
Making changes

  1. Frontend changes - Edit files in app/components/ or app/page.tsx
  2. API changes - Modify routes in app/api/
  3. Styling - Update Tailwind classes or app/globals.css
  4. Database - Create new migrations in supabase/migrations/

​
Testing locally

1

Test authentication

Navigate to http://localhost:3000 and try signing up or signing in.
2

Test README generation

  1. Sign in to get credits
  2. Enter a GitHub repository URL
  3. Click “Generate README”
  4. Verify the README is generated and your credits are decremented
3

Test payment flow

Use Stripe test cards to verify the payment integration:
  • Success: 4242 4242 4242 4242
  • Decline: 4000 0000 0000 0002

​
Common development tasks

​
Adding a new API endpoint

  1. Create a new folder in app/api/
  2. Add a route.ts file
  3. Export GET, POST, or other HTTP method handlers
  4. Use getAuth(req) for authentication

​
Updating the database schema

  1. Create a new migration file in supabase/migrations/
  2. Write SQL to modify tables or policies
  3. Run the migration in Supabase SQL Editor
  4. Update TypeScript types if needed

​
Adding new environment variables

  1. Add the variable to .env.local
  2. Update the environment variables guide
  3. Access in code: process.env.VARIABLE_NAME
  4. Restart the development server
Never commit .env.local to version control. The .gitignore file already excludes it.

​
Troubleshooting

​
Port already in use

# Kill the process on port 3000
lsof -ti:3000 | xargs kill -9

# Or use a different port
npm run dev -- -p 3001

​
Database connection errors

  1. Verify your Supabase URL and keys in .env.local
  2. Check that your Supabase project is active
  3. Ensure RLS policies are correctly set up
  4. Test the connection in Supabase dashboard

​
API errors

  1. Check the terminal for error logs
  2. Verify all environment variables are set
  3. Ensure external services (Clerk, Stripe, OpenRouter) are accessible
  4. Check API rate limits

​
Build errors

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules
npm install

# Rebuild
npm run build

​
Git ingestion service

The repository ingestion logic is handled by an external API:
  • Endpoint: https://gitread-api.onrender.com/ingest
  • Method: POST
  • Authentication: Requires PYTHON_API_KEY in headers
The service uses the gitingest library to:
  1. Clone the GitHub repository
  2. Analyze repository structure
  3. Extract and summarize file contents
  4. Estimate token counts
  5. Return processed data for AI generation
A reference implementation is available in scripts/git_ingest.py.

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us