Guida rapida

Crea un nuovo progetto

pnpm dlx @rebasepro/cli init my-app

Questo genera lo scaffold di un progetto con tre pacchetti. Se concetti come collection, Studio, managed runtime, bundle o resource sono nuovi per te, il riquadro con le cinque definizioni in Project Structure li spiega nel dettaglio.

Cartella	Descrizione
frontend/	SPA React — Vite + TypeScript con l’interfaccia utente di amministrazione di Rebase
backend/	Le tue funzioni personalizzate e i cron job, oltre allo schema Drizzle generato. Non c’è alcun file server: il runtime pubblicato avvia direttamente il progetto
config/	File di configurazione e definizioni delle collezioni condivisi da entrambe le parti

Prerequisiti

• Node.js 22.22+ — ogni scaffold, incluso quello headless, dichiara "node": ">=22.22.0"
• pnpm (consigliato) o npm

Nessun database da installare e nessun Docker richiesto. rebase dev esegue un’istanza gestita di PostgreSQL per il progetto, con i dati memorizzati in .rebase/. Consulta Variante: usa la tua istanza di PostgreSQL se preferisci fornirne una tu: un’installazione locale, Neon, Supabase o il container incluso in questo scaffold.

Il tuo ambiente è già configurato

init genera un file .env pronto all’uso nella radice del progetto con un vero JWT_SECRET, una password per il database e una porta locale libera per il database. Non è necessario creare o modificare nulla per iniziare.

Attenzione

Non eseguire cp .env.example .env. .env.example serve come riferimento per le variabili disponibili: sovrascriverlo al tuo .env scarterà i secret generati e farà puntare DATABASE_URL a un database inesistente. Modifica direttamente .env se vuoi cambiare un valore.

Avvia i server di sviluppo

pnpm install
pnpm run dev

Questo è tutto ciò che serve per il primo avvio. Non c’è alcun database da installare e nessun passaggio relativo allo schema: se non viene impostato alcun DATABASE_URL, rebase dev avvia un PostgreSQL gestito (PGlite) nella directory del progetto, genera lo schema Drizzle dalle tue collezioni e crea le tabelle all’avvio — incluse quelle di esempio posts, authors e tags.

Avvia entrambe le parti contemporaneamente:

• Backend — API REST, autenticazione, storage, WebSocket
• Frontend — il pannello: Rebase CMS e Rebase Studio
• Hot reload per entrambi

Entrambe le porte sono derivate dal percorso del progetto anziché essere fisse, consentendo a diversi progetti Rebase di essere eseguiti contemporaneamente. rebase dev mostrerà i due URL associati — usa quelli, non localhost:3001 / localhost:5173. (PORT e VITE_API_URL in .env configurano rebase start, che esegue il bundle compilato, e qui vengono ignorati.) Fissa una porta con rebase dev --port 3001.

Flag utili da conoscere

Flag	Su	Cosa fa
--yes	init	Non richiede mai conferme interattive. Obbligatorio quando non c’è un terminale a cui rispondere, come nei contesti di CI. Salta git init e l’installazione delle dipendenze — le opzioni predefinite interattive rispondono affermativamente a entrambi, quindi passa --git / --install se li desideri
--headless	init	Un backend senza file di collezione e senza interfaccia grafica — vedi Backend only
--template <name>	init	Avvia il progetto da un template diverso da quello predefinito
--install / --no-install	init	Esegue il gestore di pacchetti al posto tuo, oppure lo ignora
--docker	dev	Usa PostgreSQL in un container al posto di quello gestito. Da 0.25 Gli altri comandi lo seguono finché rebase dev non viene eseguito senza. Un DATABASE_URL ha la precedenza: allora non avvia nulla, e lo dice
--no-db	dev	Non avvia alcun database — né il container né quello gestito. Imposta DATABASE_URL manualmente

Variante: usa la tua istanza di PostgreSQL

Il database gestito è una comodità, non un obbligo. Per puntare il progetto a un’istanza di Postgres gestita da te, decommenta DATABASE_URL in .env:

DATABASE_URL=postgresql://username:password@localhost:5432/your_database

Quindi avvia i server di sviluppo come descritto sopra. Un DATABASE_URL impostato non viene mai sovrascritto, e qualsiasi URL che punti a una destinazione diversa da questa macchina viene lasciato del tutto inalterato.

I comandi di migrazione pianificano le modifiche con Atlas, il motore di migrazione degli schemi utilizzato da Rebase, che richiede un secondo database vuoto per effettuare i confronti. Sul tuo database Rebase ne crea uno accanto; su quello gestito, che ne serve esattamente uno, avvia un PGlite temporaneo per la durata del comando. Da 0.25 Su 0.24 i comandi di migrazione rifiutano il database gestito, e richiedono il tuo. In entrambi i casi:

pnpm run db:push

La procedura di avvio crea già le tabelle mancanti — e le relative policy RLS (Row-Level Security di PostgreSQL, con cui Rebase stabilisce chi può leggere una riga) — in modo additivo, quindi db push serve per ciò che lascia intenzionalmente invariato: qualsiasi modifica che non sia puramente additiva — una colonna rinominata, un tipo ristretto, un campo rimosso.

Lo scaffold include anche un file docker-compose.yml con un servizio PostgreSQL, qualora preferissi usare un container anziché un’installazione locale di Postgres:

docker compose up -d db

Esegui l’introspezione di un database esistente (opzionale)

Se ti stai connettendo a un database esistente con tabelle già create, puoi eseguirne l’introspezione per generare automaticamente i file delle collezioni in TypeScript:

pnpm rebase schema introspect

Questo comando analizzerà le tabelle del tuo database e genererà i corrispondenti file TypeScript in config/collections/, evitandoti di doverli scrivere a mano.

Primo accesso

Quando apri l’URL del frontend mostrato da rebase dev, vedrai la schermata di login. Il primo utente a registrarsi diventa automaticamente un amministratore: questo è il flusso di bootstrap.

1. La schermata si apre su Welcome!, il modulo per quel primo account
2. Inserisci email e password, poi clicca su Create account
3. Hai effettuato l’accesso — con privilegi completi di amministratore

rebase init ha inoltre inserito REBASE_ADMIN_EMAIL e una REBASE_ADMIN_PASSWORD generata all’interno di .env. Queste non sono le credenziali da usare in questa fase: rebase dev le ignora e lo segnala all’avvio. Servono per gli avvii in produzione — docker compose up o qualsiasi processo con NODE_ENV=production — dove la finestra di bootstrap è chiusa, poiché il server risponde su un hostname pubblico prima ancora che tu possa inserire dei dati. Consulta Your first admin.

Definisci la tua prima collezione

Apri config/collections/ e crea un nuovo file. Esporta la collezione come default export — è ciò che il backend e il pannello di amministrazione caricano da ogni file della cartella. Il nome della tabella è opzionale: come impostazione predefinita corrisponde allo slug, quindi specificalo solo se differiscono:

import { defineCollection } from "@rebasepro/cms-types";

const productsCollection = defineCollection({
    slug: "products",
    name: "Products",
    properties: {
        name: {
            type: "string",
            name: "Name",
            validation: { required: true }
        },
        price: {
            type: "number",
            name: "Price",
            validation: { required: true, min: 0 }
        },
        description: {
            type: "string",
            name: "Description",
            admin: { multiline: true }
        },
        active: {
            type: "boolean",
            name: "Active",
            defaultValue: true
        },
        createdAt: {
            type: "date",
            name: "Created At",
            autoValue: "on_create"
        }
    }
});

export default productsCollection;

Aggiungila poi all’array collections in config/collections/index.ts. Quell’array è un ordinamento, non un registro: ogni file di collezione nella cartella viene caricato — dal backend, dal pannello di amministrazione e dal generatore dell’SDK — che l’array lo elenchi o no, e l’array decide solo dove compare nella navigazione. Per rimuovere una collezione, elimina il suo file:

// ...existing imports
import productsCollection from "./products.js";

export const collections = [
    postsCollection, authorsCollection, tagsCollection, usersCollection, productsCollection
];

Crea la tabella

Salva il file. Non serve altro: rebase dev rigenera backend/src/schema.generated.ts e i tipi dell’SDK in generated/sdk/ a partire dalle tue collezioni, riavvia il backend e l’avvio crea la nuova tabella — così la collezione Products compare direttamente nella barra di navigazione.

Sulla 0.23, rebase dev rigenera solo lo schema, quindi esegui rebase generate-sdk dopo una modifica a una collezione prima di importare i suoi tipi.

La stessa logica si applica all’aggiunta di una proprietà a una collezione esistente: salva e la colonna sarà subito pronta.

rebase db push è riservato alle modifiche che l’avvio lascia intenzionalmente invariate — una colonna rinominata, un tipo ristretto, un campo rimosso:

pnpm run db:push

Da 0.25 Funziona sul database gestito come sul tuo. Su 0.24 richiede una tua istanza PostgreSQL.

Riferimento dei comandi del database

Comando	Descrizione
rebase schema generate	Genera lo schema Drizzle dalle tue collezioni TypeScript. Nessun database richiesto — rebase dev lo esegue per te
rebase schema introspect	Genera collezioni TypeScript a partire da un database esistente
rebase db push	Applica le modifiche allo schema direttamente al database, compreso quello gestito
rebase db generate	Genera file di migrazione SQL
rebase db migrate	Esegue le migrazioni in sospeso

Da 0.25 I tre comandi db funzionano sul database gestito. Su 0.24 richiedono una tua istanza di PostgreSQL.

Passaggi successivi

• Project Structure — Comprendi il codice generato
• Collections — Approfondimento sulla definizione dello schema
• Environment & Configuration — Tutte le opzioni di configurazione
• Deployment — Distribuisci in produzione