Vai al contenuto principale

Setup locale dell'API

Questa guida ti accompagna nel setup dell'API di ChurchApps per lo sviluppo locale. Clonerai il repository, configurerai le connessioni al database, inizializzerai lo schema e avvierai il server di sviluppo con hot reload.

Prima di iniziare

  • Installa Node.js 24+, Git e MySQL 8.0+ -- vedi Prerequisiti
  • Crea un utente MySQL con i privilegi per creare database
  • Consulta il riferimento delle variabili d'ambiente per la configurazione dell'API

Setup passo per passo​

1. Clona il repository​

git clone https://github.com/ChurchApps/Api.git

2. Installa le dipendenze​

Il progetto usa Yarn (un controllo blocca npm install):

cd Api
yarn install

3. Configura le variabili d'ambiente​

cp .env.sample .env

Apri .env e configura le stringhe di connessione a MySQL. Ogni modulo ha bisogno della propria connessione al database nel seguente formato:

mysql://root:password@localhost:3306/dbname

Ti servono le stringhe di connessione per tutti e sei i database dei moduli (membership, attendance, content, giving, messaging, doing).

4. Inizializza i database​

npm run initdb

Questo crea automaticamente tutti e sei i database e le relative tabelle.

Suggerimento

Puoi inizializzare il database di un solo modulo con npm run initdb -- --module=membership (oppure attendance, content, giving, messaging, doing).

5. Avvia il server di sviluppo​

npm run dev

L'API si avvia con hot reload su http://localhost:8084.

Comandi principali​

ComandoDescrizione
npm run devAvvia il server di sviluppo con hot reload (tsx watch)
npm run buildPulisce, compila il TypeScript e copia gli asset
npm run testEsegue i test con Jest (include la copertura)
npm run test:watchEsegue i test in modalità watch
npm run lintEsegue ESLint con correzione automatica (ESLint è l'unico formattatore)

Deployment​

L'ambiente di staging è stato dismesso. L'Api viene distribuita sull'ambiente demo a ogni push su main, e in produzione tramite il workflow manuale Deploy Prod, che applica anche le migrazioni del database in sospeso. Vedi Deployment dell'API per i dettagli.

Sviluppo locale delle librerie​

Se devi sviluppare una libreria condivisa (@churchapps/helpers o @churchapps/apihelper) insieme all'API, compilala nel workspace Packages e aggiungi un portal Yarn temporaneo nell'API:

# Nel workspace Packages
yarn build

# Nella directory dell'API
yarn link ../Packages/helpers
# ... test ...
yarn unlink ../Packages/helpers && yarn install

Questo ti permette di testare le modifiche alle librerie con l'API senza pubblicarle su npm. Vedi Librerie condivise per i dettagli -- e non committare mai la risoluzione del portal che il link scrive in package.json.

Articoli correlati​