localStorage vs sessionStorage

They are the same API with the same two storage areas, and they differ in lifetime and scope.

Local storage is permanent. The data stays until something explicitly removes it, and it is shared by every page on the origin, in every tab. Session storage is scoped to the browsing context. Each tab gets its own copy, so two tabs of the same site do not see each other's session data, and the data is discarded when the tab is closed. A page opened in a new tab from a link starts with an empty session storage.

// Web storage only exists in a browser.
if (typeof localStorage !== "undefined") {
  localStorage.setItem("theme", "dark");
  sessionStorage.setItem("theme", "light");

  console.log(localStorage.getItem("theme"));    // "dark"
  console.log(sessionStorage.getItem("theme"));  // "light"

  // Both store strings only.
  localStorage.setItem("count", 42);
  console.log(typeof localStorage.getItem("count"));   // "string"

  // The keys and the length.
  console.log(localStorage.length);
  console.log(localStorage.key(0));

  // Removing an item.
  localStorage.removeItem("theme");
  console.log(localStorage.getItem("theme"));   // null
} else {
  console.log("No web storage in this runtime - open a browser console to try it.");
}

Both store strings only, so anything else has to be converted on the way in and parsed on the way out. That is why you see the JSON pattern in most code that stores objects, and why you have to handle the case where the stored text is not valid JSON.

The API is the same for both. The setItem, getItem, removeItem and clear methods, plus the length property and the key method. The one difference in the API itself is that reading a missing key gives you null rather than an error.

Both are synchronous, and that matters. Every read and write blocks the main thread while it happens, so a large amount of data or a lot of frequent writes will make the page janky. The values are also stored as text, so there is a practical size limit of a few megabytes per origin for local storage.

There are five that come up regularly, and they are worth listing because storage is easy to reach for and easy to get wrong.

It is synchronous. Every operation blocks the main thread. Reading a large value during page load makes the page wait, and writing in a tight loop makes it janky. This is the reason the storage event exists as a separate API for cross-tab communication.

It holds strings only. Objects have to be serialised, and everything comes back as text. That means dates, maps and sets need a revival step, and it means a stored value can be corrupted by a change in your data shape between versions.

There is a size limit. Local storage is typically a few megabytes per origin, and exceeding it throws an error rather than failing quietly. Session storage has a similar limit.

It is not private. Anything on the page can read it, including any script that got injected. That rules it out for tokens, personal data or anything else sensitive. A token in local storage is readable by any cross-site scripting bug on the site, and it stays there until the user clears it.

It has no expiry. Local storage data stays until it is removed, which means a stale schema can be sitting there when a new version of your app loads. A versioned key prefix, or a migration step that runs on start-up, is the usual defence.

Two more practical notes. Storage is per origin, so moving between the development and production hosts loses it. And in private browsing modes the behaviour varies, with some browsers treating local storage as if it were session storage and clearing it when the window closes.