first commit
This commit is contained in:
566
frontend/TROUBLESHOOTING.md
Normal file
566
frontend/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,566 @@
|
||||
# TurboTrades Frontend - Troubleshooting Guide
|
||||
|
||||
This guide covers common issues and their solutions when working with the TurboTrades frontend.
|
||||
|
||||
## 🔴 CSS/Tailwind Issues
|
||||
|
||||
### Issue: "The `border-border` class does not exist"
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
[postcss] The `border-border` class does not exist
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
This has been fixed in the latest version. If you still see this error:
|
||||
|
||||
1. Clear Vite cache:
|
||||
```bash
|
||||
rm -rf node_modules/.vite
|
||||
```
|
||||
|
||||
2. Restart the dev server:
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Issue: Tailwind classes not applying
|
||||
|
||||
**Symptoms:**
|
||||
- Styles not showing up
|
||||
- Page looks unstyled
|
||||
- Colors are wrong
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Restart the dev server** (most common fix):
|
||||
- Press `Ctrl+C` to stop
|
||||
- Run `npm run dev` again
|
||||
|
||||
2. **Check Tailwind configuration:**
|
||||
- Verify `tailwind.config.js` exists
|
||||
- Check content paths include all Vue files
|
||||
|
||||
3. **Clear cache and restart:**
|
||||
```bash
|
||||
rm -rf node_modules/.vite
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Issue: "Unknown at rule @tailwind"
|
||||
|
||||
**Solution:**
|
||||
This is usually an IDE warning and can be ignored. To fix:
|
||||
|
||||
1. **VS Code:** Install "Tailwind CSS IntelliSense" extension
|
||||
2. **Add to settings.json:**
|
||||
```json
|
||||
{
|
||||
"css.validate": false,
|
||||
"scss.validate": false
|
||||
}
|
||||
```
|
||||
|
||||
## 🔴 Installation Issues
|
||||
|
||||
### Issue: "Cannot find module 'vue'"
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
Error: Cannot find module 'vue'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
Dependencies not installed properly.
|
||||
|
||||
```bash
|
||||
# Delete node_modules and package-lock.json
|
||||
rm -rf node_modules package-lock.json
|
||||
|
||||
# Reinstall
|
||||
npm install
|
||||
```
|
||||
|
||||
### Issue: EACCES permission errors (Unix/macOS)
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
npm ERR! code EACCES
|
||||
npm ERR! syscall access
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Fix npm permissions** (recommended):
|
||||
```bash
|
||||
sudo chown -R $USER:$(id -gn $USER) ~/.npm
|
||||
sudo chown -R $USER:$(id -gn $USER) ~/.config
|
||||
```
|
||||
|
||||
2. **Or use sudo** (not recommended):
|
||||
```bash
|
||||
sudo npm install
|
||||
```
|
||||
|
||||
### Issue: "EPERM: operation not permitted" (Windows)
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Close all applications that might be using files
|
||||
2. Run Command Prompt as Administrator
|
||||
3. Try installation again
|
||||
|
||||
## 🔴 Development Server Issues
|
||||
|
||||
### Issue: Port 5173 already in use
|
||||
|
||||
**Error Message:**
|
||||
```
|
||||
Port 5173 is in use, trying another one...
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Kill the process using port 5173:**
|
||||
|
||||
**Windows:**
|
||||
```cmd
|
||||
netstat -ano | findstr :5173
|
||||
taskkill /PID <PID> /F
|
||||
```
|
||||
|
||||
**macOS/Linux:**
|
||||
```bash
|
||||
lsof -ti:5173 | xargs kill -9
|
||||
```
|
||||
|
||||
2. **Use a different port:**
|
||||
```bash
|
||||
npm run dev -- --port 5174
|
||||
```
|
||||
|
||||
### Issue: "Address already in use"
|
||||
|
||||
**Solution:**
|
||||
Another Vite server is running. Close all terminal windows running Vite and try again.
|
||||
|
||||
### Issue: Dev server starts but browser shows "Cannot GET /"
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Check you're accessing the correct URL: `http://localhost:5173`
|
||||
2. Clear browser cache (Ctrl+Shift+Delete)
|
||||
3. Try incognito/private mode
|
||||
|
||||
## 🔴 API Connection Issues
|
||||
|
||||
### Issue: "Network Error" or "Failed to fetch"
|
||||
|
||||
**Symptoms:**
|
||||
- Login doesn't work
|
||||
- API calls fail
|
||||
- Console shows network errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify backend is running:**
|
||||
```bash
|
||||
# In another terminal
|
||||
cd ../
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Backend should be running on `http://localhost:3000`
|
||||
|
||||
2. **Check proxy configuration** in `vite.config.js`:
|
||||
```javascript
|
||||
server: {
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:3000',
|
||||
changeOrigin: true,
|
||||
rewrite: (path) => path.replace(/^\/api/, ''),
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
3. **Verify backend CORS settings:**
|
||||
Backend should allow `http://localhost:5173` origin.
|
||||
|
||||
### Issue: API calls return 404
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check backend routes are correctly defined
|
||||
2. Verify API endpoint paths in frontend code
|
||||
3. Check proxy rewrite rules in `vite.config.js`
|
||||
|
||||
## 🔴 WebSocket Issues
|
||||
|
||||
### Issue: "WebSocket connection failed"
|
||||
|
||||
**Error in Console:**
|
||||
```
|
||||
WebSocket connection to 'ws://localhost:3000/ws' failed
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify backend WebSocket server is running:**
|
||||
- Check backend console for WebSocket initialization
|
||||
- Backend should show: "WebSocket server initialized"
|
||||
|
||||
2. **Check WebSocket URL:**
|
||||
- Development: `ws://localhost:3000/ws`
|
||||
- Production: `wss://yourdomain.com/ws`
|
||||
|
||||
3. **Verify proxy configuration** in `vite.config.js`:
|
||||
```javascript
|
||||
'/ws': {
|
||||
target: 'ws://localhost:3000',
|
||||
ws: true,
|
||||
}
|
||||
```
|
||||
|
||||
### Issue: WebSocket connects but immediately disconnects
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check backend WebSocket authentication
|
||||
2. Verify token is being sent correctly
|
||||
3. Check backend logs for connection errors
|
||||
|
||||
## 🔴 Authentication Issues
|
||||
|
||||
### Issue: Login redirects to error page
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify Steam API key** in backend `.env`:
|
||||
```env
|
||||
STEAM_API_KEY=your_actual_steam_api_key
|
||||
```
|
||||
|
||||
2. **Check Steam realm settings:**
|
||||
```env
|
||||
STEAM_REALM=http://localhost:3000
|
||||
STEAM_RETURN_URL=http://localhost:3000/auth/steam/return
|
||||
```
|
||||
|
||||
3. **Verify MongoDB is running:**
|
||||
```bash
|
||||
mongod --version
|
||||
# Should show version, not error
|
||||
```
|
||||
|
||||
### Issue: "Token expired" errors
|
||||
|
||||
**Solution:**
|
||||
This is normal after 15 minutes. The app should auto-refresh the token.
|
||||
|
||||
If auto-refresh fails:
|
||||
1. Clear cookies
|
||||
2. Log out and log back in
|
||||
3. Check backend JWT secrets are set
|
||||
|
||||
### Issue: User data not persisting after refresh
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Cookies might not be set correctly
|
||||
2. Check browser console for cookie errors
|
||||
3. Verify `withCredentials: true` in axios config
|
||||
4. Check backend cookie settings (httpOnly, sameSite)
|
||||
|
||||
## 🔴 Build Issues
|
||||
|
||||
### Issue: Build fails with "Out of memory"
|
||||
|
||||
**Error:**
|
||||
```
|
||||
FATAL ERROR: Reached heap limit Allocation failed
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
Increase Node.js memory:
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
set NODE_OPTIONS=--max-old-space-size=4096
|
||||
|
||||
# macOS/Linux
|
||||
export NODE_OPTIONS=--max-old-space-size=4096
|
||||
|
||||
# Then build
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Issue: Build succeeds but preview doesn't work
|
||||
|
||||
**Solution:**
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
rm -rf dist
|
||||
npm run build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
## 🔴 Component Issues
|
||||
|
||||
### Issue: Components not hot reloading
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Save the file (Ctrl+S)
|
||||
2. Check for syntax errors in console
|
||||
3. Restart dev server
|
||||
4. Check if file is in `src/` directory
|
||||
|
||||
### Issue: "v-model" not working
|
||||
|
||||
**Solution:**
|
||||
Ensure you're using Vue 3 syntax:
|
||||
|
||||
```vue
|
||||
<!-- Correct (Vue 3) -->
|
||||
<input v-model="value" />
|
||||
|
||||
<!-- Incorrect (Vue 2 - don't use) -->
|
||||
<input :value="value" @input="value = $event.target.value" />
|
||||
```
|
||||
|
||||
### Issue: Pinia store not updating
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Verify you're using the store correctly:
|
||||
```javascript
|
||||
import { useAuthStore } from '@/stores/auth'
|
||||
|
||||
const authStore = useAuthStore()
|
||||
// Use authStore.property, not authStore.value.property
|
||||
```
|
||||
|
||||
2. Ensure state is reactive:
|
||||
```javascript
|
||||
const user = ref(null) // ✅ Reactive
|
||||
const user = null // ❌ Not reactive
|
||||
```
|
||||
|
||||
## 🔴 Routing Issues
|
||||
|
||||
### Issue: 404 on page refresh
|
||||
|
||||
**Solution:**
|
||||
This is expected in development with Vite. In production, configure your server:
|
||||
|
||||
**Nginx:**
|
||||
```nginx
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
```
|
||||
|
||||
**Apache (.htaccess):**
|
||||
```apache
|
||||
RewriteEngine On
|
||||
RewriteBase /
|
||||
RewriteRule ^index\.html$ - [L]
|
||||
RewriteCond %{REQUEST_FILENAME} !-f
|
||||
RewriteCond %{REQUEST_FILENAME} !-d
|
||||
RewriteRule . /index.html [L]
|
||||
```
|
||||
|
||||
### Issue: Router links not working
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Use `<router-link>` not `<a>`:
|
||||
```vue
|
||||
<!-- Correct -->
|
||||
<router-link to="/market">Market</router-link>
|
||||
|
||||
<!-- Incorrect -->
|
||||
<a href="/market">Market</a>
|
||||
```
|
||||
|
||||
2. Use `router.push()` in script:
|
||||
```javascript
|
||||
import { useRouter } from 'vue-router'
|
||||
|
||||
const router = useRouter()
|
||||
router.push('/market')
|
||||
```
|
||||
|
||||
## 🔴 Performance Issues
|
||||
|
||||
### Issue: App is slow or laggy
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check browser DevTools Performance tab**
|
||||
2. **Reduce console.log statements** in production
|
||||
3. **Enable Vue DevTools Performance tab**
|
||||
4. **Check for memory leaks:**
|
||||
- Unsubscribe from WebSocket events
|
||||
- Remove event listeners in `onUnmounted`
|
||||
|
||||
### Issue: Initial load is slow
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify it's only slow on first load** (expected)
|
||||
2. **Check network tab** for large assets
|
||||
3. **Production build is much faster:**
|
||||
```bash
|
||||
npm run build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
## 🔴 Browser-Specific Issues
|
||||
|
||||
### Issue: Works in Chrome but not Firefox/Safari
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Check browser console for errors
|
||||
2. Verify browser version (Firefox 88+, Safari 14+)
|
||||
3. Check for browser-specific CSS issues
|
||||
4. Test in private/incognito mode
|
||||
|
||||
### Issue: Styles different in Safari
|
||||
|
||||
**Solution:**
|
||||
Safari has different default styles. This is expected. Most major issues are already handled.
|
||||
|
||||
## 🔴 IDE Issues
|
||||
|
||||
### Issue: VS Code not recognizing Vue files
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Install **Volar** extension (NOT Vetur for Vue 3)
|
||||
2. Disable Vetur if installed
|
||||
3. Restart VS Code
|
||||
|
||||
### Issue: ESLint errors everywhere
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. Restart VS Code
|
||||
|
||||
3. Check `.eslintrc.cjs` exists
|
||||
|
||||
## 🚨 Emergency Fixes
|
||||
|
||||
### Nuclear Option: Complete Reset
|
||||
|
||||
If nothing else works:
|
||||
|
||||
```bash
|
||||
# 1. Stop all servers (Ctrl+C)
|
||||
|
||||
# 2. Delete everything
|
||||
rm -rf node_modules
|
||||
rm -rf dist
|
||||
rm -rf .vite
|
||||
rm package-lock.json
|
||||
|
||||
# 3. Clean npm cache
|
||||
npm cache clean --force
|
||||
|
||||
# 4. Reinstall
|
||||
npm install
|
||||
|
||||
# 5. Start fresh
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Check System Requirements
|
||||
|
||||
```bash
|
||||
# Check Node version (should be 18+)
|
||||
node -v
|
||||
|
||||
# Check npm version (should be 9+)
|
||||
npm -v
|
||||
|
||||
# Check available disk space
|
||||
# Windows: dir
|
||||
# macOS/Linux: df -h
|
||||
|
||||
# Check available memory
|
||||
# Windows: systeminfo
|
||||
# macOS/Linux: free -h
|
||||
```
|
||||
|
||||
## 📞 Getting Help
|
||||
|
||||
If none of these solutions work:
|
||||
|
||||
1. **Check the documentation:**
|
||||
- `README.md` - Full documentation
|
||||
- `QUICKSTART.md` - Quick start guide
|
||||
- `INSTALLATION.md` - Installation guide
|
||||
|
||||
2. **Search for similar issues:**
|
||||
- GitHub Issues
|
||||
- Stack Overflow
|
||||
- Vue.js Discord
|
||||
|
||||
3. **Create a bug report with:**
|
||||
- Operating system
|
||||
- Node.js version
|
||||
- Complete error message
|
||||
- Steps to reproduce
|
||||
- What you've already tried
|
||||
|
||||
4. **Contact support:**
|
||||
- GitHub Issues: Create new issue
|
||||
- Email: support@turbotrades.com
|
||||
- Discord: [Your Discord link]
|
||||
|
||||
## 📝 Preventive Measures
|
||||
|
||||
To avoid issues:
|
||||
|
||||
1. ✅ Use Node.js 18 or higher
|
||||
2. ✅ Keep dependencies updated
|
||||
3. ✅ Clear cache regularly
|
||||
4. ✅ Use version control (Git)
|
||||
5. ✅ Test in multiple browsers
|
||||
6. ✅ Keep backend and frontend versions in sync
|
||||
7. ✅ Read error messages carefully
|
||||
8. ✅ Check backend logs when API fails
|
||||
|
||||
## 🎯 Quick Diagnosis
|
||||
|
||||
**If you see errors:**
|
||||
1. Read the error message completely
|
||||
2. Check which file/line number
|
||||
3. Look for typos first
|
||||
4. Search this guide for the error
|
||||
5. Check browser console
|
||||
6. Check backend logs
|
||||
7. Restart dev server
|
||||
|
||||
**If something doesn't work:**
|
||||
1. Does it work in the same browser after refresh?
|
||||
2. Does it work in another browser?
|
||||
3. Does it work after restarting the dev server?
|
||||
4. Is the backend running?
|
||||
5. Are there errors in console?
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** January 2025
|
||||
**Version:** 1.0.0
|
||||
|
||||
Remember: Most issues are solved by restarting the dev server! 🔄
|
||||
Reference in New Issue
Block a user