Skip to content
@vp-tw/nanostores-storage

Quick Start

This guide will walk you through the basics of nanostores-storage.

1. Create a Storage Store

A storage store binds a single key to a reactive nanostore atom.

import { createStorageStore, localStorageAdapter } from "@vp-tw/nanostores-storage";


// Create a store for user preferences
const usernameStore = createStorageStore(localStorageAdapter, "username", {
  defaultValue: "Guest",
});

2. Read and Write Values

// Read current value
const username = usernameStore.get();
console.log(username); // "Guest" (or stored value)


// Update value
usernameStore.set("Alice");


// Remove value (resets to null)
usernameStore.remove();

3. Subscribe to Changes

// React to all changes
usernameStore.$value.subscribe((value) => {
  console.log("Username changed:", value);
});


// Or use listen() to skip the initial call
usernameStore.$value.listen((value) => {
  console.log("Username updated to:", value);
});

4. Use with React

import { useStore } from "@nanostores/react";
import { createStorageStore, localStorageAdapter } from "@vp-tw/nanostores-storage";


const usernameStore = createStorageStore(localStorageAdapter, "username", {
  defaultValue: "Guest",
});


function UserGreeting() {
  const username = useStore(usernameStore.$value);


  return (
    <div>
      <p>Hello, {username}!</p>
      <input
        value={username ?? ""}
        onChange={(e) => usernameStore.set(e.target.value)}
      />
    </div>
  );
}

5. Enable Cross-Tab Sync

Listen for changes from other browser tabs:

const usernameStore = createStorageStore(localStorageAdapter, "username", {
  defaultValue: "Guest",
  listen: true, // Enable cross-tab sync
});


// Or control manually:
usernameStore.listener.on();
usernameStore.listener.off();


// Check if listening:
console.log(usernameStore.listener.$on.get()); // true/false

6. Use sessionStorage

Simply swap the adapter:

import { createStorageStore, sessionStorageAdapter } from "@vp-tw/nanostores-storage";


const sessionStore = createStorageStore(sessionStorageAdapter, "session-data");

Complete Example

import { createStorageStore, localStorageAdapter } from "@vp-tw/nanostores-storage";


// Theme preference with cross-tab sync
const themeStore = createStorageStore(localStorageAdapter, "theme", {
  defaultValue: "system",
  listen: true,
});


// React to theme changes
themeStore.$value.subscribe((theme) => {
  document.documentElement.setAttribute("data-theme", theme ?? "system");
});


// Toggle theme
function toggleTheme() {
  const current = themeStore.get();
  const next = current === "dark" ? "light" : "dark";
  themeStore.set(next);
}

Next Steps