mark/vibn-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3896eb671cbccf6cbab78c5511693fd7aab5f47d
vibn-frontend/SETUP.md

319 lines
8.8 KiB
Markdown
Raw Blame History

# 🚀 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
```bash
cd vibn-frontend
npm install
```
---
## 🔐 Step 2: Environment Variables
Create a `.env.local` file in the `vibn-frontend` directory:
```bash
touch .env.local
```
### Required Environment Variables
Copy and paste the following into `.env.local` and replace with your actual values:
```env
# ===================================
# 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](https://console.firebase.google.com/)
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
```bash
# 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](https://github.com/settings/developers)
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
```bash
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
```bash
# 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**:
```bash
# 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](https://vercel.com)
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`:
```json
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"tailwindCSS.experimental.classRegex": [
["cn\\(([^)]*)\\)", "'([^']*)'"]
]
}
```
---
## 📖 Additional Resources
- [Next.js Documentation](https://nextjs.org/docs)
- [Firebase Documentation](https://firebase.google.com/docs)
- [Tailwind CSS](https://tailwindcss.com/docs)
- [shadcn/ui](https://ui.shadcn.com/)
- [Lucide Icons](https://lucide.dev/)
---
## 💬 Need Help?
- Check the [Project Instructions](../PROJECT_INSTRUCTIONS.md)
- Review the [Firebase Admin Setup](lib/firebase/admin.ts)
- Look at existing [API routes](app/api/) for examples
---
**Status**: ✅ Ready for local development
**Last Updated**: November 2025
Reference in New Issue View Git Blame Copy Permalink