Ricerca statica fulminea: integrare Pagefind in Astro su Cloudflare

L’architettura Jamstack ha rivoluzionato il modo in cui costruiamo il web, eliminando i colli di bottiglia legati a database e server lenti. Grazie a framework come Astro, possiamo distribuire HTML pre-renderizzato e ultra-veloce direttamente dall’Edge tramite Cloudflare.

Tuttavia, c’è una funzionalità che storicamente mette in crisi i siti puramente statici: la ricerca interna.

Senza un database da interrogare (come MySQL in WordPress) e senza affidarsi a servizi SaaS esterni costosi e pesanti, come possiamo cercare un termine tra decine di articoli? La risposta ingegneristica per l’ecosistema statico si chiama Pagefind.

Cos’è Pagefind e perché cambia le regole

Pagefind è una libreria di ricerca open-source scritta in Rust. Il suo approccio è radicalmente diverso rispetto ai tradizionali motori di ricerca: non lavora “on-demand” su un server.

Il processo avviene durante la fase di build (eseguendo npm run build). In questa fase, Pagefind scansiona tutto l’HTML finale generato da Astro, indicizza i contenuti e costruisce un indice di ricerca altamente compresso, suddividendolo in microscopici frammenti (chunk). Quando l’utente esegue una ricerca in produzione, il browser scarica solo il frammento di dati rilevante per quella parola chiave. Il risultato è una ricerca istantanea e a latenza zero.

1. Installazione e Configurazione in Astro

Si inizia installando il pacchetto:

npm install astro-pagefind

Integrazione realizzata da shishkin

Nel file astro.config.mjs, l’integrazione convive perfettamente con l’adapter per Cloudflare. È fondamentale mantenere l’output su ‘static’ affinché il binario Rust possa scansionare i file generati:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import pagefind from "astro-pagefind";

export default defineConfig({
  output: 'static',
  adapter: cloudflare(),
  integrations: [pagefind()],
});

2. Guidare l’Indicizzazione: data-pagefind-body e ignore

L’aspetto più potente di Pagefind è il controllo granulare sull’indicizzazione tramite attributi HTML. In un’architettura rigorosa, è vitale evitare l’inquinamento dell’indice con testi ripetitivi.

<main data-pagefind-body >
  <!-- Contenuto -->
</main>

<div data-pagefind-ignore >
  <!-- Contenuto ignorato -->
</div>

3. Implementare la UI di Ricerca

Per esporre il motore all’utente, il pacchetto fornisce i Web Component nativi. L’implementazione pertanto è immediata.

Importiamo il componente ove necessitiamo di mostrare la ricerca (ad esempio ricerca.astro):

---
import PagefindConfig from "astro-pagefind/components/PagefindConfig.astro";
---

<section>
  <PagefindConfig/>
  <pagefind-input></pagefind-input>
  <pagefind-summary></pagefind-summary>
  <pagefind-results></pagefind-results>
</section>

4. Personalizzare l’interfaccia

Pagefind espone variabili CSS native per sovrascrivere il tema predefinito. Ottienendo un’estetica tecnica e rigorosa:

:root {
  /* Colors */
  --pf-text: #1a1a1a;
  --pf-text-secondary: #666;
  --pf-text-muted: #767676;
  --pf-background: #fff;
  --pf-border: #e0e0e0;
  --pf-border-focus: #999;
  --pf-skeleton: #eee;
  --pf-skeleton-shine: #f5f5f5;
  --pf-hover: #f5f5f5;
  --pf-mark: #1a1a1a;
  --pf-scroll-shadow: rgba(0, 0, 0, 0.08);

  /* Shadows */
  --pf-shadow-sm: 0 2px 8px rgba(0, 0, 0, 0.06);
  --pf-shadow-md: 0 4px 12px rgba(0, 0, 0, 0.1);
  --pf-shadow-lg: 0 16px 48px rgba(0, 0, 0, 0.2);

  /* Error states */
  --pf-error-bg: #fef2f2;
  --pf-error-border: #fecaca;
  --pf-error-text: #dc2626;
  --pf-error-text-secondary: #b91c1c;

  /* Focus ring */
  --pf-outline-focus: #0969da;
  --pf-outline-width: 2px;
  --pf-outline-offset: 2px;

  /* Typography */
  --pf-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;

  /* Sizing */
  --pf-input-height: 36px;
  --pf-input-font-size: 16px; /* Keep at 16px+ to prevent iOS auto-zoom on focus */
  --pf-summary-font-size: 12px;
  --pf-result-title-font-size: 14px;
  --pf-result-excerpt-font-size: 13px;

  /* Results layout */
  --pf-results-display: flex;
  --pf-results-flex-direction: column;
  --pf-results-flex-wrap: nowrap;
  --pf-results-columns: none; /* grid-template-columns value, used when display is grid */
  --pf-results-gap: 8px;

  --pf-border-radius: 6px;
  --pf-image-width: 64px;
  --pf-image-height: 48px;

  /* Icons (SVG data URIs) */
  --pf-icon-search: url("data:image/svg+xml,...");
  --pf-icon-arrow: url("data:image/svg+xml,...");

  /* Modal */
  --pf-modal-backdrop: rgba(0, 0, 0, 0.5);
  --pf-modal-max-width: 560px;
  --pf-modal-max-height: min(80dvh, 800px);
  --pf-modal-top: 10dvh;

  /* Searchbox dimensions */
  --pf-searchbox-max-width: 480px;
  --pf-searchbox-dropdown-max-height: 320px;

  /* Dropdown settings */
  --pf-dropdown-max-height: 280px;
  --pf-dropdown-z-index: 9999;
}

5. L’Avvertenza sull’Ambiente di Sviluppo

Poiché Pagefind agisce sui file HTML dopo la generazione, la ricerca non funzionerà con il classico comando npm run dev. Per testare il motore in locale, è necessario compilare il progetto e servire l’anteprima:

npm run build
npm run preview

Implementare questo stack significa liberarsi da dipendenze esterne, azzerare i costi mensili per le API di ricerca e garantire un’esperienza utente senza attriti.