Canova

Documentazione

Quick Start

Benvenuto! Questo boilerplate è configurato per minimizzare il time-to-interface. Tutto è già pronto, puoi iniziare a costruire subito.

Pre Requisiti

Per usare questo boilerplate ti servono i seguenti software:

Node.js

versione 20.x o superiore

Git

per clonare il repository

VSCode / Cursor

o qualsiasi altro IDE

Quick Start
1

Hard fork del repository

Fai un hard fork del repository per poter modificare il codice senza influenzare la repo originale. Il link del boilerplate originale è qui sotto.

https://bitbucket.org/dosai/canova-frontend-boilerplate/src/main/
2

Posiziona la repo nella tua macchina

Apri il terminale nella cartella in cui vuoi posizionare la repo forkata

3

Clona la repo forkata

Clona la repository che hai creato nel primo passaggio all'interno della cartella scelta

git clone <your-fork-repository-url>
4

Entra nel progetto copiato

Con il terminale o con un IDE di tuo gradimento posizionati nella root principale del progetto

cd <your-project-folder>
5

Installa le dipendenze

Installa le dipendenze già configurate per il progetto

npm i
6

Avvia il dev server

Avvia il dev server per avviare il progetto in locale

npm run dev
7

Visualizza il progetto

Apri il browser e vai a http://localhost:3000 per visualizzare il progetto in locale

8

Inizia a sviluppare

Modifica il codice della homepage del progetto (src/app/page.tsx) per creare la tua prima pagina

Struttura del Progetto
Composizone del progetto per gestire logica e presentazione in maniera organizzata.
src/
├── app/             # Next.js App Router (pagine e routing)
├── components/      # Componenti React riutilizzabili
│   └── ui/          # Componenti Shadcn/UI
|	└── .../         # Altri componenti personalizzati
├── hooks/           # Custom React hooks
├── store/           # Zustand stores
├── lib/             # Organizzazione codice di supporto
|	└── utils.ts 	 # Generic utility functions
|	└── constants.ts # Constanti di utilizzo generale
|	└── api/	     # API utility functions
|      └── ...		 # API endpoints calls (e.g. user.ts, products.ts, etc.)
├── providers/       # React context providers
├── config.ts        # Configurazione app (nome, tema, font)
└── types.ts         # TypeScript types condivisi
Convenzioni
Linee guida e convenzioni per mantenere il codice consistente, manutenibile e allineato agli standard del progetto.

Fetching e mutation pattern
Pattern a 3 strati per separare chiaramente la gestione dei dati dalla UI.

Layer API

src/lib/api

Hooks

src/hooks

Componenti UI

solo hooks

Form Validation Pattern
Pattern a 2 strati (Custom Hook + Componente Form) per separare validazione dalla UI e garantire type-safety end-to-end con React Hook Form e Zod.

Custom Hook

schema + logica submit

Componente Form

solo UI

State management pattern
Zustand per lo state globale: leggero, intuitivo e senza boilerplate. Store separati per dominio con state, actions e getters ben definiti.

State

Dati immutabili

Actions

Modifica via set()

Getters

Valori derivati

Vibe coding
Il boilerplate è pensato per lo sviluppo assistito da agenti AI: MCP e regole dedicate aiutano Cursor e altri IDE a rispettare stack e pattern del progetto.

Server MCP nel progetto

In .cursor/mcp.json sono configurati i server MCP che Cursor espone agli agenti. Abilitali dalle impostazioni MCP dell'IDE per avere contesto aggiornato su componenti UI, Zod e Zustand mentre generi o modifichi codice.

shadcn

Integrazione MCP ufficiale di Shadcn/UI: consente agli agenti di cercare, aggiungere e configurare componenti UI in linea con il design system del progetto.

inkeepMcp

Documentazione Zod via Inkeep: gli agenti possono consultare API, esempi e best practice per schemi e validazione type-safe.

zustand Docs

Documentazione Zustand (GitMCP): supporta la creazione e la modifica degli store globali seguendo le API e i pattern ufficiali della libreria.

Regole per gli agenti

Il file .agent/rules.md descrive come gli agenti AI devono lavorare su questa repository: stack da rispettare, pattern architetturali (fetching, form, state), convenzioni di naming e quando è lecito discostarsi dalle scelte predefinite.

Apri il file nella root del progetto prima di sessioni di vibe coding lunghe, oppure assicurati che le tue Cursor Rules facciano riferimento a quelle linee guida, così creazione e modifica del codice restano allineate al boilerplate.

Esempi di prompt

Puoi incollare questi prompt in Cursor (o in un altro agente) per ottenere codice già allineato al boilerplate. Riferisci sempre .agent/rules.md quando vuoi che l'agente rispetti stack e pattern del progetto.

1

Pagina con form di contatto

Costruisci una pagina /contatto con un form (nome, email, messaggio) usando i componenti Shadcn/UI già presenti nel progetto. Segui le regole in .agent/rules.md
2

Lista dati con fetching

Aggiungi una pagina /articoli che mostra una tabella degli articoli con TanStack Table. Rispetta le regole definite in .agent/rules.md
3

Nuovo componente UI

Aggiungi il componente Dialog di Shadcn tramite MCP shadcn se non è già nel progetto, poi crea un ConfirmDeleteDialog riutilizzabile in src/components/. Stile e convenzioni come definite in .agent/rules.md
Pulizia del Progetto
Se vuoi rimuovere file di esempio e documentazione per partire da un progetto più pulito, puoi eseguire lo script dedicato dalla root del progetto.

Lo script elimina le seguenti cartelle:

src/app/docs/— pagine di documentazione
src/components/docs/— componenti della documentazione
src/components/moduli/— componenti dei moduli

Esegui lo script:

./scripts/remove-docs.sh

Oppure: bash scripts/remove-docs.sh