first commit
This commit is contained in:
437
frontend/INSTALLATION.md
Normal file
437
frontend/INSTALLATION.md
Normal file
@@ -0,0 +1,437 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user