2. Progetti

2.1 Creare un progetto

Le tre strade: una cartella vuota, un repository Git, o una base di framework o CMS con le sue aggiunte. Più i tuoi repository GitHub.

Nell'app: «Nuovo progetto»

In breve

Un progetto è semplicemente una cartella dentro projects: il kit la riconosce da sola.
Per crearne uno ci sono tre strade: «Progetto vuoto», «Da un indirizzo Git» e «Da una base», con le basi di framework e CMS in quattro gruppi: Web, CMS, App e Altro. Più l'elenco dei tuoi repository GitHub.
Un tuo progetto può diventare una base: «Salva come base» nella sua pagina, e la ritrovi per prima sotto «Le mie basi».
Con un framework, il kit installa gli strumenti che servono ed esegue i comandi ufficiali del framework.
Puoi anche copiare a mano una cartella in projects: compare nell'elenco dopo «Aggiorna».

**La procedura «Da una base»**dati di esempio

Dove si crea un progetto

Tutte le strade portano alla scheda «Nuovo progetto» della pagina Progetti, che si apre in uno di questi modi:

dal «Pannello rapido», sotto «Nuovo progetto»: in alto a destra i collegamenti «Progetto vuoto» e «Da un indirizzo Git»; sotto, un riquadro per gruppo (Le mie basi, se ne hai salvate, poi Web, CMS, App, Altro) con le sue basi divise per categoria: un clic su una base apre la procedura con quella base già scelta;
dalle icone in cima alla barra laterale: «Nuovo progetto» (cartella con il più) e «Nuovo progetto da una base» (bacchetta);
dal riquadro «Nuovo progetto» della barra laterale, un albero: «Progetto vuoto», «Da un indirizzo Git», poi i rami Le mie basi (con la stella, se ne hai salvate), Web, CMS, App e Altro con il numero delle basi. Sotto Web, App e Altro ci sono le categorie e le loro basi, sotto CMS direttamente le basi; un clic su un gruppo apre la procedura sulla sua prima base, un clic su una base la apre con quella base già scelta;
da Ctrl+P, che in fondo all'elenco ha le tre voci «Nuovo progetto».

Un progetto creato o clonato compare subito anche nella pagina «Server Web».

Strada 1 · «Progetto vuoto»

Una cartella nuova e vuota in projects, da riempire come vuoi (anche copiandoci dei file).

Scrivi il nome della cartella nel campo «Vuoto».
Premi «Crea». Si apre la pagina del nuovo progetto.

Il nome non può contenere \ / : * ? " < > |, non può iniziare o finire con un punto e non può essere un nome riservato di Windows (come CON o NUL). Se esiste già una cartella con quel nome, il kit lo dice.

Strada 2 · «Da un indirizzo Git»

Copia (clona) un repository Git esistente in una cartella di projects.

Nel primo campo scrivi owner/repository per un repository GitHub (per esempio laravel/laravel), oppure l'indirizzo completo https:// di qualsiasi server Git.
Nel secondo campo, facoltativo, il nome della cartella; se lo lasci vuoto è l'ultima parte dell'indirizzo.
Premi «Clona».

Dopo la copia il kit guarda i file del progetto, installa i componenti che servono e sceglie le versioni che il progetto dichiara (per esempio la versione di Node scritta in .nvmrc o quella di PHP in composer.json), scaricandole se mancano.

Strada 3 · «Da una base»

Una procedura guidata che crea un progetto partendo da una base (un framework come Laravel, Django o Vite, un CMS come WordPress, un generatore di siti, un'app desktop o mobile…) e da eventuali aggiunte (Tailwind, React, un database, gli strumenti di prova…). Il kit installa gli strumenti che servono ed esegue i comandi ufficiali del framework, gli stessi che troveresti nella sua documentazione.

Passo	Che cosa fai
1. Base	Scegli un gruppo con le etichette in alto (Le mie basi, se ne hai salvate, Web con PHP, Web con JavaScript e TypeScript, Web con Python, Web con altri linguaggi, CMS, Siti statici e documentazione, App desktop, App mobile, Dati e documenti, Riga di comando e librerie) e poi la scheda della base.
2. Aggiunte	Spunta le aggiunte che vuoi. Sono divise per tipo (Interfaccia, Stili, Prove, Database…): di ogni tipo se ne sceglie una sola, e sceglierne un'altra sostituisce la prima.
3. Nome	Scrivi il nome del progetto. In alternativa usa un progetto esistente vuoto («vuoto») o con dei file ma senza Git («con file»): i file del framework si aggiungono e quelli che ci sono restano come sono. Un repository Git non si può usare.
4. File .env	Le variabili che il kit scriverà nel file .env del progetto. {name} diventa il nome del progetto, {package} un identificativo come com.example.nome, {password} una password nuova. Puoi cambiare i valori, togliere righe o aggiungerne con «Aggiungi una variabile».
Riepilogo	Che cosa succederà: gli strumenti del kit, il database del progetto, i comandi nella cartella projects, quelli nella cartella del progetto e le azioni che il progetto avrà.

Controlla il «Riepilogo» e premi «Crea il progetto».
Nella parte «Avanzamento» vedi «Installo gli strumenti del kit che servono…», poi «Comando 1 di N» con l'output di ogni comando.
Alla fine compare «Progetto … creato.» con «Apri il progetto». Se un comando fallisce, la procedura si ferma e mostra l'errore.

StrumentiInstalla ciò che la base e le aggiunte chiedono (Node, PHP, Composer…).
CreazioneEsegue i comandi di creazione nella cartella projects.
DatabaseSe previsto, crea database e utente e scrive la connessione in .env.
RifinituraEsegue i passi nella cartella del progetto (installazioni, migrazioni).
AzioniSalva le azioni della ricetta nel file panel.json del progetto.

Sotto il cofano

Si crea un progetto alla volta. «Annulla», durante l'avanzamento, ferma il comando in corso.
Ogni riga della ricetta è un comando eseguito con la PowerShell del kit e con l'ambiente del kit, quindi con le versioni degli strumenti del kit.
Se usi un progetto esistente con dei file, il framework viene generato in una cartella temporanea del sistema e poi spostato nel progetto: i file che ci sono già restano, e nell'avanzamento compare «Già nel progetto, lasciato com'è».
Se il piano prevede MySQL o MongoDB, il kit avvia il server, crea database e utente del progetto e passa ai comandi le variabili ATOLLO_DB_HOST, ATOLLO_DB_PORT, ATOLLO_DB_NAME, ATOLLO_DB_USER, ATOLLO_DB_PASSWORD e ATOLLO_DB_URL. La password generata dal kit prende il posto di una vuota che arriva dalla base (per esempio DB_PASSWORD= nel suo .env.example).
Alla fine, se c'è un file .env che Git prenderebbe, il kit aggiunge /.env al file .gitignore.
Le azioni della ricetta vanno nel file panel.json del progetto con un identificativo che comincia con fw- (per esempio fw-avvia).
Alcune basi richiedono componenti particolari: le app Android vogliono il componente Android SDK; Laravel con MongoDB vuole l'estensione mongodb di PHP, che il kit non installa.

«Le mie basi»

Un tuo progetto può diventare una base, da cui crearne altri uguali: per esempio un Laravel con i pacchetti di sempre o la struttura di un monorepo.

Nella pagina del progetto premi «Salva come base», nella testata accanto ad «Apri la cartella».
Scrivi il nome della base (all'inizio è quello del progetto) e, se vuoi, una descrizione.
In «Cosa copiare» c'è ogni cartella e file della radice del progetto, con il numero dei file e la dimensione: togli la spunta a quelli che non vuoi. Sotto, il totale.
Premi «Salva come base»: «Salvata: la trovi in Nuovo progetto › Le mie basi. Con lo stesso nome la si sostituisce.»

Quali file: in un repository Git, quelli che Git terrebbe, cioè i file seguiti e quelli nuovi che .gitignore non esclude. Senza Git, tutti tranne le cartelle senza sorgenti (node_modules, vendor, .venv, venv, target, dist, build e simili). Mai .env né .env.local e le altre copie, che hanno le password: .env.example invece resta. Mai la cartella .git.

Per usarla: in «Nuovo progetto» il gruppo «Le mie basi», con la stella, è il primo. Il kit copia i file della base nel progetto nuovo invece di eseguire i comandi di un framework, poi scrive il .env, esegue i passi e salva le azioni come per le altre basi. Anche qui puoi usare un progetto esistente vuoto o con dei file ma senza Git.

Sotto il cofano

I file vanno in data\frameworks\mine\<id>, dove l'id è mine- seguito dal nome in lettere minuscole, cifre e trattini. La copia si fa a parte e poi prende il posto di quella di prima: salvare di nuovo con lo stesso nome sostituisce file e base.
Per togliere una base: Impostazioni, istruzioni dei framework, «Togli» sulla base; al salvataggio se ne va anche la sua cartella. Se la cartella manca, creare un progetto dice «La cartella della base non c'è più: salvala di nuovo dal progetto.»
Collegamenti e junction dentro il progetto non si copiano. Senza Git si salta anche la cartella storage: in un Laravel senza Git va ricreata con i passi della base.

I tuoi repository GitHub

Se hai collegato l'account GitHub, il riquadro «Dai tuoi repository GitHub» della barra laterale elenca i tuoi repository e quelli delle organizzazioni di cui fai parte, raggruppati per proprietario, con una casella «Cerca nei repository».

«Clona» copia il repository in projects (nella cartella con il suo nome, oppure proprietario-nome se il nome è già preso). Un repository già clonato ha il nome in verde e il pulsante «Editor».
«GitHub» apre il repository nel browser.
Con un clic sulla riga si aprono i dettagli: privato o pubblico, linguaggio, stelle, ultimo push, dove è clonato, «Copia l'indirizzo per Git» e, per i repository che amministri, «Rinomina» ed «Elimina da GitHub».