TanStack Router & Start: quando il framework smette di essere magia

Negli ultimi anni Next.js si è affermato come il meta-framework React più diffuso, introducendo progressivamente nuove astrazioni per gestire rendering, data fetching e organizzazione del codice. Questo approccio offre molti vantaggi, ma comporta anche una maggiore presenza di convenzioni implicite e comportamenti automatici. In determinati contesti, comprendere esattamente cosa stia accadendo può richiedere un livello di conoscenza più profondo del framework.

Non è un caso se molti sviluppatori stanno iniziando a guardarsi intorno, non perché manchino le feature, ma perché manca il controllo sulle feature stesse.

Ed è qui che l’ecosistema TanStack sta attirando sempre più attenzione. Non tanto per l’hype, quanto per un’idea molto chiara: meno effetto “magia”, più concretezza.

In questo articolo voglio concentrarmi su tre esempi che spiegano bene perché TanStack Router e TanStack Start sono interessanti e meritano di essere esplorati seriamente.

_Routing e Link completamente type-safe

La prima cosa che colpisce di TanStack Router è che il routing smette di essere un insieme di stringhe sparse nel codice e diventa un contratto tipizzato.

Con il file-based routing definisci le rotte tramite filesystem, ma la differenza vera è che ogni rotta è conosciuta da TypeScript e questo cambia tutto.

Parametri dinamici tipizzati automaticamente

Immaginiamo una dashboard gestionale con una pagina dedicata al dettaglio di un ordine: /orders/$orderId

// src/routes/orders.$orderId.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/orders/$orderId')({
  component: OrderDetail,
})

function OrderDetail() {
  const { orderId } =Route.useParams()
  return<div>Order ID: {orderId}</div>
}

Qui non stai semplicemente leggendo una stringa dall’URL.

Stai dichiarando che quella pagina richiede un orderId, e TypeScript lo sa.

Link che non compilano se sbagli

La parte davvero interessante arriva quando costruisci i link:

<Link
  to="/orders/$orderId"
  params={{ orderId: 'ORD-2026-001' }}
>
View Order
</Link>

Se dimentichi orderId, passi un valore con il type sbagliato o punti a una rotta che non esiste, il codice non compila. Questo significa che se cambi una rotta o aggiungi un parametro obbligatorio, TypeScript ti dice subito dove sta il problema.

Niente bug scoperti a runtime, niente link “silenziosamente sbagliati”.

_Search params validati: il contratto si propaga

Il secondo esempio è quello che mostra meglio la filosofia di TanStack.

I search params non sono un dettaglio secondario, ma parte integrante della rotta.

In TanStack Router puoi dichiarare quali search params una pagina accetta, come devono essere validati e che tipo devono avere.

import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

const searchSchema = z.object({
  page: z.coerce.number(),
  status: z.enum(['active', 'inactive']).optional(),
})

export const Route = createFileRoute('/customers')({
  validateSearch: (search) => searchSchema.parse(search),
  component: CustomersPage,
})

Qui stai dicendo che questa pagina dichiara esplicitamente che il parametro page è obbligatorio e deve essere un numero.

Effetto immediato sui Link esistenti

La parte più interessante non è la validazione in sé, ma l’effetto a cascata.

Se rendi page obbligatorio vuol dire che tutti i Link che puntano a /users devono passare anche search={{ page: ... }}

<Link
  to="/customers"
  search={{ page: 1, status: 'active' }}
>
Active Customers
</Link>

Se un link non lo fa, TypeScript lo segnala subito.

Questo significa che una modifica all’interfaccia della rotta non rompe l’app in produzione, non genera bug silenziosi e viene intercettata mentre stai scrivendo il codice.

È un approccio molto più simile a quello di una API ben progettata, che non a un semplice sistema di URL.

_TanStack Start e le Server Functions

Arriviamo a TanStack Start, che viene spesso visto come “l’alternativa a Next.js”.

Qui la differenza non sta tanto nelle feature, quanto nel rendere più esplicito ciò che succede. Una differenza di approccio sostanziale.

In Start tutto il codice è, per impostazione predefinita, isomorfo. Lo stesso componente o la stessa funzione possono girare sia lato server sia lato client.

Nel momento in cui questa distinzione diventa rilevante, non è il framework a decidere per te, ma sei tu a dichiarare cosa deve girare solo lato server.

Server Function: RPC esplicita, tipizzata

import { createServerFn }from'@tanstack/start'

exportconst getData =createServerFn({method:'GET' })
  .handler(async () => {
return {message:'Hello world' }
  })

Qui stai dicendo esattamente cosa vuoi:

• questa funzione gira sul server
• è una GET
• ritorna un certo tipo di dato

Uso dal loader o dal client, senza ambiguità

exportconstRoute =createFileRoute('/')({
loader:async () => {
returnawaitgetData()
  },
component:Page,
})

Cosa succede:

• lato server: la funzione viene chiamata direttamente
• lato client: Start genera automaticamente una fetch verso un endpoint interno

Tu non devi creare endpoint manuali, indovinare cosa fa il framework, ricordarti regole implicite.

Se vuoi una GET, scrivi GET, se vuoi una POST, scrivi POST.

Ed è proprio qui la differenza con certi approcci più impliciti, non devi sapere come il framework si comporta sotto il cofano, perché glielo stai dicendo tu.

_Un approccio che funziona

TanStack non è uno stack che cerca di fare tutto al posto tuo, ma uno strumento che ti mette nelle condizioni di capire cosa stai costruendo e perché sta funzionando in quel modo ed è proprio questo il suo punto di forza.

TanStack Router e TanStack Start non sono l’ennesima moda né un’alternativa “con ancora più feature”, sono il segnale di una direzione chiara: tornare a framework che aiutano lo sviluppatore a ragionare meglio, non solo a scrivere codice più in fretta.

Se senti che certi strumenti stanno diventando troppo vaghi, o se vuoi che TypeScript lavori davvero per te, come guida al tuo lavoro, vale la pena fermarsi un attimo e guardare questa direzione. Perché quando il framework smette di essere “magia”, il codice diventa molto più facile da capire, modificare e mantenere, soprattutto nei progetti che crescono nel tempo.