Home / Frontend / Biblioteca personal en un Pod Solid con React y Vite
Biblioteca personal en un Pod Solid con React y Vite

Biblioteca personal en un Pod Solid con React y Vite

22 November 2026 · 20 min de lectura ··

Una aplicación que no se queda con tus datos

La mayoría de las aplicaciones web guardan la información del usuario en una base de datos propia. Si cambias de servicio, empiezas de cero; si el servicio cierra, pierdes todo. Solid, el proyecto impulsado por Tim Berners-Lee, plantea lo contrario: el usuario tiene un Pod, un espacio de almacenamiento personal en un servidor que él elige, y las aplicaciones piden permiso para leer y escribir ahí. El código de la app y los datos del usuario viven en sitios distintos.

En este tutorial construiremos una biblioteca personal, es decir, una lista de lecturas donde apuntas libros pendientes, los marcas como terminados y los eliminas. Es una aplicación de React 19 creada con Vite, que se autentica con el protocolo OIDC contra un proveedor de identidad Solid y guarda cada libro como un recurso RDF dentro del Pod. Si todavía no dominas React, conviene repasar antes la hoja de ruta para aprender React desde cero hasta avanzado, porque aquí damos por sentados componentes, estado y efectos.

Aclaración importante para evitar confusiones: este Solid no tiene relación con SolidJS, el framework reactivo de interfaces. Aquí hablamos de la especificación de Pods descentralizados, con identidades WebID, datos enlazados y control de acceso.

Al terminar tendrás una aplicación que:

  • Inicia y cierra sesión con un proveedor Solid, y recupera la sesión al recargar.
  • Descubre automáticamente la dirección del Pod del usuario a partir de su WebID.
  • Crea un conjunto de datos de lecturas si no existe.
  • Añade, lista, completa y borra libros usando vocabulario estándar de schema.org.
  • Maneja errores de red y de permisos de forma razonable.

Qué necesitas y qué versiones usar

Los ecosistemas de JavaScript cambian rápido, así que conviene fijar el punto de partida. Al redactar esto, la rama estable de React es la 19 y la herramienta recomendada para arrancar proyectos es Vite en su versión 8, que exige Node.js 20.19 o superior, o 22.12 o superior. Create React App está abandonado y la propia documentación de React ya no lo recomienda, de modo que no lo usaremos. Para el lado de Solid usaremos dos paquetes de Inrupt: la librería de autenticación para navegador, en su serie 3.x, y la librería de lectura y escritura de datos, @inrupt/solid-client.

Hay un detalle que cambia el enfoque respecto a tutoriales antiguos. Los componentes de interfaz de Inrupt para React (@inrupt/solid-ui-react) están en un repositorio archivado y marcados como obsoletos, así que no construiremos sobre ellos. En su lugar escribiremos nuestro propio hook de sesión y nuestras funciones de datos; son pocas líneas y no dependen de una capa que ya no recibe mantenimiento. Antes de fijar versiones en tu proyecto, comprueba las vigentes con npm view nombre-del-paquete version; no copies números de ningún texto, incluido este.

Además de Node.js necesitas:

  • Un editor de código y un navegador moderno.
  • Un Pod. Puedes crear uno gratuito en un proveedor público de Solid durante el registro; guarda tu usuario y contraseña, porque se usarán para iniciar sesión.
  • Conocimientos básicos de promesas, async y await.

Anota también la dirección del emisor (issuer) de tu proveedor, la que aparece al iniciar sesión en su página; la necesitaremos al conectar la aplicación.

Crear el proyecto con Vite

Genera el esqueleto con la plantilla de React y instala las dependencias:

npm create vite@latest biblioteca-solid -- --template react
cd biblioteca-solid
npm install
npm install @inrupt/solid-client @inrupt/solid-client-authn-browser

Arranca el servidor de desarrollo para comprobar que todo funciona:

npm run dev
  VITE ready in 410 ms

  ➜  Local:   http://localhost:5173/

Vite sirve la aplicación en el puerto 5173. Ese origen exacto importa, porque el flujo OIDC redirige al usuario de vuelta a una dirección concreta y los proveedores Solid comparan esa dirección con la que registró la aplicación. Si cambias de puerto, cambia también la dirección de redirección en el código.

Vamos a organizar el código así:

biblioteca-solid/
├── index.html
├── package.json
├── vite.config.js
└── src/
    ├── main.jsx
    ├── App.jsx
    ├── solid/
    │   ├── sesion.js
    │   └── lecturas.js
    └── componentes/
        ├── FormularioLogin.jsx
        ├── AnadirLibro.jsx
        └── ListaLibros.jsx

La carpeta solid/ contiene todo lo que habla con el Pod, sin nada de interfaz. Los componentes solo consumen esas funciones. Esta separación facilita las pruebas y hace que un cambio de librería afecte a pocos archivos.

Cómo funciona la identidad en Solid

Antes de escribir código conviene entender tres piezas, porque los errores más frecuentes nacen de confundirlas.

La primera es el WebID: una dirección web que identifica a una persona, por ejemplo una dirección de perfil dentro de su Pod. Al abrir esa dirección se obtiene un documento RDF con datos del perfil, entre ellos la ubicación del almacenamiento. El WebID es tu identidad, no un nombre de usuario en un servidor concreto.

La segunda es el proveedor de identidad. Es el servidor OIDC que comprueba tu contraseña y emite los tokens. La aplicación nunca ve tu contraseña: te redirige al proveedor, tú te identificas allí y regresas con un código que la librería canjea por tokens. Con esto, el usuario elige dónde autenticarse, sin que la app dependa de un único proveedor.

La tercera es el Pod, el almacenamiento propiamente dicho, organizado en contenedores (similares a carpetas) y recursos. Cada recurso tiene una dirección y una lista de control de acceso que decide quién lo lee o lo modifica.

El flujo completo de nuestra app será este: el usuario escribe el emisor de su proveedor, pulsamos iniciar sesión, el navegador viaja al proveedor y vuelve a nuestra dirección de redirección, la librería completa el intercambio y entonces tenemos una función fetch autenticada que añade las credenciales a cada petición hacia el Pod.

El hook de sesión

Creamos src/solid/sesion.js. Aquí viven el inicio de sesión, el cierre y el procesamiento de la redirección entrante.

import { useEffect, useState } from "react";
import {
  getDefaultSession,
  handleIncomingRedirect,
  login,
  logout,
} from "@inrupt/solid-client-authn-browser";

// Se ejecuta una sola vez al cargar el módulo, aunque React
// monte los componentes dos veces en modo estricto.
const sesionInicial = handleIncomingRedirect({
  restorePreviousSession: true,
});

export function useSesionSolid() {
  const [estado, setEstado] = useState({
    cargando: true,
    conectado: false,
    webId: null,
  });

  useEffect(() => {
    let activo = true;
    sesionInicial
      .then((info) => {
        if (!activo) return;
        setEstado({
          cargando: false,
          conectado: Boolean(info?.isLoggedIn),
          webId: info?.webId ?? null,
        });
      })
      .catch(() => {
        if (activo) setEstado({ cargando: false, conectado: false, webId: null });
      });
    return () => {
      activo = false;
    };
  }, []);

  const entrar = (emisor) =>
    login({
      oidcIssuer: emisor,
      redirectUrl: window.location.origin + "/",
      clientName: "Biblioteca personal",
    });

  const salir = async () => {
    await logout();
    setEstado({ cargando: false, conectado: false, webId: null });
  };

  return { ...estado, entrar, salir };
}

export const fetchAutenticado = (...args) => getDefaultSession().fetch(...args);

Hay varias decisiones de diseño en estas líneas. La llamada a handleIncomingRedirect está fuera del hook a propósito. Esa función procesa los parámetros de la dirección tras volver del proveedor y el código de autorización solo puede canjearse una vez; si la ejecutaras dentro de un efecto en modo estricto, se invocaría dos veces en desarrollo y la segunda fallaría. Al guardar la promesa a nivel de módulo, todos los componentes esperan el mismo resultado.

La opción restorePreviousSession pide a la librería que intente recuperar la sesión anterior de forma silenciosa. Gracias a ella, recargar la página no obliga a volver a autenticarse, siempre que el proveedor mantenga su propia sesión.

Con login indicamos el emisor, la dirección de redirección y un nombre de cliente que el proveedor mostrará en la pantalla de consentimiento. Esta función no devuelve control útil: navega a otra página, por eso no esperamos nada tras ella.

Por último, exportamos fetchAutenticado, un envoltorio sobre el fetch de la sesión por defecto. Cualquier petición hecha con él lleva las credenciales de la sesión actual; una petición hecha con el fetch global del navegador iría anónima y recibiría errores 401 o 403 en recursos privados.

Punto de entrada y pantalla de acceso

El archivo src/main.jsx apenas cambia respecto a la plantilla:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.jsx";
import "./index.css";

createRoot(document.getElementById("root")).render(
  <StrictMode>
    <App />
  </StrictMode>
);

Ahora el formulario de acceso en src/componentes/FormularioLogin.jsx. Ofrecemos un campo con un valor por defecto editable, porque cada persona puede tener un proveedor distinto:

import { useState } from "react";

export default function FormularioLogin({ onEntrar }) {
  const [emisor, setEmisor] = useState("");
  const [error, setError] = useState("");

  const enviar = async (evento) => {
    evento.preventDefault();
    setError("");
    try {
      new URL(emisor);
    } catch {
      setError("Escribe una dirección válida, incluido el protocolo.");
      return;
    }
    try {
      await onEntrar(emisor);
    } catch (e) {
      setError("No se pudo iniciar la sesión: " + e.message);
    }
  };

  return (
    <form onSubmit={enviar}>
      <label htmlFor="emisor">Proveedor de identidad</label>
      <input
        id="emisor"
        value={emisor}
        onChange={(e) => setEmisor(e.target.value)}
        placeholder="Dirección del emisor de tu Pod"
      />
      <button type="submit">Iniciar sesión</button>
      {error && <p role="alert">{error}</p>}
    </form>
  );
}

Validar con new URL evita enviar al proveedor valores absurdos y da un mensaje claro. Fíjate en que el texto de ejemplo del campo no incluye ninguna dirección real; cada lector debe usar la de su propio proveedor.

Modelar una lectura como datos RDF

Solid almacena información como grafos RDF, en los que cada dato es una tripleta: sujeto, predicado y objeto. Un libro será un sujeto con varios predicados. En vez de inventar nombres de campos, reutilizamos el vocabulario de schema.org, que otras aplicaciones también entienden, y esa interoperabilidad es la gracia de los datos enlazados.

Nuestro modelo, expresado en formato Turtle, tiene este aspecto:

@prefix schema: <https://schema.org/> .
@prefix : <#> .

:a1b2c3 a schema:Book ;
    schema:name "Estructuras de datos funcionales" ;
    schema:author "Chris Okasaki" ;
    schema:dateCreated "2026-11-22T00:57:20Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

Un libro terminado añade un predicado más, la fecha de fin de lectura:

:a1b2c3 schema:endDate "2026-12-10T18:00:00Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .

Elegimos representar el estado por la presencia o ausencia de la fecha de fin, en lugar de un booleano. Así guardamos más información (cuándo terminaste) con el mismo esfuerzo, y un libro pendiente simplemente no tiene ese predicado. Todos los libros viven en un único documento, lecturas/biblioteca.ttl, dentro del almacenamiento del Pod. En la jerga de la librería, ese documento es un dataset y cada libro es un Thing dentro de él.

Las funciones de datos

Escribimos src/solid/lecturas.js. Empezamos con las constantes del vocabulario y las funciones de descubrimiento:

import {
  buildThing,
  createSolidDataset,
  createThing,
  getDatetime,
  getPodUrlAll,
  getSolidDataset,
  getStringNoLocale,
  getThing,
  getThingAll,
  getUrlAll,
  removeThing,
  saveSolidDatasetAt,
  setThing,
} from "@inrupt/solid-client";
import { fetchAutenticado } from "./sesion.js";

const RDF_TIPO = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type";
const LIBRO = "https://schema.org/Book";
const TITULO = "https://schema.org/name";
const AUTOR = "https://schema.org/author";
const CREADO = "https://schema.org/dateCreated";
const TERMINADO = "https://schema.org/endDate";

const opciones = { fetch: fetchAutenticado };

export async function localizarBiblioteca(webId) {
  const pods = await getPodUrlAll(webId, opciones);
  if (pods.length === 0) {
    throw new Error("Tu perfil no declara ningún almacenamiento.");
  }
  const raiz = pods[0].endsWith("/") ? pods[0] : pods[0] + "/";
  return raiz + "lecturas/biblioteca.ttl";
}

La función getPodUrlAll lee el perfil del WebID y devuelve las direcciones de almacenamiento declaradas. Un usuario puede tener varios Pods, por simplicidad tomamos el primero, y normalizamos la barra final para construir la dirección del documento. Nunca debes fijar la ruta del Pod a mano: cada proveedor organiza las direcciones a su manera.

Ahora la función que lee el dataset o lo crea si no existe:

export async function cargarOCrearBiblioteca(direccion) {
  try {
    return await getSolidDataset(direccion, opciones);
  } catch (error) {
    if (error.statusCode === 404) {
      return saveSolidDatasetAt(direccion, createSolidDataset(), opciones);
    }
    throw error;
  }
}

Un 404 significa que el documento todavía no existe, y en ese caso lo guardamos vacío. Cualquier otro fallo, como un 401 o un 403, se propaga hacia arriba para que la interfaz lo muestre. Los servidores compatibles con Solid crean los contenedores intermedios al escribir un recurso nuevo, así que no necesitamos crear lecturas/ por separado.

Para pasar de Things a objetos de JavaScript manejables, escribimos un traductor:

export function listarLibros(dataset) {
  return getThingAll(dataset)
    .filter((cosa) => getUrlAll(cosa, RDF_TIPO).includes(LIBRO))
    .map((cosa) => ({
      id: cosa.url,
      titulo: getStringNoLocale(cosa, TITULO) ?? "(sin título)",
      autor: getStringNoLocale(cosa, AUTOR) ?? "Autor desconocido",
      creado: getDatetime(cosa, CREADO),
      terminado: getDatetime(cosa, TERMINADO),
    }))
    .sort((a, b) => (b.creado?.getTime() ?? 0) - (a.creado?.getTime() ?? 0));
}

El filtro por tipo es una buena práctica: un documento RDF puede contener otros sujetos (metadatos del servidor, por ejemplo) y no queremos mostrarlos como libros. Los valores ausentes se sustituyen por textos por defecto, porque en datos enlazados cualquier predicado puede faltar y otra aplicación pudo haber escrito en el mismo documento.

Las operaciones de escritura siguen el mismo patrón: construir o modificar un Thing, insertarlo en el dataset y guardar el dataset completo.

export async function anadirLibro(direccion, dataset, titulo, autor) {
  const libro = buildThing(createThing({ name: crypto.randomUUID() }))
    .addUrl(RDF_TIPO, LIBRO)
    .addStringNoLocale(TITULO, titulo)
    .addStringNoLocale(AUTOR, autor)
    .addDatetime(CREADO, new Date())
    .build();
  return saveSolidDatasetAt(direccion, setThing(dataset, libro), opciones);
}

export async function alternarTerminado(direccion, dataset, id) {
  const actual = getThing(dataset, id);
  if (!actual) throw new Error("El libro ya no existe.");
  const constructor = buildThing(actual);
  if (getDatetime(actual, TERMINADO)) {
    constructor.removeAll(TERMINADO);
  } else {
    constructor.addDatetime(TERMINADO, new Date());
  }
  return saveSolidDatasetAt(direccion, setThing(dataset, constructor.build()), opciones);
}

export async function borrarLibro(direccion, dataset, id) {
  const actual = getThing(dataset, id);
  if (!actual) return dataset;
  return saveSolidDatasetAt(direccion, removeThing(dataset, actual), opciones);
}

Un punto sutil: los datasets de la librería son inmutables. setThing y removeThing devuelven una copia nueva, y saveSolidDatasetAt devuelve el dataset tal como quedó guardado, ya con la información del servidor. Por eso cada función devuelve el resultado, y la interfaz sustituye su estado por él. Es el mismo principio de inmutabilidad que React espera en su estado.

Como createThing({ name }) genera una dirección con fragmento dentro del propio documento, un identificador aleatorio garantiza que dos libros nunca colisionen aunque tengan el mismo título.

Componentes de la lista

El formulario para añadir libros, en src/componentes/AnadirLibro.jsx:

import { useState } from "react";

export default function AnadirLibro({ onAnadir, ocupado }) {
  const [titulo, setTitulo] = useState("");
  const [autor, setAutor] = useState("");

  const enviar = async (evento) => {
    evento.preventDefault();
    if (!titulo.trim()) return;
    await onAnadir(titulo.trim(), autor.trim() || "Autor desconocido");
    setTitulo("");
    setAutor("");
  };

  return (
    <form onSubmit={enviar}>
      <input
        value={titulo}
        onChange={(e) => setTitulo(e.target.value)}
        placeholder="Título"
        aria-label="Título del libro"
      />
      <input
        value={autor}
        onChange={(e) => setAutor(e.target.value)}
        placeholder="Autor"
        aria-label="Autor del libro"
      />
      <button type="submit" disabled={ocupado}>
        Añadir
      </button>
    </form>
  );
}

Y la tabla de libros en src/componentes/ListaLibros.jsx:

const formatoFecha = new Intl.DateTimeFormat("es", { dateStyle: "medium" });

export default function ListaLibros({ libros, onAlternar, onBorrar, ocupado }) {
  if (libros.length === 0) {
    return <p>Tu biblioteca está vacía. Añade tu primera lectura.</p>;
  }

  return (
    <table>
      <thead>
        <tr>
          <th>Terminado</th>
          <th>Título</th>
          <th>Autor</th>
          <th>Añadido</th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        {libros.map((libro) => (
          <tr key={libro.id}>
            <td>
              <input
                type="checkbox"
                checked={Boolean(libro.terminado)}
                disabled={ocupado}
                onChange={() => onAlternar(libro.id)}
                aria-label={"Marcar " + libro.titulo + " como terminado"}
              />
            </td>
            <td>{libro.titulo}</td>
            <td>{libro.autor}</td>
            <td>{libro.creado ? formatoFecha.format(libro.creado) : "-"}</td>
            <td>
              <button disabled={ocupado} onClick={() => onBorrar(libro.id)}>
                Borrar
              </button>
            </td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

La clave de cada fila es la dirección del Thing, estable y única. Las etiquetas accesibles en casillas y campos permiten que lectores de pantalla los anuncien correctamente, un detalle barato que merece la pena. Si tu biblioteca crece mucho, puedes mostrar los libros por tramos con una técnica como la de la paginación incremental con un botón de cargar más en React, ya que el dataset completo se descarga de una vez pero la interfaz no tiene por qué pintarlo todo.

Unir todo en el componente principal

src/App.jsx coordina sesión, carga inicial y acciones. Nótese cómo mantenemos tres estados: el dataset, un indicador de operación en curso y un mensaje de error.

import { useCallback, useEffect, useState } from "react";
import { useSesionSolid } from "./solid/sesion.js";
import {
  alternarTerminado,
  anadirLibro,
  borrarLibro,
  cargarOCrearBiblioteca,
  listarLibros,
  localizarBiblioteca,
} from "./solid/lecturas.js";
import FormularioLogin from "./componentes/FormularioLogin.jsx";
import AnadirLibro from "./componentes/AnadirLibro.jsx";
import ListaLibros from "./componentes/ListaLibros.jsx";

export default function App() {
  const { cargando, conectado, webId, entrar, salir } = useSesionSolid();
  const [direccion, setDireccion] = useState(null);
  const [dataset, setDataset] = useState(null);
  const [ocupado, setOcupado] = useState(false);
  const [error, setError] = useState("");

  useEffect(() => {
    if (!conectado) return;
    let activo = true;
    (async () => {
      try {
        setOcupado(true);
        const url = await localizarBiblioteca(webId);
        const datos = await cargarOCrearBiblioteca(url);
        if (!activo) return;
        setDireccion(url);
        setDataset(datos);
      } catch (e) {
        if (activo) setError(e.message);
      } finally {
        if (activo) setOcupado(false);
      }
    })();
    return () => {
      activo = false;
    };
  }, [conectado, webId]);

  const ejecutar = useCallback(async (operacion) => {
    setError("");
    setOcupado(true);
    try {
      setDataset(await operacion());
    } catch (e) {
      setError("La operación falló: " + e.message);
    } finally {
      setOcupado(false);
    }
  }, []);

  if (cargando) return <p>Comprobando sesión...</p>;
  if (!conectado) return <FormularioLogin onEntrar={entrar} />;

  const libros = dataset ? listarLibros(dataset) : [];

  return (
    <main>
      <header>
        <h1>Mi biblioteca</h1>
        <p>Sesión iniciada como {webId}</p>
        <button onClick={salir}>Cerrar sesión</button>
      </header>
      {error && <p role="alert">{error}</p>}
      <AnadirLibro
        ocupado={ocupado || !dataset}
        onAnadir={(titulo, autor) =>
          ejecutar(() => anadirLibro(direccion, dataset, titulo, autor))
        }
      />
      <ListaLibros
        libros={libros}
        ocupado={ocupado}
        onAlternar={(id) => ejecutar(() => alternarTerminado(direccion, dataset, id))}
        onBorrar={(id) => ejecutar(() => borrarLibro(direccion, dataset, id))}
      />
    </main>
  );
}

El flujo es lineal: al detectar sesión, localizamos el documento y lo cargamos; después, cada acción ejecuta una función de datos y reemplaza el dataset con el devuelto. La bandera activo del efecto evita actualizar estado tras desmontar el componente o si cambia el WebID mientras la petición vuela. Para que el estado refleje el Pod en todo momento, no modificamos nunca el dataset a mano: siempre usamos el resultado que devuelve el servidor tras guardar.

Probar la aplicación

Con el servidor en marcha, abre la dirección local, escribe el emisor de tu proveedor y pulsa iniciar sesión. Verás la pantalla del proveedor, te identificas y apruebas el acceso. Al volver, la aplicación mostrará tu WebID y una biblioteca vacía. Añade un par de libros, marca uno como terminado, recarga la página y comprueba que todo persiste y que la sesión se restaura sin pedirte nada.

Para confirmar que los datos están realmente en tu Pod y no en la memoria del navegador, abre el panel de red de las herramientas de desarrollo y observa las peticiones. Deberías ver una lectura inicial y, tras cada acción, una escritura hacia el documento de lecturas:

GET   .../lecturas/biblioteca.ttl   404
PUT   .../lecturas/biblioteca.ttl   201
PATCH .../lecturas/biblioteca.ttl   205

La primera ejecución produce el 404 de lectura seguido de la creación; después, las escrituras son parches que añaden o quitan tripletas. Los códigos exactos pueden variar según el servidor. También puedes abrir el panel de tu proveedor o un explorador de Pods y ver el archivo Turtle con los libros que escribiste. Esa es la prueba más clara de la idea de Solid: puedes leer, copiar o borrar tus datos sin pasar por nuestra aplicación.

Permisos y privacidad

Por defecto, los recursos que crea la aplicación en tu Pod son privados: solo tú, autenticado, puedes leerlos. Ese comportamiento seguro por defecto es una de las ventajas del modelo, pero hay matices que debes entender.

El control de acceso se gestiona por recurso o por contenedor mediante ACL (listas de control de acceso) o ACP (políticas de control de acceso), según qué mecanismo implemente tu servidor. Si quisieras compartir tu lista con un amigo, no tocarías la base de datos de la app: darías permiso de lectura sobre el documento a su WebID desde el panel del proveedor o con las utilidades de acceso de @inrupt/solid-client. Con permisos concedidos recurso por recurso, puedes publicar la lista de lecturas sin exponer nada más de tu Pod.

Otras consideraciones de seguridad:

  • La librería almacena el estado de sesión en el navegador; no guardes tokens por tu cuenta ni los muestres en consola.
  • Pide siempre los mínimos privilegios. Nuestra app solo necesita acceder a un documento, y el consentimiento del usuario debe reflejarlo.
  • Valida y escapa lo que muestras. React escapa el texto en JSX por defecto, pero un título malicioso escrito por otra aplicación en tu documento nunca debe insertarse como HTML sin sanear.
  • No fijes la dirección del proveedor en el código si quieres soportar a cualquier usuario; es tu elección de producto, pero explícala.

Errores comunes y cómo resolverlos

Al trabajar con Solid por primera vez suelen aparecer los mismos problemas. Repasarlos te ahorrará horas.

El primero es la redirección que falla con un error del proveedor. Casi siempre se debe a una discrepancia entre la dirección de redirección enviada y la que el proveedor espera, por ejemplo localhost frente a 127.0.0.1, o un puerto distinto. Usa siempre el mismo origen en el navegador y en el código.

El segundo son los errores 401 y 403 al leer el documento. Un 401 indica que la petición llegó sin credenciales: seguramente usaste el fetch global en lugar del autenticado. Un 403 indica que estás autenticado, pero sin permiso sobre ese recurso; comprueba que el documento está dentro de tu propio Pod y que no lo creó otra identidad.

El tercero es el doble intercambio en desarrollo. Si ves un error de estado no válido tras volver del proveedor, revisa que handleIncomingRedirect se llame una sola vez, como hicimos a nivel de módulo, y que no la repitas en un efecto.

El cuarto son los fallos de CORS. Los servidores Solid deben permitir el origen de tu aplicación; los proveedores públicos suelen hacerlo, pero un servidor propio o mal configurado puede rechazar las peticiones. El síntoma es un error de red sin código de estado.

El quinto es la lista vacía tras recargar. Si la sesión no se restaura, la app mostrará el formulario de acceso y parecerá que perdiste datos, pero siguen en el Pod. Verifica que usaste la opción de restauración y que el navegador no bloquea las cookies de terceros del proveedor.

Un último caso es el conflicto por escrituras concurrentes. Si abres la aplicación en dos pestañas y modificas ambas, la segunda escritura parte de un dataset antiguo. La librería envía parches calculados contra el estado que conoce, de manera que los cambios simples suelen fusionarse bien, pero conviene recargar el dataset antes de operaciones críticas si esperas varias pestañas abiertas.

Mejoras de rendimiento y experiencia de uso

Nuestra versión espera la respuesta del servidor antes de actualizar la pantalla. Es correcta y sencilla, pero cada clic tiene la latencia de una petición de red. Puedes mejorar la sensación de velocidad con actualizaciones optimistas: modificas el estado local al instante y revertirlo si la escritura falla. Implementarlo exige conservar el dataset anterior para el retroceso, y por eso lo dejamos como ejercicio.

Otras ideas útiles:

  • Divide los libros en varios documentos, por año de lectura, cuando la biblioteca crezca. Descargar un archivo enorme para cambiar una casilla es ineficiente.
  • Guarda una copia local de solo lectura para ver datos sin conexión y sincroniza al recuperar la red.
  • Usa React.memo o separa filas en un componente propio si la tabla tiene cientos de elementos; la mayor parte del coste está en la red, aun así no conviene volver a pintar todo en cada cambio.
  • Muestra estados intermedios claros: un texto de carga, botones deshabilitados durante las escrituras y mensajes de error cerca de la acción que falló.
  • Añade pruebas con Vitest para las funciones de lecturas.js, sustituyendo el fetch por una función simulada que devuelva respuestas Turtle de ejemplo.

Para pruebas automáticas ten presente que la autenticación real exige un navegador y un proveedor, de modo que lo habitual es aislar la capa de datos recibiendo el fetch como parámetro. En nuestro código usamos una importación directa por brevedad; si quieres probar de verdad, cambia las funciones para que reciban las opciones como argumento.

Alternativas y cuándo elegir Solid

Solid no es la solución para todo. Conviene comparar con otras opciones antes de decidirte.

Con una base de datos tradicional en un backend propio, tienes control total y rendimiento predecible, pero tú custodias los datos y eres responsable de su protección y de las normativas de privacidad. Con servicios de backend como servicio ganas rapidez de desarrollo, a cambio de depender de un proveedor. Con almacenamiento local en el navegador no hay servidor, pero tampoco sincronización entre dispositivos ni copias de seguridad.

Solid brilla cuando el usuario debe ser dueño de su información: historiales personales, notas, listas, perfiles portables o datos sanitarios compartidos de forma selectiva. Sus limitaciones también son reales: las consultas son menos potentes que en SQL, el ecosistema es más pequeño, el rendimiento depende del servidor que elija cada persona y los componentes de React oficiales ya no se mantienen, como vimos. Para una aplicación con millones de registros compartidos entre usuarios, probablemente necesitarás una arquitectura complementaria.

Si te interesa seguir adelante, explora los consultores de datos más avanzados, la gestión de permisos desde código y los vocabularios compartidos para que tus datos se entiendan con otras aplicaciones.

Conclusiones

Hemos construido una biblioteca personal con React 19 y Vite cuyos datos residen en un Pod Solid y no en un servidor nuestro. El camino fue claro: un hook que gestiona la sesión OIDC y la restauración, una capa de funciones que descubre el almacenamiento a partir del WebID y lee o escribe un dataset RDF, y unos componentes que se limitan a pintar y delegar.

Lo esencial para recordar es que la identidad, la autenticación y el almacenamiento están desacoplados de la aplicación; que todas las peticiones al Pod deben usar el fetch autenticado de la sesión; que los datasets son inmutables y cada escritura devuelve uno nuevo; y que reutilizar vocabularios como schema.org hace tus datos reutilizables por otras aplicaciones.

Desde aquí puedes añadir puntuaciones, notas por libro, compartición con amigos mediante permisos de lectura, actualizaciones optimistas y pruebas automáticas. Y recuerda comprobar las versiones vigentes de cada paquete antes de empezar, porque este ecosistema evoluciona con rapidez.