Skip to main content

​
Get Started in 3 Steps

This guide will help you set up the AI Hackathon Guide locally and start using the AI chat assistant to find the best tools for your hackathon project.
1

Clone and Install

Clone the repository and install dependencies:
git clone https://github.com/ayomidecole/AI-Hackathon-Guide.git
cd AI-Hackathon-Guide
npm install
This project uses npm as the package manager. Make sure you have Node.js 18+ installed.
2

Configure OpenAI API

The AI chat assistant requires an OpenAI API key. Get yours at platform.openai.com/api-keys.
Copy the example environment file and add your API key:
cp .env.example .env
Then edit .env and add:
OPENAI_API_KEY="your_api_key_here"
Never commit your .env file or API keys to version control. The .env file is already in .gitignore.
3

Run the Development Server

Start the Vite dev server:
npm run dev
The app will be available at http://localhost:5173. The dev server includes:
  • Hot module replacement for instant updates
  • API middleware at /api/chat for the AI assistant
  • TypeScript type checking

​
Using the AI Chat Assistant

Once the dev server is running, you can access the AI chat assistant from the sidebar:
Ask general questions about tools, frameworks, or hackathon strategies:Example questions:
  • “What’s the difference between Clerk and Auth0?”
  • “How do I add realtime features to my app?”
  • “Which deployment platform should I use for Next.js?”
The assistant uses gpt-4o-mini for fast, cost-effective responses.
Click “Suggest a stack” to get personalized tech stack recommendations.The assistant will:
  1. Ask clarifying questions about your project (frontend framework, features needed, etc.)
  2. Analyze the available tools in the guide
  3. Return a complete stack recommendation with explanations
This mode uses gpt-4o with structured JSON output for reliable recommendations.

​
Available Commands

Here are all the commands you’ll need during development: 
npm run dev

​
Command Details

CommandDescription
npm run devStarts Vite dev server with HMR and API middleware at /api/chat
npm run buildFull production build: TypeScript check → Vite build → esbuild API bundle
npm run build:apiBuilds only the serverless chat function (server/chat.ts → api/chat.js)
npm run lintRuns ESLint on all TypeScript files
npm run previewPreviews the production build locally
npm run testRuns Vitest in watch mode (auto-reruns on file changes)
npm run test:runRuns the full test suite once (use before committing)
npm run test:coverageGenerates coverage report (opens coverage/index.html in browser)

​
Testing Your Setup

Verify everything is working correctly:
1

Check the Homepage

Navigate to http://localhost:5173 and verify:
  • Tool sections load (Development Tools, Databases, Auth, etc.)
  • Tool cards are visible and expandable
  • Theme toggle works (dark/light mode)
2

Test the Chat Assistant

Open the chat panel from the sidebar and:
  1. Send a simple question like “What is Cursor?”
  2. Verify you get a response (if you see an error, check your API key)
  3. Try the “Suggest a stack” button
3

Run the Test Suite

Ensure all tests pass:
npm run test:run
The project uses Vitest with React Testing Library and happy-dom.

​
Deploying to Production

The guide is optimized for Vercel deployment:
1

Push to GitHub

Ensure your code is committed and pushed to a GitHub repository.
2

Import to Vercel

  1. Go to vercel.com/new
  2. Import your GitHub repository
  3. Vercel will auto-detect the Vite configuration
3

Add Environment Variables

In your Vercel project settings:
  1. Navigate to Project Settings → Environment Variables
  2. Add OPENAI_API_KEY with your API key
  3. Redeploy to apply the changes
Vercel automatically builds both the static site (dist/) and the serverless API function (api/chat.js) based on the vercel.json configuration.

​
Project Structure

Understanding the architecture will help you navigate and contribute: 
ai-hackathon-guide/
├── src/                    # React frontend
│   ├── App.tsx            # Root layout with sidebar + chat
│   ├── components/        # UI components (ToolCard, ChatPanel, etc.)
│   ├── content/
│   │   └── sections.ts    # All tool data (single source of truth)
│   └── index.css          # Theme colors and Tailwind
├── shared/
│   └── chatPolicy.ts      # Chat logic (used by both dev + prod)
├── server/
│   └── chat.ts            # Vercel serverless handler
├── api/
│   └── chat.js            # Built serverless function (generated)
├── dist/                  # Production build output (generated)
└── vercel.json            # Vercel deployment config

​
Key Files

Single source of truth for all tool data.Each Section contains:
  • id: Unique identifier
  • title: Display name
  • tools: Array of Tool objects
Each Tool includes:
  • Basic info: name, tagline, description, url
  • Features: bullets array
  • Details: detailsGuide, detailsVideo, detailsSections
Adding a new tool means editing this file—the UI and chat automatically pick it up.
All chat logic in one place.Handles:
  • Message sanitization
  • System prompts
  • OpenAI API calls
  • Stack suggestion mode (structured JSON)
  • Tool ranking and filtering
Used identically in:
  • Development (via Vite middleware in vite.config.ts)
  • Production (via server/chat.ts serverless function)
Thin Vercel serverless handler.Delegates all logic to shared/chatPolicy.ts. Built to api/chat.js using esbuild:
npm run build:api

​
Next Steps

Now that you’re set up, explore the guide:

Explore Development Tools

Check out Cursor, Codex, Replit, and other AI-powered editors

Browse Databases & Auth

See all databases, auth services, deployment platforms, and APIs

AI Chat Features

Learn about the AI chat assistant and tech stack recommendations

Contribute

Add new tools, fix bugs, or improve documentation

​
Troubleshooting

Possible causes:
  1. Missing API key: Verify OPENAI_API_KEY is set in .env or environment
  2. Invalid API key: Check that your key is correct at platform.openai.com
  3. No credits: Ensure your OpenAI account has available credits
  4. Rate limiting: Free tier has usage limits; wait or upgrade
Check the browser console for detailed error messages.
If port 5173 is taken:
# Kill the process using the port
lsof -ti:5173 | xargs kill -9

# Or let Vite choose another port
npm run dev -- --port 3000
Common issues:
  1. Outdated dependencies: Run npm install
  2. TypeScript errors: Run npm run build to see type errors
  3. Coverage threshold: The project requires 80% coverage (configured in Vitest)
View the coverage report:
npm run test:coverage
open coverage/index.html
Build fails:
  • Verify vercel.json is present
  • Check build logs for TypeScript or dependency errors
Chat doesn’t work in production:
  • Ensure OPENAI_API_KEY is set in Vercel environment variables
  • Redeploy after adding env vars
  • Check Function logs in Vercel dashboard
For additional help, check the GitHub Issues or ask in the AI chat assistant using the deployed site at deepwiki.com.

Build docs developers (and LLMs) love

Get started for freeTalk to us