@truss-dev/trellis

Un plugin Vite professionale per il File-system Based Routing in React. Porta la semplicità di Next.js nel tuo progetto Vite + React Router.

Caratteristiche

• 🚀 Zero Config: Scansiona automaticamente la cartella delle pagine.
• 📦 Code Splitting: Ogni pagina è un chunk separato (Lazy Loading).
• 🛠 Type Safe: Genera tipi TypeScript automatici per le tue rotte.
• 🏗 Nested Layouts: Supporto nativo ai layout nidificati.
• ⏳ Loading States: Supporto automatico a loading.tsx (React Suspense).
• ⚠️ Error Boundaries: Supporto a error.tsx per isolare i crash di rotta.
• 🔍 SEO Ready: Supporto a meta.ts per gestire metadati dinamici.
• 📂 Route Groups: Cartelle (group) per organizzare i file senza influire sull'URL.
• 🌐 Catch-all: Supporto a [...] per rotte jolly e wildcard.
• 🛠 CLI Scaffolding: Comando gen per generare istantaneamente pagine, layout e stati di errore.

Installazione

npm install @truss-dev/trellis react-router-dom

Utilizzo con Vite (Raccomandato)

1. Configura Vite

// vite.config.ts
import { fsRouter } from "@truss-dev/trellis";

export default defineConfig({
  plugins: [
    fsRouter({
      pagesDir: "src/pages", // Opzionale: cartella delle pagine (default: "src/pages")
    }),
  ],
});

[!IMPORTANT] Se decidi di utilizzare una cartella diversa da src/pages, assicurati di passare lo stesso percorso a tutti i comandi CLI (gen, build) e alle opzioni del plugin.

2. Configura Git

Il plugin genera un file locale per fornire tipi istantanei. Aggiungi la cartella al tuo .gitignore:

.trellis/

3. Utilizzo nel Codice

Importa le rotte direttamente dal pacchetto virtuale. Grazie al nostro Pro Export Proxy, i tipi funzionano istantaneamente anche a server spento.

import { createBrowserRouter, RouterProvider } from "react-router-dom";
import { routes } from "@truss-dev/trellis/routes";

const router = createBrowserRouter(routes);

export default function App() {
  return <RouterProvider router={router} />;
}

Funzioni Avanzate

📂 Nested Layouts (layout.tsx)

Crea un file layout.tsx per avvolgere tutte le pagine in quella directory. Usa <Outlet /> di React Router per renderizzare i figli.

// src/pages/dashboard/layout.tsx
import { Outlet } from "react-router-dom";

export default function DashboardLayout() {
  return (
    <div>
      <nav>Sidebar Dashboard</nav>
      <main>
        <Outlet />
      </main>
    </div>
  );
}

⏳ Stati di Caricamento (loading.tsx)

Se aggiungi un file loading.tsx in una cartella, la pagina verrà automaticamente avvolta in un <Suspense fallback={<Loading />} />.

⚠️ Error Boundaries (error.tsx)

Cattura gli errori di rendering specifici per quella rotta (mappa alla proprietà ErrorBoundary di React Router).

🔍 SEO Metadata (meta.ts)

Esporta un oggetto da meta.ts. Sarà accessibile tramite handle.meta nelle tue rotte. Puoi usare l'interfaccia RouteMeta per avere piena assistenza dal compilatore.

// src/pages/about/meta.ts
import { RouteMeta } from "@truss-dev/trellis";

const meta: RouteMeta = { 
  title: "Chi Siamo", 
  description: "La nostra storia" 
};

export default meta;

📂 Route Groups ((group))

Le cartelle tra parentesi vengono ignorate nell'URL finale. src/pages/(auth)/login/page.tsx -> /login

Utilizzo CLI (Universale)

Se desideri generare le rotte senza usare il plugin Vite (es. per un progetto Webpack o CLI pura):

# Generazione singola
npx trellis --out src/routes.generated.tsx

# Modalità Watch (raccomandata per sviluppo)
npx trellis --watch --out .trellis/routes.tsx

🛠 Generatore di Pagine (gen)

Puoi generare rapidamente la struttura di una nuova pagina (inclusi layout, loading ed error) con un comando interattivo:

npx trellis gen

Come funziona:

1. Nome della pagina: Inserisci il percorso (es. login o admin/settings).
2. Selezione file: Scegli quali file generare tramite la lista interattiva:
   • page.tsx: Il componente principale della pagina (selezionato di default).
   • layout.tsx: Per definire layout specifici di rotta.
   • loading.tsx: Per gestire i caricamenti tramite React Suspense.
   • error.tsx: Per intercettare errori di rendering.

Il comando creerà automaticamente le cartelle necessarie e popolerà i file con un template funzionale pronto all'uso.

Opzioni:

• -p, --pages <dir>: Specifica la directory delle pagine (default: src/pages).

Struttura Cartelle Esempio

• src/pages/page.tsx -> /
• src/pages/layout.tsx -> Layout Root
• src/pages/loading.tsx -> Loading Root
• src/pages/about/page.tsx -> /about
• src/pages/user/[id]/page.tsx -> /user/:id (Parametri dinamici)
• src/pages/docs/[...slug]/page.tsx -> /docs/* (Wildcard)

Licenza

MIT