Questa pagina contiene tutte le regole che il tuo assistente AI deve conoscere per preparare il progetto per Ai to App. Non devi leggerla: basta dare al tuo assistente il messaggio qui sotto.

Leggi la guida all'indirizzo https://aitoapp.com/it/upload-guide. Prepara il mio progetto per Ai to App seguendo questa guida, applica la checklist punto per punto e crea il file zip.

Ai to App esamina e pubblica siti e applicazioni caricati come file zip. I file caricati non vengono eseguiti durante l'esame. Le applicazioni server, una volta pubblicate, girano in un proprio ambiente isolato, separato dagli altri progetti. Questa guida contiene tutte le regole necessarie perché il progetto passi senza problemi al primo caricamento.

1. Stabilisci il tipo di progetto

Ai to App riconosce il tipo da solo, in base ai file presenti nello zip. Se corrispondono più tipi, vale l'ordine qui sotto; vince quello più in alto.

Importante:

• Nei siti compilati (React, Vue, Vite, Angular, Svelte, Astro) esegui prima npm run build. Comprimi in zip i file ALL'INTERNO della cartella dist (o build) che viene creata. Nella radice dello zip deve esserci direttamente index.html.
• I progetti Go vengono pubblicati solo con un Dockerfile.
• docker-compose non è supportato; viene eseguita solo l'applicazione principale (Dockerfile). Il database lo fornisce Ai to App a parte (vedi Sezione 4).

2. Regole per lo zip

Limiti

Struttura delle cartelle

• I file del progetto devono trovarsi nella radice dello zip oppure dentro un'unica cartella superiore.
• In un sito statico, index.html deve trovarsi nella radice dello zip oppure dentro l'unica cartella superiore.
• Non sono accettati due file con lo stesso percorso né percorsi non sicuri che contengono ../.

NON mettere nello zip (vengono scartati automaticamente, occupano spazio inutilmente)

• Dipendenze: node_modules, .venv, venv, __pycache__, bower_components, .pytest_cache, .mypy_cache
• Cartelle di strumenti e controllo versione: .git, .svn, .hg, .idea, .vscode, .vs, .cache, .turbo, .parcel-cache, .gradle
• Output di compilazione: .next, .nuxt, .svelte-kit. In .NET anche bin e obj.
• File di sistema: __MACOSX, .DS_Store, Thumbs.db, desktop.ini, *.pyc

MAI mettere nello zip (vengono scartati e non vengono conservati)

• File .env: come .env, .env.local, .env.production. I file di esempio possono restare: .env.example, .env.sample, .env.template. Se nello zip c'è un .env, il file non viene conservato; alla build passano solo i valori pubblici con i prefissi VITE_, NEXT_PUBLIC_, PUBLIC_, REACT_APP_. Inserisci i valori segreti nel pannello.
• File di chiavi e credenziali: *.pem, *.key, *.p12, *.pfx, *.ppk, *.jks, *.keystore, id_rsa, id_ed25519, .npmrc, .pypirc, .netrc. Se uno di questi è già stato condiviso, rigenera la chiave.

File che bloccano il caricamento

• Nel sorgente dell'applicazione: script e file di installazione di Windows (.bat, .cmd, .ps1, .vbs, .scr, .msi). I file di programma compilati (.exe, .dll, .so e simili) vengono scartati; il server compila il progetto dal sorgente.
• Nel sito statico:
  • Codice server ed eseguibili sono vietati: .php, .py, .rb, .pl, .cgi, .asp, .aspx, .cshtml, .jsp, .exe, .dll, .sh, .jar, .htaccess, .config.
  • Tipi consentiti: .html, .htm, .css, .js, .mjs, .json, .webmanifest, .txt, .xml, .csv, .svg, .png, .jpg, .jpeg, .gif, .webp, .avif, .ico, .bmp, .woff, .woff2, .ttf, .otf, .eot, .mp4, .webm, .mp3, .ogg, .wav, .pdf.
  • I file .map e .md vengono ignorati.

3. Impostazioni obbligatorie per le applicazioni server

Porta e indirizzo

Ai to App fornisce la porta su cui l'applicazione deve restare in ascolto tramite la variabile d'ambiente PORT. L'applicazione deve collegarsi all'indirizzo 0.0.0.0; localhost o 127.0.0.1 non sono raggiungibili dall'esterno.

Comando di avvio

• Node.js:
  • Lo script start in package.json deve avviare il server di produzione, ad es. "start": "node server.js".
  • I comandi di sviluppo NON devono stare in start: vite, next dev, nodemon, ts-node-dev, tsx watch, webpack serve, react-scripts start, npm run dev. Lasciali nello script dev.
  • TypeScript: aggiungi "build": "tsc" e imposta "start": "node dist/index.js". Compilare TypeScript durante l'esecuzione è lento.
  • Aggiungi allo zip il file di lock (package-lock.json, pnpm-lock.yaml, yarn.lock oppure bun.lockb).
  • Indica la versione di Node con package.json → engines.node oppure con .nvmrc.
• Python:
  • FastAPI, Flask, Django, Streamlit e Gradio vengono riconosciuti automaticamente.
  • Se usi un'altra struttura, crea nella radice un Procfile: web: <comando di avvio>. Il comando deve usare 0.0.0.0 e $PORT.
  • Flask: gunicorn deve essere in requirements.txt.
  • Django: ALLOWED_HOSTS non deve essere vuoto, DEBUG = False e SECRET_KEY deve essere letta da una variabile d'ambiente.
  • Indica la versione di Python con runtime.txt oppure .python-version.
• .NET: Nella radice deve esserci un .csproj. Ai to App compila con dotnet publish -c Release; la versione di destinazione viene letta da TargetFramework nel .csproj.
• Dockerfile: Indica la porta dell'applicazione con EXPOSE. L'applicazione deve comunque leggere la variabile PORT.

4. Database

Ai to App configura il database da sé e fornisce i dati di connessione tramite una variabile d'ambiente. Non scrivere l'indirizzo di connessione nel codice; leggilo dalla variabile qui sotto.

• Prisma: aggiungi allo zip la cartella prisma/migrations; altrimenti le tabelle potrebbero non essere create automaticamente.
• Alembic: se è presente alembic.ini, prima della pubblicazione viene eseguito automaticamente alembic upgrade head.
• File SQLite: il file SQLite presente nello zip viene usato come dati iniziali solo alla prima pubblicazione; i caricamenti successivi non sovrascrivono i dati live. Non mettere nello zip un database di prova che contiene dati personali.
• Aggiornamenti: quando carichi una nuova versione, i dati nel database vengono conservati.

5. File persistenti

Il disco dell'ambiente in cui gira l'applicazione non è persistente; viene cancellato a ogni nuova pubblicazione. L'unica cartella persistente è /data.

• Salva sotto /data le foto e i documenti caricati dai visitatori, i file generati e il database SQLite.
• Leggi il percorso della cartella dalla variabile d'ambiente DATA_DIR; Ai to App la imposta per te su /data.

6. Informazioni riservate e variabili d'ambiente

• Non scrivere password, chiavi API e token nel codice; leggili da variabili d'ambiente. Inserisci i valori nel pannello di Ai to App; vengono conservati in forma cifrata.
• Prefissi pubblici: le variabili con prefisso VITE_, NEXT_PUBLIC_, REACT_APP_ e PUBLIC_ vengono incorporate nel codice durante la build e ogni visitatore può vederle. Non inserirvi valori riservati.
• Sistema di accesso (NextAuth / Auth.js): NEXTAUTH_URL (oppure AUTH_URL) deve essere l'indirizzo reale del sito e NEXTAUTH_SECRET (oppure AUTH_SECRET) deve essere valorizzato.
• OAuth (Google, GitHub): aggiungi l'indirizzo di pubblicazione nelle impostazioni del provider come URI di reindirizzamento autorizzato.
• Accesso con Supabase: in Supabase, in Authentication > URL Configuration, inserisci il tuo indirizzo pubblicato in Site URL e aggiungi l'indirizzo esatto in Redirect URLs (https://your-app.aitoapp.com/). Altrimenti i link nelle email di conferma e di accesso portano a localhost:3000 e l'accesso non si completa. Per l'accesso con Google, in Google Cloud aggiungi il tuo indirizzo pubblicato a Authorized JavaScript origins e https://PROJECT.supabase.co/auth/v1/callback a Authorized redirect URIs.
• Variabili che fornisce Ai to App stesso: PORT, HOST=0.0.0.0, DATA_DIR=/data e le variabili del database (Sezione 4). In Node.js NODE_ENV=production.

7. Cosa non deve esserci nel codice

• Indirizzi localhost: il codice che invia richieste a http://localhost:... o http://127.0.0.1:... una volta pubblicato raggiunge il computer del visitatore e non funziona. Leggi l'indirizzo da una variabile d'ambiente (ad es. import.meta.env.VITE_API_URL) oppure, se è sullo stesso server, usa un percorso relativo (fetch('/api/...')).
• Richieste /api/... in un sito statico: dietro un sito statico non c'è un server. Se serve un'API, prepara il progetto come un'unica applicazione server (ad es. Express) che esegue anche l'API.
• Porta fissa: const PORT = 3000 non deve stare da solo; usa process.env.PORT || 3000.
• Modalità di debug: debug=True o DEBUG = True non devono essere attivi in produzione.
• Segreti scritti nel codice: una chiave trovata si considera condivisa; rigenerala.

8. Checklist per l'assistente

• Il tipo di progetto è stato stabilito (Sezione 1).
• Se è un sito compilato, è stata eseguita la build ed è stato compresso solo il contenuto della cartella dist / build / out; index.html è nella radice.
• Se è un'applicazione server, lo script start (o il Procfile) avvia il server di produzione.
• La porta viene letta dalla variabile d'ambiente PORT; il server si collega a 0.0.0.0.
• Nel codice non è rimasto nessun indirizzo localhost / 127.0.0.1.
• Password e chiavi sono state tolte dal codice; vengono lette da variabili d'ambiente.
• La connessione al database viene letta da DATABASE_URL / MONGODB_URI / REDIS_URL / DATABASE_PATH.
• I file persistenti vengono scritti sotto /data.
• Il file di lock è presente (package-lock.json ecc.).
• node_modules, .git, .venv, .next, bin, obj, .env e i file di chiavi NON sono nello zip.
• Lo zip è sotto i 50 MB, ogni singolo file sotto i 25 MB; al massimo 2000 file.

9. Alla fine del lavoro, dimmi questo

1. Il percorso esatto del file zip preparato.
2. Il tipo di progetto e il linguaggio o framework usato (ad es. "Node.js + Express").
3. L'elenco delle variabili d'ambiente che devo inserire nel pannello: il nome di ciascuna e a cosa serve. Non scrivere i valori; li inserirò io.
4. Un breve riepilogo delle modifiche che hai fatto.

Se dopo il caricamento dello zip c’è un problema, Ai to App lo spiega in modo semplice: incolla quel testo al tuo assistente.