docs: update troubleshooting documentation
Update troubleshooting guide with latest fixes and solutions for common development issues encountered during CMS implementation and shop frontend development. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -13,6 +13,7 @@ Common PyCharm issues and their solutions for the development team.
|
||||
- [Performance Issues](#performance-issues)
|
||||
- [Git Integration Issues](#git-integration-issues)
|
||||
- [Database Tool Issues](#database-tool-issues)
|
||||
- [Frontend Asset Loading Issues](#frontend-asset-loading-issues)
|
||||
|
||||
---
|
||||
|
||||
@@ -342,6 +343,145 @@ DATABASE_URL=postgresql://user:password@localhost:5432/letzshop_db
|
||||
|
||||
---
|
||||
|
||||
## Frontend Asset Loading Issues
|
||||
|
||||
### Problem
|
||||
|
||||
- Tailwind CSS styles not loading
|
||||
- Alpine.js not initializing
|
||||
- Frontend pages look unstyled
|
||||
- Console errors about missing CSS/JS files
|
||||
- App doesn't work offline
|
||||
|
||||
### Solution 1: Verify CDN Fallback Files Exist
|
||||
|
||||
All frontends use CDN with local fallback. Check that local copies exist:
|
||||
|
||||
```bash
|
||||
# From project root
|
||||
ls -lh static/shared/css/tailwind.min.css
|
||||
ls -lh static/shared/js/vendor/alpine.min.js
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
-rw-r--r-- 1 user user 2.9M static/shared/css/tailwind.min.css
|
||||
-rw-r--r-- 1 user user 44K static/shared/js/vendor/alpine.min.js
|
||||
```
|
||||
|
||||
**If files are missing:**
|
||||
```bash
|
||||
# Download Tailwind CSS
|
||||
cd static/shared/css
|
||||
curl -o tailwind.min.css https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css
|
||||
|
||||
# Download Alpine.js
|
||||
cd ../js/vendor
|
||||
curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js
|
||||
```
|
||||
|
||||
### Solution 2: Check Browser Console
|
||||
|
||||
Open DevTools (F12) and check the Console tab for errors:
|
||||
|
||||
**Common errors:**
|
||||
- `GET http://localhost:8000/static/shared/css/tailwind.min.css [404 Not Found]` → File missing
|
||||
- `Alpine.js CDN failed, loading local copy...` → Normal fallback behavior
|
||||
- `Uncaught ReferenceError: Alpine is not defined` → Alpine.js failed to load
|
||||
|
||||
### Solution 3: Test CDN Fallback Behavior
|
||||
|
||||
To verify fallback works correctly:
|
||||
|
||||
1. **Start application:**
|
||||
```bash
|
||||
uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
2. **Test with CDN blocked:**
|
||||
- Open browser DevTools (F12)
|
||||
- Go to Network tab
|
||||
- Add request blocking rule for `cdn.jsdelivr.net`
|
||||
- Reload page
|
||||
|
||||
3. **Verify fallback:**
|
||||
- Check Console for: `⚠️ Alpine.js CDN failed, loading local copy...`
|
||||
- Check Network tab shows local files loaded
|
||||
- Page should still work normally
|
||||
|
||||
### Solution 4: Verify Static Files Mounting
|
||||
|
||||
Check that FastAPI is serving static files correctly:
|
||||
|
||||
**In `app/main.py`:**
|
||||
```python
|
||||
from fastapi.staticfiles import StaticFiles
|
||||
|
||||
app.mount("/static", StaticFiles(directory="static"), name="static")
|
||||
```
|
||||
|
||||
**Test static file serving:**
|
||||
```bash
|
||||
# With app running, test directly:
|
||||
curl http://localhost:8000/static/shared/css/tailwind.min.css | head -n 5
|
||||
curl http://localhost:8000/static/shared/js/vendor/alpine.min.js | head -n 5
|
||||
```
|
||||
|
||||
### Solution 5: File Permissions
|
||||
|
||||
If files exist but return 403 Forbidden:
|
||||
|
||||
```bash
|
||||
# Fix permissions
|
||||
chmod 644 static/shared/css/tailwind.min.css
|
||||
chmod 644 static/shared/js/vendor/alpine.min.js
|
||||
chmod 755 static/shared/css
|
||||
chmod 755 static/shared/js/vendor
|
||||
```
|
||||
|
||||
### Solution 6: For Offline Development
|
||||
|
||||
If working completely offline, the CDN will always fail. Verify:
|
||||
|
||||
1. **Console shows fallback message** (expected behavior)
|
||||
2. **Local files load successfully**
|
||||
3. **Page functions normally**
|
||||
|
||||
**To suppress CDN warnings when offline:**
|
||||
- Accept that CDN will fail (expected)
|
||||
- Fallback mechanism handles it automatically
|
||||
- Or modify templates to use local-only (see [CDN Fallback Strategy](../frontend/cdn-fallback-strategy.md#optimization-strategies))
|
||||
|
||||
### Solution 7: Network Issues
|
||||
|
||||
If both CDN and local files fail intermittently:
|
||||
|
||||
1. **Check browser cache:**
|
||||
- Open DevTools → Network tab
|
||||
- Check "Disable cache" option
|
||||
- Hard reload: Ctrl+Shift+R
|
||||
|
||||
2. **Clear browser cache completely:**
|
||||
- Browser Settings → Privacy → Clear browsing data
|
||||
- Select "Cached images and files"
|
||||
- Clear data
|
||||
|
||||
3. **Check for firewall/proxy issues:**
|
||||
```bash
|
||||
# Test CDN accessibility
|
||||
curl https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css | head -n 5
|
||||
```
|
||||
|
||||
### Related Documentation
|
||||
|
||||
See [CDN Fallback Strategy](../frontend/cdn-fallback-strategy.md) for complete details on:
|
||||
- How the fallback mechanism works
|
||||
- Updating local asset files
|
||||
- Production deployment considerations
|
||||
- Air-gapped deployment setup
|
||||
|
||||
---
|
||||
|
||||
## Quick Checklist for New Developers
|
||||
|
||||
When setting up PyCharm for the first time:
|
||||
|
||||
Reference in New Issue
Block a user