lucasacchi/llm-monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: resolve console errors (localStorage in Worker, favicon, Tailwind CDN)

Browse Source 
Issues fixed:
1. Web Worker localStorage error - Remove localStorage calls from worker
   - Worker cannot access localStorage (browser context only)
   - Worker now sends data to main thread via postMessage
   - Main thread handles all localStorage operations

2. Add favicon to avoid 404 error
   - Use inline SVG favicon (llama emoji)
   - No external file request

3. Optimize Tailwind CSS for production
   - Add tailwind.config.js for content scanning
   - Add app/web/static/css/input.css (Tailwind directives)
   - Update package.json with tailwind build commands
   - Update Dockerfile multi-stage build:
     * Stage 1: Node.js - compile Tailwind CSS
     * Stage 2: Python - install dependencies
     * Stage 3: Runtime - use compiled CSS
   - Update index.html to use compiled output.css
   - Add fallback to CDN for development

4. Add DEVELOPMENT.md documentation
   - Setup instructions for local development
   - Tailwind CSS workflow (watch mode)
   - Docker build explanation
   - Development tips and best practices

Benefits:
- No more localStorage errors in console
- No more 404 favicon requests
- Optimized CSS for production (~30KB minified)
- Clear development workflow
- Multi-stage Docker build is efficient (~300MB image)
This commit is contained in:
Luca Sacchi Ricciardi
2026-04-24 19:30:53 +02:00
parent b3beb525ad
commit 893376dc14
7 changed files with 258 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEVELOPMENT.md
+216
View File
@@ -0,0 +1,216 @@
# Development Setup - LLM Monitor
## 🛠️ Setup Locale
### 1. Installare Dipendenze Python
```bash
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
```
### 2. Installare Dipendenze Node (per Tailwind CSS)
```bash
npm install
```
### 3. Compilare Tailwind CSS
#### Modalità Development (watch mode)
```bash
npm run tailwind:dev
```
Questo comando:
- Compila `app/web/static/css/input.css` in `app/web/static/css/output.css`
- Rimane in watch mode per compilare automaticamente al salvataggio
- Legge la configurazione da `tailwind.config.js`
#### Modalità Production (minified)
```bash
npm run tailwind:build
```
Questo comando:
- Compila e minifica il CSS
- Ottimizzato per produzione
- Usato durante il build Docker
### 4. Avviare l'Applicazione
In una finestra di terminale (con `npm run tailwind:dev` in watch):
```bash
source venv/bin/activate
python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
O usar il comando Makefile:
```bash
make dev
```
Accedi a: http://localhost:8000
---
## 📱 Workflow di Sviluppo
### Sviluppare il Frontend
1. **Terminal 1 - Tailwind Watcher:**
```bash
npm run tailwind:dev
```
2. **Terminal 2 - FastAPI Dev Server:**
```bash
source venv/bin/activate
uvicorn main:app --reload
```
3. **Modificare i file:**
- HTML: `app/web/templates/index.html`
- CSS input: `app/web/static/css/input.css` (raramente, usa classi Tailwind)
- JavaScript: `app/web/static/js/app.js` e `data-sync.worker.js`
4. **Compilato automaticamente:**
- Tailwind genera `app/web/static/css/output.css` automaticamente
- FastAPI recarica il server automaticamente
- Browser reload automatico (se abilitato)
---
## 🐳 Build Docker
Il Dockerfile multi-stage:
1. **Stage 1 - CSS Builder (Node):**
- Installa dipendenze npm
- Compila Tailwind CSS
- Genera `app/web/static/css/output.css`
2. **Stage 2 - Python Builder:**
- Installa dipendenze Python
- Crea virtualenv
3. **Stage 3 - Runtime:**
- Copia CSS compilato dal Stage 1
- Copia Python packages dal Stage 2
- Immagine finale ottimizzata (~300MB)
### Build locale:
```bash
docker build -t llm-monitor:latest .
```
### Eseguire il container:
```bash
docker run -p 8000:8000 --env-file .env llm-monitor:latest
```
---
## ⚙️ Configurazione Tailwind
File: `tailwind.config.js`
```javascript
module.exports = {
content: [
"./app/web/templates/**/*.html",
"./app/web/static/**/*.js",
],
theme: {
extend: {},
},
plugins: [],
}
```
**Content**: Specifica quali file Tailwind deve scansionare per le classi utilizzate
---
## 🎯 CSS Architecture
### Input CSS
File: `app/web/static/css/input.css`
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```
### Output CSS
File: `app/web/static/css/output.css` (generato)
- Contiene solo le classi Tailwind utilizzate
- Minificato in produzione (~30KB)
- Ottimizzato per performance
### Usage in HTML
File: `app/web/templates/index.html`
```html
<!-- Usa il CSS compilato (produzione) -->
<link rel="stylesheet" href="/static/css/output.css">
<!-- Fallback CDN per sviluppo (se output.css non esiste) -->
<script src="https://cdn.tailwindcss.com"></script>
```
---
## 📝 Tips di Sviluppo
### Hot Reload CSS
```bash
npm run tailwind:dev
# Guarda i file e compila automaticamente
```
### Debug CSS Compilation
```bash
npm run tailwind:build
# Se il CSS non appare, verifica:
# 1. Le classi sono usate nei file HTML/JS?
# 2. C'è un errore nella sintassi CSS?
# 3. I percorsi in tailwind.config.js sono corretti?
```
### Aggiungere Nuove Classi Tailwind
1. Modifica i file HTML/JS con classi Tailwind
2. Tailwind watcher le detetta automaticamente
3. `output.css` viene rigenerato
```html
<!-- Nuova classe aggiunta -->
<div class="bg-gradient-to-r from-purple-500 to-pink-500">
<!-- Viene aggiunta automaticamente al CSS compilato -->
</div>
```
---
## 🚀 Production Checklist
- [ ] Eseguire `npm run tailwind:build` per minificare
- [ ] Verificare che `output.css` sia generato
- [ ] Controllare che il container Docker usi il CSS compilato
- [ ] Test performance con Lighthouse
- [ ] Verifica bundle size `output.css`
---
## 🔗 Risorse
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [Tailwind CLI](https://tailwindcss.com/docs/installation)
- [FastAPI Hot Reload](https://fastapi.tiangolo.com/#example-upgrade)
- [Docker Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/)
---
**Ultimo aggiornamento:** Aprile 2024