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 7 con adapter Node.js per deployment su server, garantendo performance ottimali e SEO-friendly pages.

Stack Tecnologico

• Framework: Astro 7
• 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: endpoint runtime /sitemap.xml (route vetrina, programmi e articoli pubblicati)
• Testing: Vitest
• Linguaggio: TypeScript

Installazione

Prerequisiti

• Node.js 18+ e npm

Setup

# 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:4321)
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: -- <nome> <password> [admin|editor]

Gestione Contenuti

I testi e le immagini del sito vetrina sono contenuti taggati, modificabili senza toccare il codice tramite il pannello /admin/content. Ogni blocco di contenuto è identificato da un tag (ad esempio home.hero.title) e può essere aggiornato nel valore, negli stili predefiniti (dimensione, peso, colore) e — per le immagini — sostituito con un upload o riportato all'originale.

Il pannello raggruppa i tag per pagina, offre una ricerca per tag o contenuto e mostra per ogni blocco l'ultima modifica effettuata. Visitando il sito da utente autenticato con il parametro ?annotate=1 (link "Vedi sito con tag" nel pannello), ogni contenuto taggato viene evidenziato con un badge che rimanda direttamente al form di modifica corrispondente.

Sono previsti due ruoli utente: admin ha accesso completo (articoli del blog, contenuti, upload), mentre editor può operare esclusivamente sul pannello contenuti. Gli utenti si creano con npm run create-user -- <nome> <password> editor.

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

# 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.