3dc8592b83
- Added multi-platform deployment architecture details (Web App, PWA, DApp) to README.md. - Included comprehensive troubleshooting guides and fix scripts in README.md. - Enhanced CHANGELOG.md with new features, fixes, and improvements, including TypeScript error resolutions and updated documentation structure. - Revised development setup instructions in DEV_SETUP.md to reflect changes in script usage and environment variable setup.
108 lines
2.4 KiB
Markdown
108 lines
2.4 KiB
Markdown
# Frontend Troubleshooting Guide
|
|
|
|
## Issue: No Content Appearing
|
|
|
|
### Possible Causes
|
|
|
|
1. **Next.js Compilation Issue**
|
|
- Next.js may still be compiling
|
|
- Check for compilation errors in the terminal
|
|
- Wait for "Ready" message in dev server
|
|
|
|
2. **Missing Dependencies**
|
|
- React Query, Wagmi, or other dependencies may not be loaded
|
|
- Check browser console for errors
|
|
|
|
3. **Provider Issues**
|
|
- Providers (QueryClient, Wagmi, Session) may be failing silently
|
|
- Check browser console for React errors
|
|
|
|
4. **CSS Not Loading**
|
|
- Tailwind CSS may not be compiled
|
|
- Check if `globals.css` is imported correctly
|
|
|
|
### Solutions
|
|
|
|
#### 1. Check Dev Server Status
|
|
```powershell
|
|
# Check if Next.js is running
|
|
Get-NetTCPConnection -LocalPort 3000 -State Listen
|
|
|
|
# Check process
|
|
Get-Process node | Where-Object { $_.Id -eq (Get-NetTCPConnection -LocalPort 3000).OwningProcess }
|
|
```
|
|
|
|
#### 2. Restart Dev Server
|
|
```powershell
|
|
cd webapp
|
|
# Stop current server (Ctrl+C)
|
|
npm run dev
|
|
```
|
|
|
|
#### 3. Clear Next.js Cache
|
|
```powershell
|
|
cd webapp
|
|
Remove-Item -Recurse -Force .next -ErrorAction SilentlyContinue
|
|
npm run dev
|
|
```
|
|
|
|
#### 4. Check Browser Console
|
|
- Open browser DevTools (F12)
|
|
- Check Console tab for errors
|
|
- Check Network tab for failed requests
|
|
|
|
#### 5. Verify Environment Variables
|
|
```powershell
|
|
# Check if .env.local exists
|
|
Test-Path webapp/.env.local
|
|
|
|
# Create minimal .env.local if missing
|
|
@"
|
|
NEXT_PUBLIC_ORCH_URL=http://localhost:8080
|
|
NEXTAUTH_SECRET=dev-secret-change-in-production
|
|
"@ | Out-File -FilePath webapp/.env.local
|
|
```
|
|
|
|
#### 6. Check for TypeScript Errors
|
|
```powershell
|
|
cd webapp
|
|
npm run build
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Fixes
|
|
|
|
### Fix 1: Ensure Providers Load
|
|
The `providers.tsx` file should wrap the app. Check that it's imported in `layout.tsx`.
|
|
|
|
### Fix 2: Add Error Boundary
|
|
The ErrorBoundary component should catch and display errors. Check browser console.
|
|
|
|
### Fix 3: Verify API Endpoints
|
|
Check that the orchestrator is running and accessible:
|
|
```powershell
|
|
Invoke-WebRequest -Uri "http://localhost:8080/health" -UseBasicParsing
|
|
```
|
|
|
|
---
|
|
|
|
## Common Issues
|
|
|
|
### Issue: Blank Page
|
|
**Cause**: React hydration error or provider failure
|
|
**Fix**: Check browser console, verify all providers are configured
|
|
|
|
### Issue: Timeout
|
|
**Cause**: Next.js still compiling or stuck
|
|
**Fix**: Restart dev server, clear .next cache
|
|
|
|
### Issue: Styling Missing
|
|
**Cause**: Tailwind CSS not compiled
|
|
**Fix**: Check `globals.css` import, verify Tailwind config
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-15
|
|
|