chore: scaffold progetto Astro 5 con adapter node

2026-07-01 23:35:56 +02:00
parent 9780e51137
commit 5f7ed1f97b
12 changed files with 6132 additions and 0 deletions
@@ -0,0 +1,137 @@
+# InsanityLab Website
+
+Sito vetrina per InsanityLab con blog integrato e form di contatti.
+
+## Descrizione
+
+Il progetto realizza un sito web per InsanityLab, combinando una vetrina aziendale con un sistema di blog gestito tramite SQLite e un form di contatti funzionante. L'architettura è costruita su **Astro 5** con adapter **Node.js** per deployment su server, garantendo performance ottimali e SEO-friendly pages.
+
+## Stack Tecnologico
+
+- **Framework**: Astro 5
+- **Runtime**: Node.js (adapter standalone)
+- **Database**: SQLite (better-sqlite3)
+- **Autenticazione**: bcryptjs
+- **Email**: Nodemailer
+- **Markup Editor**: TipTap (rich text)
+- **Font System**: @fontsource (Montserrat, Open Sans)
+- **Sitemap**: @astrojs/sitemap
+- **Testing**: Vitest
+- **Linguaggio**: TypeScript
+
+## Installazione
+
+### Prerequisiti
+
+- Node.js 18+ e npm
+
+### Setup
+
+```bash
+# Installa dipendenze
+npm install
+
+# Copia il template di configurazione env
+cp .env.example .env
+
+# Crea il primo utente amministratore (dopo aver configurato il DB)
+npm run create-user -- admin tuapassword
+```
+
+Modifica `.env` con le credenziali SMTP, percorsi database e upload directory secondo il tuo ambiente.
+
+## Comandi Disponibili
+
+| Comando | Descrizione |
+|---------|-------------|
+| `npm run dev` | Avvia il server di sviluppo (localhost:3000) |
+| `npm run build` | Compila il progetto per production |
+| `npm run preview` | Visualizza l'anteprima della build (locale) |
+| `npm run start` | Avvia il server production (richiede `npm run build` preliminare) |
+| `npm run test` | Esegui i test con Vitest |
+| `npm run create-user` | Crea un nuovo utente (admin o redattore) |
+
+## Struttura Progetto
+
+```
+insanitylab-website/
+├── src/
+│   ├── pages/               # Pagine Astro (routing automatico)
+│   ├── components/          # Componenti Astro riutilizzabili
+│   ├── layouts/             # Layout master
+│   ├── utils/               # Funzioni di utilità
+│   ├── env.d.ts            # Type definitions globali
+│   └── ...
+├── data/                    # Database SQLite e dati persistenti
+│   └── insanitylab.db      # (generato al primo avvio)
+├── uploads/                 # Directory per upload immagini e file
+├── dist/                    # Output build (server)
+├── tests/                   # Test suite
+├── astro.config.mjs        # Configurazione Astro
+├── tsconfig.json           # Configurazione TypeScript
+├── vitest.config.ts        # Configurazione test framework
+├── .env.example            # Template variabili di ambiente
+├── .env                    # Variabili di ambiente (non versionato)
+├── package.json            # Dipendenze e script npm
+└── README.md               # Questo file
+```
+
+## Configurazione Ambiente
+
+Il file `.env` richiede le seguenti variabili:
+
+- `SMTP_HOST`: Host SMTP per invio email
+- `SMTP_PORT`: Porta SMTP (solitamente 587)
+- `SMTP_USER`: Utente SMTP
+- `SMTP_PASS`: Password SMTP
+- `CONTACT_TO`: Email di destinazione contatti
+- `CONTACT_FROM`: Email mittente
+- `DB_PATH`: Percorso database SQLite
+- `UPLOADS_DIR`: Cartella upload file
+
+## Development Workflow
+
+1. **Avvia il server locale**: `npm run dev`
+2. **Modifica file** in `src/` (hot reload automatico)
+3. **Test**: `npm run test`
+4. **Build**: `npm run build` (verifica errori di build)
+5. **Commit**: Con prefisso `feat:` (feature) o `chore:` (manutenzione)
+
+## Deployment
+
+```bash
+# Build per production
+npm run build
+
+# Opzionalmente, preview locale
+npm run preview
+
+# In production, il server parte con:
+npm run start
+
+# Variabili ambiente in production vanno impostate sull'hosting
+# (es. Hostinger VPS, Vercel, etc.)
+```
+
+## Riferimenti Tecnici
+
+Per dettagli su architettura, schema database, componenti e specifiche vedi:
+- `/docs/superpowers/specs/2026-07-01-insanitylab-website-design.md`
+- `/docs/superpowers/plans/2026-07-01-insanitylab-website.md`
+
+## Problemi Comuni
+
+### `better-sqlite3` fallisce su npm install
+
+Se `better-sqlite3` non compila, assicurati di avere build tools installati:
+- **Linux**: `sudo apt-get install build-essential python3`
+- **macOS**: Xcode Command Line Tools (`xcode-select --install`)
+- **Windows**: Visual Studio Build Tools o MinGW
+
+### Database locked
+
+Se il database è locato durante i test, verifica che non ci siano processi in background che accedono a `data/insanitylab.db`.
+
+## Licenza
+
+Proprietario InsanityLab.