Come velocizzare la build MDX con Rust e Sätteri

Se hai mai creato una documentazione di grandi dimensioni o un blog con Astro, Next.js o Vite, probabilmente hai riscontrato problemi di velocità di build. Sembra che tu abbia appena aggiunto qualche decina di file con codice e grafica, e improvvisamente il tuo progetto impiega quaranta secondi per essere compilato invece di cinque.

Il colpevole è quasi sempre lo stesso: la catena tradizionale di unified, remark e rehype. Questi sono strumenti eccellenti con migliaia di plugin già pronti, ma vengono eseguiti interamente in JavaScript single-threaded. Quando devi analizzare un sacco di file .mdx pesanti, scomporli in alberi AST, applicare trasformazioni e riassemblarli, Node.js raggiunge rapidamente i suoi limiti.

Gli sviluppatori del collettivo Bruits hanno deciso di affrontare il problema in modo pragmatico. Hanno creato Sätteri — un parser e compilatore Markdown/MDX in cui tutto il lavoro pesante viene svolto da Rust, mentre gli sviluppatori continuano a usare il familiare JavaScript.

Come funziona questo ibrido

I creatori di Sätteri non hanno riscritto tutto da zero. Invece, hanno preso soluzioni collaudate dalla community e le hanno collegate insieme usando i binding NAPI.

All'interno del monorepo, il progetto è suddiviso in due livelli: crate Rust di basso livello e wrapper per Node.js e Vite.

A livello Rust, vengono utilizzati i seguenti componenti:

• satteri-pulldown-cmark — un fork del popolare parser pulldown-cmark con supporto aggiunto per la sintassi MDX.
• satteri-mdxjs-rs — un fork del compilatore mdxjs-rs, adattato per OXC — un parser JavaScript/TypeScript basato su Rust in rapida crescita.
• satteri-ast — tipi di nodi MDAST e HAST, oltre alle operazioni sugli alberi.
• satteri-napi-binding — uno strato bridge tra C++ / Rust e JavaScript.

Sopra c'è un elegante livello TypeScript. L'idea principale è che non devi imparare Rust o riscrivere i tuoi script di build. Installi un normale pacchetto npm e ci lavori come con qualsiasi altra utility nel tuo file di configurazione.

Interessante è l'approccio all'elaborazione dei plugin. Scrivere un compilatore in Rust è un compito abbastanza diretto. Le vere sfide iniziano quando devi dare agli utenti la possibilità di modificare l'albero AST in JS. In Sätteri, il parsing e l'assemblaggio del codice finale avvengono alla massima velocità all'interno di Rust, mentre le chiamate ai plugin utente in JavaScript avvengono selettivamente attraverso un binding veloce. Gli autori sono stati onestamente ispirati dall'architettura di Lightning CSS, che utilizza un principio simile per i visitor.

Compilare progetti con Vite

Per gli utenti di Vite, gli autori hanno preparato un pacchetto separato vite-plugin-satteri. Trasforma il collegamento dei file .md e .mdx in un paio di righe di configurazione.

import { defineConfig } from 'vite';
import satteri from 'vite-plugin-satteri';

export default defineConfig({
  plugins: [
    satteri({
      // Ваши настройки и плагины
    }),
  ],
});

Il bundle include un plugin satteri-expressive-code per il rendering elegante dei blocchi di codice. Se la tua documentazione contiene molti esempi con evidenziazione della sintassi, questa combinazione sostituisce i soliti plugin Rehype pesanti.

Vantaggi pratici e compromessi

Perché aggiungere un altro strumento al tuo progetto quando hai librerie collaudate da anni?

Prima di tutto, la velocità di build in CI/CD e nello sviluppo locale. Quando hai centinaia di pagine, la differenza tra l'esecuzione delle operazioni su V8 e il codice Rust compilato diventa molto evidente.

In secondo luogo, la praticità della migrazione. Se il tuo progetto ha raggiunto il limite di prestazioni di remark, di solito ti viene offerto di aspettare pazientemente o di riscrivere tutto in Go o Rust. Sätteri fornisce una via di mezzo: il parsing diventa veloce, mentre l'infrastruttura dei plugin JS rimane accessibile.

Ma ci sono delle sfumature. Il progetto è ancora giovane, con poco più di mille stelle su GitHub e 23 issue aperte al momento della scrittura. Questo significa che alcuni casi limite della sintassi MDX o plugin specifici dell'ecosistema potrebbero necessitare di lavoro. Esistono anche limitazioni dei binding JS: se il tuo plugin JS effettua milioni di piccole chiamate all'AST nella memoria Rust, l'overhead di marshalling potrebbe erodere parte dei guadagni di velocità.

Vale la pena provarlo

Sätteri è una scoperta eccellente per chi costruisce grandi siti di contenuto, sistemi di documentazione o generatori di siti statici. Se il tuo progetto Vite o Astro impiega secondi per caricarsi quando modifichi file MDX, lo strumento merita sicuramente un test.

Puoi provare il compilatore in azione senza installazione direttamente nel tuo browser tramite il playground ufficiale sul sito del progetto, oppure unirti alla community Discord degli autori per discutere le funzionalità.

Se stavi cercando un modo per velocizzare la tua build senza riscrivere radicalmente l'intera pipeline in un altro linguaggio, prova a installare satteri ed esegui benchmark sui tuoi file.