TurboTrades/frontend/INSTALLATION.md

# TurboTrades Frontend - Installation & Setup Guide

## 📋 Prerequisites Checklist

Before you begin, ensure you have the following installed:

- [ ] **Node.js 18+** - [Download here](https://nodejs.org/)
- [ ] **npm 9+** (comes with Node.js)
- [ ] **Git** - [Download here](https://git-scm.com/)
- [ ] **Backend running** - See main README.md

## ✅ Verify Prerequisites

Run these commands to verify your installation:

```bash
# Check Node.js version (should be 18 or higher)
node --version

# Check npm version (should be 9 or higher)
npm --version

# Check Git version
git --version
```

Expected output:
```
v18.x.x or higher
9.x.x or higher
git version 2.x.x or higher
```

## 🚀 Installation Steps

### Step 1: Navigate to Frontend Directory

```bash
cd TurboTrades/frontend
```

### Step 2: Install Dependencies

```bash
# Clean install (recommended)
npm ci

# OR regular install
npm install
```

**This will install:**
- Vue 3.4.21
- Vite 5.2.8
- Vue Router 4.3.0
- Pinia 2.1.7
- Axios 1.6.8
- Tailwind CSS 3.4.3
- Lucide Vue Next 0.356.0
- Vue Toastification 2.0.0-rc.5
- And more...

**Expected output:**
```
added XXX packages in YYs
```

### Step 3: Verify Installation

Check if all dependencies are installed:

```bash
# List installed packages
npm list --depth=0
```

You should see all the packages from package.json listed.

### Step 4: Environment Configuration

The `.env` file is already created with defaults. Verify it exists:

```bash
# Windows
type .env

# macOS/Linux
cat .env
```

Should contain:
```env
VITE_API_URL=http://localhost:3000
VITE_WS_URL=ws://localhost:3000
VITE_APP_NAME=TurboTrades
VITE_APP_URL=http://localhost:5173
```

### Step 5: Start Development Server

```bash
npm run dev
```

**Expected output:**
```
  VITE v5.2.8  ready in XXX ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help
```

### Step 6: Verify Frontend is Running

Open your browser and navigate to:
```
http://localhost:5173
```

You should see:
- ✅ TurboTrades homepage
- ✅ Navigation bar with logo
- ✅ "Sign in through Steam" button
- ✅ Hero section with CTA buttons
- ✅ Features section
- ✅ Footer

## 🔍 Troubleshooting

### Issue: Port 5173 Already in Use

**Error:**
```
Port 5173 is in use, trying another one...
```

**Solution 1:** Kill the process using port 5173
```bash
# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:5173 | xargs kill -9
```

**Solution 2:** Use a different port
```bash
npm run dev -- --port 5174
```

### Issue: Module Not Found

**Error:**
```
Error: Cannot find module 'vue'
```

**Solution:**
```bash
# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install
```

### Issue: EACCES Permission Error

**Error:**
```
npm ERR! code EACCES
```

**Solution:**
```bash
# Fix npm permissions (Unix/macOS)
sudo chown -R $USER:$(id -gn $USER) ~/.npm
sudo chown -R $USER:$(id -gn $USER) ~/.config

# OR run with sudo (not recommended)
sudo npm install
```

### Issue: Tailwind Classes Not Working

**Solution:**
```bash
# Restart the dev server
# Press Ctrl+C to stop
npm run dev
```

### Issue: Cannot Connect to Backend

**Error in console:**
```
Network Error: Failed to fetch
```

**Solution:**
1. Verify backend is running on port 3000
2. Check proxy settings in `vite.config.js`
3. Ensure CORS is configured in backend

```bash
# In another terminal, check backend
cd ../
npm run dev
```

### Issue: WebSocket Connection Failed

**Error in console:**
```
WebSocket connection to 'ws://localhost:3000/ws' failed
```

**Solution:**
1. Verify backend WebSocket server is running
2. Check backend logs for WebSocket errors
3. Verify no firewall blocking WebSocket

### Issue: Slow HMR or Build

**Solution:**
```bash
# Clear Vite cache
rm -rf node_modules/.vite

# Restart dev server
npm run dev
```

## 🧪 Testing the Installation

### 1. Test Navigation

- [ ] Click "Browse Market" - should navigate to `/market`
- [ ] Click "FAQ" - should navigate to `/faq`
- [ ] Click logo - should navigate to `/`

### 2. Test Responsive Design

- [ ] Resize browser window
- [ ] Mobile menu should appear on small screens
- [ ] Navigation should stack vertically

### 3. Test WebSocket Connection

Open browser DevTools (F12) → Console:

You should see:
```
Connecting to WebSocket: ws://localhost:3000/ws
WebSocket connected
```

### 4. Test Steam Login Flow

**Prerequisites:** Backend must be running with valid Steam API key

1. Click "Sign in through Steam" button
2. Should redirect to Steam OAuth page (if backend configured)
3. OR show error if backend not configured

### 5. Test Theme

- [ ] Check dark background colors
- [ ] Orange primary color on buttons
- [ ] Hover effects on interactive elements
- [ ] Smooth transitions

## 📦 Build for Production

### Create Production Build

```bash
npm run build
```

**Expected output:**
```
vite v5.2.8 building for production...
✓ XXX modules transformed.
dist/index.html                   X.XX kB │ gzip: X.XX kB
dist/assets/index-XXXXX.css      XX.XX kB │ gzip: X.XX kB
dist/assets/index-XXXXX.js      XXX.XX kB │ gzip: XX.XX kB
✓ built in XXXms
```

### Preview Production Build

```bash
npm run preview
```

Should start server on `http://localhost:4173`

### Verify Production Build

1. Check `dist/` folder exists
2. Open `http://localhost:4173` in browser
3. Test functionality (should work identically to dev)

## 🔧 Advanced Configuration

### Change API URL

Edit `.env`:
```env
VITE_API_URL=https://your-backend.com
VITE_WS_URL=wss://your-backend.com
```

Restart dev server after changes.

### Enable HTTPS in Development

Install `@vitejs/plugin-basic-ssl`:
```bash
npm install -D @vitejs/plugin-basic-ssl
```

Edit `vite.config.js`:
```javascript
import basicSsl from '@vitejs/plugin-basic-ssl'

export default defineConfig({
  plugins: [vue(), basicSsl()],
  server: {
    https: true
  }
})
```

### Customize Theme Colors

Edit `tailwind.config.js`:
```javascript
theme: {
  extend: {
    colors: {
      primary: {
        500: '#YOUR_COLOR_HERE'
      }
    }
  }
}
```

## 📊 Installation Verification Checklist

After installation, verify:

- [ ] `node_modules/` folder exists and is populated
- [ ] `package-lock.json` exists
- [ ] `.env` file exists with correct values
- [ ] Dev server starts without errors
- [ ] Frontend opens in browser at `http://localhost:5173`
- [ ] No console errors in browser DevTools
- [ ] Tailwind styles are applied (dark background)
- [ ] Navigation works
- [ ] WebSocket connects (check console)
- [ ] Hot reload works (edit a file and save)

## 🎓 Next Steps

After successful installation:

1. **Read the Documentation**
   - `README.md` - Full frontend documentation
   - `QUICKSTART.md` - Quick start guide
   - `../README.md` - Backend documentation

2. **Explore the Code**
   - Check `src/views/` for page components
   - Review `src/stores/` for state management
   - Look at `src/components/` for reusable components

3. **Start Development**
   - Create a new branch
   - Add features or fix bugs
   - Test thoroughly
   - Submit pull request

4. **Configure Your Editor**
   - Install Volar extension (VS Code)
   - Enable Tailwind CSS IntelliSense
   - Configure ESLint
   - Set up Prettier

## 📞 Getting Help

If you encounter issues not covered here:

1. **Check Documentation**
   - Frontend README.md
   - Backend README.md
   - QUICKSTART.md

2. **Search Existing Issues**
   - GitHub Issues tab
   - Stack Overflow

3. **Ask for Help**
   - Create GitHub issue
   - Discord community
   - Email: support@turbotrades.com

4. **Common Resources**
   - [Vue 3 Docs](https://vuejs.org)
   - [Vite Docs](https://vitejs.dev)
   - [Tailwind CSS Docs](https://tailwindcss.com)
   - [Pinia Docs](https://pinia.vuejs.org)

## ✨ Success!

If you've completed all steps without errors, congratulations! 🎉

Your TurboTrades frontend is now installed and running.

You can now:
- ✅ Browse the marketplace
- ✅ View item details
- ✅ Access profile pages
- ✅ Use all frontend features
- ✅ Start developing new features

**Happy coding!** 🚀

---

**Last Updated:** January 2025  
**Version:** 1.0.0  
**Support:** support@turbotrades.com