API de almacenamiento de JavaScript

Introducción a la Storage API

En el desarrollo web moderno, gestionar datos de manera eficiente es fundamental. La Web Storage API de JavaScript proporciona una forma simple y sincrónica de almacenar pares clave/valor directamente en el navegador, sin necesidad de hacer solicitudes al servidor. Es la herramienta más común para recordar preferencias del usuario, almacenar en caché pequeñas cantidades de datos y mantener el estado de la interfaz entre recargas de página.

Esta guía cubre los dos objetos de almacenamiento que expone la API — localStorage y sessionStorage — junto con el conjunto completo de métodos, cómo almacenar objetos, cómo reaccionar a cambios entre pestañas, y los errores más comunes. Ambos objetos comparten la misma interfaz (la interfaz Storage); la única diferencia es cuánto tiempo viven los datos y qué tan ampliamente se comparten.

Como el Web Storage nunca se envía al servidor, no es adecuado para tokens de autenticación que necesita el backend — para eso están las cookies.

La interfaz Storage

Cada valor en Web Storage es un string. Tanto localStorage como sessionStorage exponen los mismos cinco métodos más una propiedad length:

Los ejemplos a continuación usan localStorage, pero todos los métodos funcionan de manera idéntica en sessionStorage.

Entendiendo localStorage

localStorage almacena datos sin fecha de expiración. Los datos persisten incluso después de cerrar y volver a abrir la ventana del navegador, lo que lo hace ideal para datos de larga duración como preferencias del usuario, la elección de un tema o un formulario en borrador.

Almacenar datos en localStorage

Para almacenar datos, usa el método setItem con una clave y un valor:

// Storing data in localStorage
localStorage.setItem('username', 'JohnDoe');

Ambos argumentos se convierten a strings. Escribir setItem('count', 5) almacena realmente el string "5", así que recuerda convertirlo de vuelta cuando lo leas.

Recuperar datos de localStorage

Usa getItem para leer un valor. Si la clave no existe, obtienes null (no undefined):

// Retrieving data from localStorage
const username = localStorage.getItem('username');
console.log(username);                 // "JohnDoe"
console.log(localStorage.getItem('missing')); // null

Eliminar datos de localStorage

Elimina una sola clave con removeItem, o borra todo para el origen con clear:

// Remove one key
localStorage.removeItem('username');

// Remove every key for this origin
localStorage.clear();

clear() solo afecta el origen actual (esquema + host + puerto); nunca toca los datos de otro sitio.

Almacenar objetos: JSON.stringify y JSON.parse

Dado que los valores de almacenamiento deben ser strings, no puedes almacenar un object directamente — setItem('user', {name: 'Ann'}) almacenaría el string inútil "[object Object]". Serializa con JSON.stringify al guardar y con JSON.parse al recuperar:

const user = { name: 'Ann', theme: 'dark', visits: 3 };

// Save: serialize the object to a JSON string
localStorage.setItem('user', JSON.stringify(user));

// Load: parse the string back into an object
const restored = JSON.parse(localStorage.getItem('user'));
console.log(restored.theme); // "dark"
console.log(restored.visits + 1); // 4

Consulta Trabajar con JSON para más información sobre serialización, y Objetos JavaScript para los fundamentos de los objetos.

Iterar sobre las claves almacenadas

Usa length junto con key(index) para recorrer todo lo almacenado en el origen:

localStorage.setItem('a', '1');
localStorage.setItem('b', '2');

for (let i = 0; i < localStorage.length; i++) {
  const name = localStorage.key(i);
  console.log(`${name} = ${localStorage.getItem(name)}`);
}
// a = 1
// b = 2

Usar sessionStorage

sessionStorage comparte la misma API pero tiene una duración más corta, por pestaña. Los datos se borran cuando termina la sesión de página, es decir, cuando se cierra la pestaña. Abrir el mismo sitio en una segunda pestaña crea un sessionStorage separado, por lo que las dos pestañas nunca ven los datos de la otra. Esto lo hace ideal para datos que no deben filtrarse entre pestañas, como el progreso de un asistente de múltiples pasos.

// Store, read, and remove — same methods as localStorage
sessionStorage.setItem('sessionName', 'Session1');
console.log(sessionStorage.getItem('sessionName')); // "Session1"
sessionStorage.removeItem('sessionName');

Reaccionar a cambios entre pestañas

Cuando localStorage cambia en una pestaña, el navegador dispara un evento storage en todas las demás pestañas del mismo origen (pero no en la pestaña que realizó el cambio). Esto te permite mantener múltiples pestañas sincronizadas — por ejemplo, cerrar sesión del usuario en todas partes a la vez:

window.addEventListener('storage', (event) => {
  // event.key, event.oldValue, event.newValue, event.url
  if (event.key === 'theme') {
    console.log('Theme changed in another tab to', event.newValue);
  }
});

Nota: el evento storage solo se dispara para localStorage (compartido entre pestañas), no para sessionStorage.

Manejo de errores y límites

Las escrituras pueden lanzar un QuotaExceededError cuando superas el límite de ~5 MB, y el almacenamiento puede no estar disponible en modos de navegación privada o cuando las cookies están desactivadas. Envuelve las escrituras en try...catch y detecta la disponibilidad antes de depender de la API:

function safeSet(key, value) {
  try {
    localStorage.setItem(key, value);
    return true;
  } catch (err) {
    // QuotaExceededError, or storage blocked by the browser
    console.warn('Storage write failed:', err.name);
    return false;
  }
}

console.log(safeSet('theme', 'dark')); // true (when storage is available)

Buenas prácticas para usar Web Storage

• Seguridad: Considera siempre las implicaciones de seguridad al almacenar datos sensibles en el navegador. Evita guardar información confidencial como contraseñas o datos de identificación personal.
• Límites de almacenamiento: Ten en cuenta las limitaciones de almacenamiento (generalmente alrededor de 5 MB) y gestiona los casos en que el almacenamiento pueda estar lleno.
• Compatibilidad entre navegadores: Asegúrate de que tu código gestione escenarios en los que un navegador no soporte las Storage APIs.
• Solo strings: Web Storage solo acepta strings. Usa JSON.stringify() para guardar objetos y JSON.parse() para recuperarlos.
• Sincronización entre pestañas: Usa el StorageEvent para escuchar cambios realizados en otras pestañas y mantener los datos sincronizados.

Un ejemplo completo para entenderlo todo

Esta demo muestra cómo usar la Web Storage API, incluyendo tanto localStorage como sessionStorage. Tienes botones para almacenar, recuperar y eliminar datos del almacenamiento:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Storage API Interactive Demo</title>
  </head>
  <body>
    <h2>localStorage and sessionStorage Demo</h2>
    <div style="display: flex; gap: 10px">
      <button onclick="storeInLocal()">Store in localStorage</button>
      <button onclick="retrieveFromLocal()">Retrieve from localStorage</button>
      <button onclick="removeFromLocal()">Remove from localStorage</button>
    </div>

    <div style="margin: 20px 0" id="localStorageResult"></div>

    <div style="display: flex; gap: 10px; margin-top: 10px">
      <button onclick="storeInSession()">Store in sessionStorage</button>
      <button onclick="retrieveFromSession()">
        Retrieve from sessionStorage
      </button>
      <button onclick="removeFromSession()">Remove from sessionStorage</button>
    </div>

    <div style="margin-top: 20px" id="sessionStorageResult"></div>

    <script>
      function storeInLocal() {
        localStorage.setItem("demo", "Hi from LocalStorage!");
        document.getElementById("localStorageResult").textContent =
          "Stored in localStorage: " + localStorage.getItem("demo");
      }

      function retrieveFromLocal() {
        const value = localStorage.getItem("demo") || "Nothing in localStorage";
        document.getElementById("localStorageResult").textContent =
          "Retrieved from localStorage: " + value;
      }

      function removeFromLocal() {
        localStorage.removeItem("demo");
        document.getElementById("localStorageResult").textContent =
          "Item removed from localStorage.";
      }

      function storeInSession() {
        sessionStorage.setItem("demo", "Hi from SessionStorage!");
        document.getElementById("sessionStorageResult").textContent =
          "Stored in sessionStorage: " + sessionStorage.getItem("demo");
      }

      function retrieveFromSession() {
        const value =
          sessionStorage.getItem("demo") || "Nothing in sessionStorage";
        document.getElementById("sessionStorageResult").textContent =
          "Retrieved from sessionStorage: " + value;
      }

      function removeFromSession() {
        sessionStorage.removeItem("demo");
        document.getElementById("sessionStorageResult").textContent =
          "Item removed from sessionStorage.";
      }
    </script>
  </body>
</html>

• LocalStorage: Los datos almacenados aquí permanecen incluso después de cerrar y volver a abrir el navegador, lo que lo hace perfecto para guardar preferencias del usuario u otros datos a largo plazo.
• SessionStorage: Es similar a localStorage, pero los datos se borran cuando termina la sesión (por ejemplo, cuando se cierra el navegador).

Al hacer clic en los distintos botones, puedes ver cómo se agregan, recuperan y eliminan datos de cada tipo de almacenamiento. Los resultados se muestran directamente debajo de cada botón, dándote retroalimentación inmediata sobre lo que ocurre con los datos en el almacenamiento. Esta configuración interactiva te ayuda a visualizar y entender cómo las aplicaciones web pueden recordar datos entre recargas de página o sesiones del navegador.

Además de interactuar con las operaciones de almacenamiento a través de los botones de esta demo, también puedes ver y gestionar los datos almacenados directamente en tu navegador web. Abre las herramientas de desarrollo del navegador, navega a la sección Application y luego busca en la pestaña Storage. Aquí puedes ver las entradas de localStorage y sessionStorage.

Esta herramienta visual te permite ver los efectos de tus acciones (como almacenar y eliminar datos) en tiempo real y proporciona una forma práctica de explorar cómo funciona el almacenamiento web en los navegadores.

Conclusión

La Storage API de JavaScript proporciona un método robusto y fácil de usar para gestionar datos dentro del navegador. Al comprender y aprovechar localStorage y sessionStorage, los desarrolladores pueden mejorar significativamente la experiencia del usuario en sus aplicaciones web. Ten siempre en cuenta la seguridad y los límites de almacenamiento para asegurarte de que tus aplicaciones sean robustas y fáciles de usar. Con estas herramientas, puedes crear estados persistentes y funciones de gestión de datos que son fundamentales para las aplicaciones web modernas.

Práctica