Quando lavori su frontend che crescono davvero, la gestione delle API inizia quasi sempre in modo semplice.

Una fetch qui. Una useQuery lì. Un paio di mutation sparse. Magari un po’ di logica condivisa infilata in utility o hook custom.

Finché il progetto è piccolo, regge.

Poi però il codice cresce, gli endpoint aumentano, i flussi diventano più articolati e iniziano a comparire problemi molto concreti:

• logica API sparsa in file diversi
• naming incoerente tra operazioni simili
• integrazione con React Query ripetitiva
• poca chiarezza su dove “vive” davvero ogni operazione

È da qui che è nata ddmushi.

Una libreria open-source costruita dagli Arkers come esperimento per organizzare le API in modo più pulito, type-safe e vicino all’esperienza developer di tRPC, ma restando perfettamente compatibile con API REST già esistenti.

😵‍💫​ Il problema: le API frontend diventano facilmente disordinate

Chi usa TanStack React Query lo sa: è una libreria fortissima, flessibile, e ti lascia molta libertà.

Ma proprio questa libertà, in codebase grandi o in crescita, può trasformarsi in dispersione.

In molti progetti ci siamo trovati davanti a uno scenario abbastanza tipico:

• endpoint REST già esistenti
• React Query usato ovunque
• Zod introdotto per rendere più sicuri input e output
• diversi moduli applicativi che crescevano in parallelo
• necessità di mantenere una struttura leggibile nel tempo

Quello che mancava era un modo elegante per dare una forma coerente a tutto questo.

🤔​ Perché non tRPC?

Perché non sempre puoi o vuoi cambiare il tuo backend.

tRPC offre una developer experience molto bella, soprattutto per il type-safety end-to-end, ma richiede un certo allineamento architetturale tra client e server.

Noi volevamo qualcosa che desse una sensazione simile lato organizzazione e DX, ma applicabile anche a contesti più realistici e frequenti:

• backend REST già in produzione
• team che non possono riscrivere l’API
• progetti che vogliono migliorare il frontend senza rivoluzioni
• necessità di introdurre ordine in modo incrementale

Da qui l’idea:portare una struttura tRPC-like nella gestione delle operazioni API, sopra React Query, senza rinunciare alla libertà di lavorare con endpoint REST esistenti.

🤩​ Cos’è ddmushi

ddmushi è una libreria per organizzare operazioni API in modo type-safe, con integrazione automatica con TanStack React Query.

Il nome ddmushi viene dai Den Den Mushi di One Piece, le lumache usate per comunicare a distanza. Ci sembrava un riferimento perfetto per una libreria che organizza la comunicazione tra frontend e API 😉​

L’idea è semplice:

• definisci un router con un context condiviso
• organizzi le operazioni in collection nidificate
• descrivi query e mutation in modo leggibile
• colleghi validazione input/output
• ottieni queryOptions(), mutationOptions() e infiniteQueryOptions() già pronte da usare

In pratica, invece di avere logica API sparsa e convenzioni implicite, costruisci una struttura esplicita, modulare e riusabile.

GitHub - arkemis-labs/ddmushi: Organize and consume your APIs in a better way

Organize and consume your APIs in a better way. Contribute to arkemis-labs/ddmushi development by creating an account on GitHub.

👨‍💻​ Un esempio concreto

Con ddmushi puoi definire una struttura come questa:

jsx

E poi consumarla così dentro React:

jsx

Il vantaggio non è solo sintattico.

Il vantaggio è che query, mutation, validazione, middleware e organizzazione dei moduli iniziano a parlare tutti la stessa lingua.

🎯​ I problemi che volevamo risolvere

ddmushi è nata per affrontare una serie di problemi molto concreti.

1. Logica API troppo frammentata

In tanti progetti, la logica API è distribuita tra:

• service
• hook custom
• file queries.ts
• file mutations.ts
• etc.

Risultato: per capire un flusso, devi attraversare troppi layer.

Con ddmushi volevamo riportare le operazioni in un punto più leggibile e strutturato.

2. Validazione scollegata dal punto in cui serve

Spesso la validazione esiste, ma è sparsa o usata in modo non uniforme.

Con ddmushi puoi dichiarare .input() e .output() direttamente nella definizione dell’operazione.

Questo rende più chiaro cosa entra, cosa esce e dove avviene il controllo.

3. Integrazione React Query ripetitiva

React Query è ottima, ma il boilerplate si accumula facilmente.

Se ogni modulo definisce da sé query key, opzioni, logiche di fetch e binding, nel tempo rischi incoerenza.

ddmushi prova a ridurre questo attrito standardizzando il modo in cui esponi le operazioni.

4. Difficoltà nel riusare comportamenti cross-cutting

Autenticazione, logging, error handling, caching, enrichment del context: sono esigenze normali.

Per questo abbiamo introdotto middleware componibili, così da rendere più facile applicare comportamenti condivisi senza duplicare logica.

5. Mantenere una DX pulita anche con API REST esistenti

Non volevamo reinventare il backend.

Volevamo migliorare il modo in cui il frontend ci parla.

🔥​ Le feature principali

Type-safety e inferenza automatica

ddmushi punta a rendere il flusso più sicuro senza appesantirlo.

Con TypeScript e schema validation, input e output possono essere inferiti automaticamente.

Integrazione nativa con TanStack React Query

Libreria pensata per lavorare in modo naturale con query, mutation e infinite query.

Organizzazione per collection

Le operazioni possono essere nidificate in collezioni, mantenendo una struttura leggibile anche quando il progetto cresce.

Validazione built-in

Supporto a librerie Standard Schema-compatible come Zod, Yup, Valibot e altre.

Middleware componibili

Per gestire responsabilità trasversali come auth, logging e policy.

Chainable API

Con metodi come .input(), .output() e .use() puoi costruire operazioni in modo fluido e leggibile.

☑️​ Validazione input/output

Uno dei punti che ci interessavano di più era rendere la validazione parte naturale della definizione delle operazioni.

Esempio:

jsx

Questo permette di ottenere due vantaggi:

• sicurezza a compile time, grazie all’inferenza dei tipi
• sicurezza a runtime, grazie alla validazione effettiva dei dati

In altre parole: non solo scrivi codice più comodo da usare, ma riduci anche il rischio di farti passare sotto il radar dati inconsistenti.

🔗​ Middleware: quando il problema non è il singolo endpoint

Un altro tema ricorrente nei progetti reali è la gestione delle concern trasversali.

Per esempio:

• autenticazione
• logging
• arricchimento del context
• feature flag
• validazioni custom
• gestione errori

Con i middleware puoi comporre questi comportamenti senza incastrarli dentro ogni singola query o mutation.

Esempio:

jsx

L’obiettivo qui non è aggiungere magia.

È rendere più esplicito e riusabile ciò che altrimenti finisce duplicato in giro per la codebase.

📌​ Quando ha senso usare ddmushi

ddmushi può essere utile soprattutto in questi casi:

• usi già TanStack React Query
• lavori con API REST esistenti
• vuoi più struttura senza cambiare backend
• ti serve validazione input/output integrata
• vuoi una DX più ordinata e modulare
• il progetto ha iniziato a crescere e senti che la gestione API sta diventando dispersiva

Non è pensata per forzare un paradigma ovunque.

È pensata per essere utile dove la complessità inizia a farsi sentire.

🔬​Un esperimento interno diventato open-source

ddmushi nasce come esperimento interno.

L’abbiamo costruita per risolvere problemi che abbiamo incontrato davvero lavorando su progetti reali, e abbiamo deciso di renderla open-source perché pensiamo possa essere utile anche ad altri team che si trovano nella stessa situazione.

Non è una libreria nata per “inventare una nuova moda”.

È nata da un’esigenza pratica:

organizzare meglio le API lato frontend, senza perdere type-safety, ordine e developer experience.

⭐​ Se ti è utile, aiutaci a farla crescere

Se trovi ddmushi interessante o utile:

• aggiungi una stella al repository
• provala nei tuoi progetti
• apri una PR se hai idee per migliorarla
• entra nel Discord di Arkemis e parliamone nel canale #open-source

Ci interessa raccogliere feedback veri, capire dove può migliorare e confrontarci con chi affronta problemi simili.

Conclusione

Molte librerie nascono da un’idea.

Quelle più utili, di solito, nascono da un fastidio ripetuto.

ddmushi nasce esattamente da lì: dal bisogno di gestire API, validazione, context e React Query in modo più ordinato, leggibile e scalabile.

Se anche tu hai sentito il peso di una gestione API troppo sparsa, troppo implicita o troppo difficile da mantenere nel tempo, magari questa libreria può esserti utile.

👉​ E se vuoi contribuire a migliorarla: https://github.com/arkemis-labs/ddmushi