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
• npm 9+ (comes with Node.js)
• Git - Download here
• Backend running - See main README.md

✅ Verify Prerequisites

Run these commands to verify your installation:

# 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

cd TurboTrades/frontend

Step 2: Install Dependencies

# 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:

# 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:

# Windows
type .env

# macOS/Linux
cat .env

Should contain:

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

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

# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

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

Solution 2: Use a different port

npm run dev -- --port 5174

Issue: Module Not Found

Error:

Error: Cannot find module 'vue'

Solution:

# 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:

# 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:

# 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

# 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:

# 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

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

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:

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:

npm install -D @vitejs/plugin-basic-ssl

Edit vite.config.js:

import basicSsl from '@vitejs/plugin-basic-ssl'

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

Customize Theme Colors

Edit tailwind.config.js:

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
   • Vite Docs
   • Tailwind CSS Docs
   • Pinia Docs

✨ 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