vibn-frontend/SETUP.md

🚀 VIBN Local Development Setup

Complete guide to running VIBN locally on your machine.

✅ Prerequisites

• Node.js 18+ (check with node --version)
• npm or pnpm package manager
• Firebase Project (for authentication and database)
• GitHub OAuth App (optional, for GitHub integration)

---

📦 Step 1: Install Dependencies

cd vibn-frontend
npm install

---

🔐 Step 2: Environment Variables

Create a .env.local file in the vibn-frontend directory:

touch .env.local

Required Environment Variables

Copy and paste the following into .env.local and replace with your actual values:

# ===================================
# Firebase Client Config (Public)
# Get these from Firebase Console > Project Settings > General
# ===================================
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_firebase_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-XXXXXXXXXX

# ===================================
# Firebase Admin Config (Server-side ONLY)
# Get these from Firebase Console > Project Settings > Service Accounts
# Click "Generate New Private Key" to download JSON file
# ===================================
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your_project_id.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour_Private_Key_Here\n-----END PRIVATE KEY-----\n"

# ===================================
# GitHub OAuth (Optional)
# Create an OAuth App at: https://github.com/settings/developers
# Authorization callback URL: http://localhost:3000/api/github/oauth/callback
# ===================================
NEXT_PUBLIC_GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret

---

🔥 Step 3: Firebase Setup

3.1 Get Firebase Credentials

1. Go to Firebase Console
2. Select your project (or create a new one)
3. Navigate to Project Settings (⚙️ icon)

Client Config (Public):

• Under General tab, scroll to "Your apps"
• Copy the firebaseConfig values
• These go in NEXT_PUBLIC_FIREBASE_* variables

Admin Config (Private):

• Go to Service Accounts tab
• Click Generate New Private Key
• Download the JSON file
• Extract values:
  • FIREBASE_PROJECT_ID = project_id from JSON
  • FIREBASE_CLIENT_EMAIL = client_email from JSON
  • FIREBASE_PRIVATE_KEY = private_key from JSON (keep the \n characters!)

3.2 Enable Authentication

1. In Firebase Console, go to Authentication → Sign-in method
2. Enable Email/Password
3. Enable Google (optional)

3.3 Setup Firestore

1. In Firebase Console, go to Firestore Database
2. Click Create database
3. Choose Start in production mode (we have custom rules)
4. Select a location (closest to your users)

3.4 Deploy Firestore Rules & Indexes

# Deploy security rules
npm run firebase:deploy:rules

# Deploy indexes
npm run firebase:deploy:indexes

---

🐙 Step 4: GitHub OAuth Setup (Optional)

Only needed if you want to test GitHub repository integration.

1. Go to GitHub Developer Settings
2. Click New OAuth App
3. Fill in:
   • Application name: VIBN Local
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: http://localhost:3000/api/github/oauth/callback
4. Copy Client ID → NEXT_PUBLIC_GITHUB_CLIENT_ID
5. Generate Client Secret → GITHUB_CLIENT_SECRET

---

🏃 Step 5: Run the Development Server

npm run dev

The app will be available at http://localhost:3000

First Time Setup

1. Create an account: Click "Get Started" or go to /auth
2. Sign up with email/password or Google
3. Create your first project: Click "New Project"
4. Start coding: Open your project in Cursor and install the monitor extension

---

📂 Development Scripts

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Lint code
npm run lint

# Deploy Firebase rules
npm run firebase:deploy:rules

# Deploy Firebase indexes
npm run firebase:deploy:indexes

# Run Firebase emulators (test without production database)
npm run firebase:emulators

---

🛠️ Troubleshooting

Firebase Admin "Credentials not configured"

Problem: API routes throw errors about Firebase Admin not being initialized.

Solution: Make sure your .env.local has all three FIREBASE_* variables (not NEXT_PUBLIC_):

• FIREBASE_PROJECT_ID
• FIREBASE_CLIENT_EMAIL
• FIREBASE_PRIVATE_KEY

Make sure the private key includes \n for newlines and is wrapped in quotes.

"Failed to fetch" or CORS errors

Problem: Client can't connect to Firebase.

Solution:

1. Check that all NEXT_PUBLIC_FIREBASE_* variables are set correctly
2. Make sure Firebase Authentication is enabled in the console
3. Check browser console for specific error messages

Dev server won't start

Problem: Port 3000 is already in use.

Solution:

# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 npm run dev

Changes not showing up

Problem: You made code changes but they're not reflected in the browser.

Solution:

1. Hard refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
2. Clear Next.js cache: rm -rf .next
3. Restart the dev server

---

📁 Project Structure

vibn-frontend/
├── app/                        # Next.js App Router
│   ├── (marketing)/           # Marketing site (public)
│   │   └── page.tsx           # Homepage
│   ├── [workspace]/           # Workspace pages (authenticated)
│   │   ├── projects/          # Projects list
│   │   ├── connections/       # API connections & keys
│   │   └── project/[id]/      # Individual project pages
│   ├── auth/                  # Authentication pages
│   ├── api/                   # API routes
│   │   ├── sessions/          # Session tracking
│   │   ├── projects/          # Project management
│   │   ├── github/            # GitHub OAuth
│   │   └── stats/             # Analytics
│   └── layout.tsx             # Root layout
├── components/                 # React components
│   ├── layout/                # Layout components (left rail, sidebar, etc)
│   ├── ui/                    # shadcn/ui components
│   └── *.tsx                  # Feature components
├── lib/                       # Utility libraries
│   ├── firebase/              # Firebase config & admin
│   ├── github/                # GitHub OAuth
│   └── utils.ts               # Helper functions
├── marketing/                 # Marketing content & components
│   ├── components/            # Marketing-specific components
│   └── content/               # Marketing copy
├── public/                    # Static assets
├── firestore.rules            # Firestore security rules
├── firestore.indexes.json     # Firestore indexes
└── .env.local                 # Environment variables (YOU CREATE THIS)

---

🌐 Production Deployment

This project is configured for Vercel deployment:

1. Push to GitHub
2. Connect your repo to Vercel
3. Add all environment variables in Vercel dashboard
4. Deploy automatically on push to main

Firebase Hosting is also configured but Vercel is recommended for Next.js.

---

✨ VS Code Tips

Recommended Extensions

• ESLint - Code linting
• Tailwind CSS IntelliSense - Tailwind autocomplete
• Prettier - Code formatting
• Firebase - Firebase syntax highlighting

Settings

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "tailwindCSS.experimental.classRegex": [
    ["cn\\(([^)]*)\\)", "'([^']*)'"]
  ]
}

---

📖 Additional Resources

• Next.js Documentation
• Firebase Documentation
• Tailwind CSS
• shadcn/ui
• Lucide Icons

---

💬 Need Help?

• Check the Project Instructions
• Review the Firebase Admin Setup
• Look at existing API routes for examples

---

Status: ✅ Ready for local development Last Updated: November 2025