Nano Stores

Open a small online shop. You add a mug to your cart, switch the site to dark mode, open the menu. The page now remembers three things it didn’t a minute ago: what is in the cart, which theme you chose, and that the menu is open. Everything a page remembers while you use it is called its state.

State

The values a page remembers while it runs, which change as you use it.

Value

One piece of data: a number like 3, text like "dark", true or false, a list, or a group of named values.

State matters because people see it. When the cart goes from 0 items to 1, the little number on the cart icon must change from 0 to 1. If the value changes but the screen doesn’t, the page is lying to the visitor.

Pages are built from widgets: self-contained pieces, each with its own job. On our shop page, three widgets care about the cart. The header shows a badge with the number of items. The product list has “Add to cart” buttons. The checkout panel lists the items and the total.

Widget

A self-contained piece of a page with one job: a menu, a badge, a form. In code it is often called a component.

Shared state

State that more than one widget reads or changes, like the cart here.

One way to share is to keep the cart in a widget high up the page, and hand it down to every widget below that needs it. That works for a small page. On a real one, the cart has to travel through widgets that don’t care about it, just to reach the ones that do.

Another idea: put the cart in a variable that every widget can reach. A variable is a name that holds a value. A global variable is one the whole page can see. Sharing is solved. Being told about changes is not.

1// one variable the whole page can see2let cartCount = 03
4// the header badge draws itself once, at start5badge.textContent = cartCount6
7// later, the product list adds an item8function addToCart() {9  cartCount = cartCount + 110}

Think of a newspaper. You don’t walk to the printer every morning to check for news: you subscribe once, and each new edition comes to you. Shared state can work the same way. The value lives in one place, and any widget can subscribe to it. When it changes, every subscriber is told and can redraw itself.

Store

A place that holds a value, lets code change it, and tells subscribers when it does.

Subscribe

Ask a store to call you back every time its value changes.

Observer pattern

The general name for this design: one thing holds data, others “observe” it and are notified of changes.

Nano Stores is a library: ready-made code you add to your project instead of writing it yourself. It gives you stores you can read, change and subscribe to. Its core is a few hundred bytes, smaller than most images on a page.

• Framework-free. A store is plain JavaScript. It works the same in React, Vue, Svelte, a plain script, a test or a server.
• Small stores. You make one store per piece of state (the cart, the theme), not one giant object.
• Logic lives beside the stores. The code that changes the cart sits next to the cart, not inside each widget.
• Only what you use is shipped. Tools that pack your code for the browser leave out the parts you never import.

Library

Code someone else wrote and published, which you add to your project and call.

Framework

A larger library that shapes how you build a whole interface: React, Vue, Svelte are frameworks.

• State is what a page remembers while it runs: the cart, the theme, what was typed.
• When state changes, everything that shows it must update.
• Passing values through widgets gets tangled, and is impossible without a common parent.
• A global variable is shared, but changes to it reach nobody.
• A store holds a value and notifies its subscribers: the observer pattern.
• Nano Stores is a tiny, framework-free library of stores. Use it for state that several widgets share.

Before installing anything, you will write a tiny store yourself. It is the best way to see that Nano Stores isn’t magic: a store is a value, a list of people to call, and three small functions. The code is JavaScript, the language every browser runs.

1. Functions you can hand to other functions (callbacks).
2. Objects that group values and functions under names.
3. A store: a value, a list of listeners, get, set and subscribe.
4. How to stop listening, and why equal values shouldn’t notify.

1function greet(name) {2  return 'Hello, ' + name3}4
5greet('Ana') // 'Hello, Ana'6
7const shout = (text) => text.toUpperCase()8
9function twice(fn, value) {10  return fn(fn(value))11}12twice(shout, 'hi') // 'HI'

Function

Named steps you can run (call) later, with inputs, giving back a result.

Callback

A function you give to other code so it can call you back later.

`const`

Makes a name for a value that won’t be reassigned. let makes one that can be.

1const mug = {2  name: 'Blue mug',3  price: 1200, // in cents: 12.004  describe() {5    return this.name + ' costs ' + this.price / 1006  }7}8
9mug.name // 'Blue mug'10mug.describe() // 'Blue mug costs 12'

Curly braces make an object: named slots called properties. A property can hold a function, then called a method: describe here. this inside a method means “the object it belongs to”. Square brackets make an array, an ordered list: ["mug", "plate"].

1const cartCount = createStore(0)2
3cartCount.subscribe((count) => {4  badge.textContent = count5})6
7function addToCart() {8  cartCount.set(cartCount.get() + 1)9}

Compare with the global variable of module 1. The badge subscribes once. addToCart doesn’t know the badge exists: it only changes the store. A checkout panel added next month subscribes too, and addToCart doesn’t change.

1set(newValue) {2  value = newValue3  for (const listener of ) {4    5  }6}

When a widget is removed from the page, its listener should be removed too. Otherwise the store keeps calling a function for something that is gone, and keeps it in memory forever: a memory leak. The neat way: subscribe returns a function that unsubscribes.

1subscribe(listener) {2  listeners.push(listener)3  listener(value)4  return () => {5    const index = listeners.indexOf(listener)6    if (index !== -1) listeners.splice(index, 1)7  }8}9
10// using it11const stop = cartCount.subscribe(draw)12stop() // draw is never called again

1const theme = createStore('light')2const stop = theme.subscribe((t) => console.log(t))3theme.set('dark')4stop()5theme.set('light')

1set(newValue) {2  if (Object.is(value, newValue)) return3  value = newValue4  for (const listener of listeners) listener(value)5}

If the theme is already "dark" and someone sets "dark", redrawing every widget is wasted work. Object.is(a, b) asks “are these the same value?”, and return leaves the function early. For numbers and text, “same” means equal. For objects and arrays it means the very same object, not one with the same contents: two arrays that look alike are still two arrays.

Put the last three slides together. The tests below check each promise the store makes; run them as you go and watch them turn green one by one.

1function createStore(initial) {2  let value = initial3  const listeners = []4  return {5    get() {6      return value7    },8    set(newValue) {9      value = newValue10    },11    subscribe(listener) {12      listeners.push(listener)13      return () => {}14    }15  }16}

Your store works. Nano Stores’ atom is the same idea, carefully tested, with more on top.

• A function is a value: you can pass it to other code as a callback.
• An object groups properties and methods under names; an array is an ordered list.
• A store keeps a value and an array of listeners; set calls each listener.
• subscribe should return a function that removes the listener, or memory leaks.
• Skip notifying when Object.is says the value is the same.
• Objects and arrays are “the same” only if they are the very same object.

Web projects are set up with a few tools that run on your computer. You type commands into a terminal, a window where you talk to the computer in text. Node.js runs JavaScript outside the browser. npm comes with Node.js and downloads libraries, called packages, from a public registry.

Terminal

A text window for typing commands: Terminal on a Mac, Windows Terminal on Windows.

Node.js

A program that runs JavaScript on your computer or a server, not only in a browser.

npm

The package manager that comes with Node.js: it installs and updates libraries.

Package

A library published for npm, with a name like nanostores.

1node --version   # prints something like v22.11.02npm --version    # prints something like 10.9.0

1mkdir shop && cd shop     # make a folder and enter it2npm init -y               # start a project: makes package.json3npm install nanostores    # download Nano Stores into it

1{2  "name": "shop",3  "type": "module",4  "dependencies": {5    "nanostores": "^1.0.0"6  }7}

package.json is the project’s list of what it needs. After npm install, Nano Stores appears under dependencies, and its code lands in a node_modules folder you never edit. ^1.0.0 means “version 1, any later 1.x release”. This course teaches Nano Stores 1.

export const greeting = 'hi'
export function add(a, b) {  return a + b}

import { add, greeting } from './stores/cart.js'
add(2, 3) // 5

In modern JavaScript, each file is a module. export marks what other files may use; import brings it in. One fact matters a lot for stores: a module runs once. However many files import stores/cart.js, they all get the very same values. That is how separate widgets end up sharing one store.

1import { atom } from 'nanostores'2
3export const $theme = atom('light')4
5$theme.get() // 'light'6
7$theme.subscribe((theme) => {8  console.log('theme is now', theme)9})10// logs 'theme is now light' right away11
12$theme.set('dark')13// logs 'theme is now dark'

Atom

Nano Stores’ basic store: it holds one value, replaced as a whole with set.

1import { atom } from 'nanostores'2
3const $count = atom(0)4
5$count.subscribe((count) => {6  console.log('the badge shows', count)7})8
9$count.set(1)10$count.set($count.get() + 1)11$count.set(2)

Nano Stores code names stores with a $ in front: $theme, $cart. To JavaScript, $ is just a letter. To people, it says “this is a store: read it with get() or subscribe, don’t treat it as the value itself”.

const theme = atom('light')if (theme === 'dark') {  // never true: theme is a store}

const $theme = atom('light')if ($theme.get() === 'dark') {  // compares the value}

1import {  } from 'nanostores'2
3export const  = atom()4
5$menuOpen.(true)

TypeScript is JavaScript with types: labels that say what kind of value a name may hold. A checker reads them and points out mistakes before the code runs. Nano Stores is written for it. Files end in .ts instead of .js. The rest of this course uses TypeScript.

1import { atom } from 'nanostores'2
3export type Theme = 'light' | 'dark'4
5export const $theme = atom<Theme>('light')6
7$theme.set('dark') // fine8$theme.set('blue') // error, see below

• type Theme = "light" | "dark" names a type: one of these two words, nothing else. | reads “or”.
• atom<Theme>(…) tells the atom the type of its value. The part in angle brackets is a type parameter.
• Without it, atom("light") would accept any text at all.

1stores/theme.ts:8:12 - error TS2345: Argument of type2'"blue"' is not assignable to parameter of type 'Theme'.

• stores/theme.ts:8:12: the file, the line (8) and the column (12). Go there first.
• Argument of type "blue": the value you passed.
• is not assignable to parameter of type Theme: what was expected. The two don’t fit.
• Fix the value, or, if "blue" should be allowed, add it to Theme.

• npm installs packages; package.json lists them; their code lives in node_modules.
• Each file is a module that runs once: everything importing a store shares it.
• atom(initial) makes a store; get, set and subscribe use it.
• Name stores with $ so they are never mistaken for their values.
• In TypeScript, give the atom its type when the first value is narrower: atom<Theme>("light").
• A type error names the file, line and column, the value given and the type expected.

1import { atom } from 'nanostores'2
3export type CartItem = {4  id: string5  name: string6  price: number // in cents7  quantity: number8}9
10export const $cart = atom<CartItem[]>([])

• type CartItem = { … } describes an object: every cart item has these four properties, of these types.
• CartItem[] means “an array of CartItems”.
• The cart starts as an empty array, []. Without <CartItem[]>, TypeScript couldn’t know what goes in it.

This store is the running example for the rest of the course: a header badge, a product list and a checkout panel will all use it.

Like the store you built, set compares the new value with the current one using Object.is. Equal: nothing happens, no listener runs. For text and numbers that means the same value; for objects and arrays, the same object.

1const $count = atom(0)2$count.listen((value) => console.log('now', value))3
4$count.set(1)5$count.set(1)6$count.set(2)

1const stop = $cart.listen((cart) => {2  console.log('items:', cart.length)3})4
5// when the widget is removed from the page:6stop()

A listener you forget to remove keeps running, and keeps everything it uses in memory, for as long as the page is open. Framework bindings (module 8) call stop for you when a component goes away; in a plain script, it is your job. Calling stop twice is harmless.

1const stop = $theme.((theme, previous) => {2  console.log(`from ${previous} to ${theme}`)3})4
5$theme.('dark') // logs 'from light to dark'6
7// when the panel closes:8

Arrays and objects can be changed in place: cart.push(item) adds to the same array. But set compares objects by identity, so setting the same array back looks like “no change” and notifies nobody. The rule: always build a new array or object.

const cart = $cart.get()cart.push(mug)$cart.set(cart)// same array: nobody is told

$cart.set([...$cart.get(), mug])// a new array: listeners run

• atom<T>(initial) holds one value; give T when the starting value is narrower.
• set notifies only when Object.is says the value changed.
• subscribe runs at once and on changes; listen only on changes, with the old value.
• Both return a function that stops listening. Call it when the reader goes away.
• Never change a store’s array or object in place: spread, map, filter, toSorted.
• Accept ReadableAtom<T> where you only read; read with get(), not .value.

The visitor’s preferences are a small group: a theme, a currency, whether prices include tax. With an atom, changing one field means copying the whole object every time. A map store is made for this: an object whose fields you change one key at a time.

$prefs.set({  ...$prefs.get(),  theme: 'dark'})

$prefs.setKey('theme', 'dark')

Key

The name of a property in an object: in { theme: "dark" }, the key is theme.

Map store

A Nano Store holding an object, with setKey to change one key.

• setKey("theme", "dark") when the theme is already "dark" notifies nobody: each key is compared with Object.is.
• setKey("withTax", undefined) deletes the key from the object, and notifies (if the key was there).
• Listeners get a third argument: the key that changed. After a whole-object set it is undefined.

1$prefs.listen((prefs, oldPrefs, changedKey) => {2  console.log(changedKey, 'is now', changedKey && prefs[changedKey])3})4
5$prefs.setKey('currency', 'eur') // currency is now eur6$prefs.setKey('currency', 'eur') // nothing7$prefs.setKey('withTax', true)   // withTax is now true

A map can also hold a collection keyed by id. Keyed this way, the cart can find, change or remove one product without searching an array. TypeScript writes “an object with any text keys, each a number” as Record<string, number>.

1import { map } from 'nanostores'2
3/** Quantity of each product in the cart, by product id. */4export const $quantities = map<Record<string, number>>({})5
6export function addOne(productId: string) {7  const now = $quantities.get()[productId] ?? 08  $quantities.setKey(productId, now + 1)9}10
11export function removeAll(productId: string) {12  $quantities.setKey(productId, undefined)13}

1export function removeOne(productId: string) {2  const now = $quantities.get()[productId] ?? 03  if (now <= 1) {4    $quantities.setKey(productId, )5  } else {6    $quantities.(productId, )7  }8}

1import { deepMap } from 'nanostores'2
3export const $checkout = deepMap({4  address: { city: '', zip: '' },5  card: { saved: false }6})7
8$checkout.setKey('address.city', 'Lisbon')

A map only reaches its top-level keys. deepMap accepts a path written with dots (and [0] for array positions) to change a value deep inside. Each change copies the objects along the path, so references still say what changed.

• map(initial) is an atom holding an object, with setKey(key, value) on top.
• Each setKey makes a new object; an equal value notifies nobody; undefined deletes the key.
• Listeners get the changed key as a third argument (undefined after a whole set).
• listenKeys and subscribeKeys react only to the keys you name.
• Use a map for fields of one thing; separate atoms for unrelated values.
• deepMap changes nested values by path; prefer flat stores when you can.

The badge shows how many items are in the cart. The checkout panel shows the total price. Neither is new information: both can be worked out from the cart at any moment. Values worked out from other state are called derived state.

Derived state

A value worked out from other state, like a total from a list of prices.

Stale

Out of date: a copy that no longer matches what it was copied from.

1import { atom, computed } from 'nanostores'2
3export const $cart = atom<CartItem[]>([])4
5export const $itemCount = computed($cart, (cart) =>6  cart.reduce((sum, item) => sum + item.quantity, 0)7)8
9export const $total = computed($cart, (cart) =>10  cart.reduce((sum, item) => sum + item.price * item.quantity, 0)11)

• A computed store is read-only: get, listen, subscribe, but no set. Its type is ReadableAtom.
• Readers use it like any other store; they can’t tell it is derived.

1const RATES = { usd: 1, eur: 0.9 } // example rates2
3export const $shownTotal = computed(4  [$total, $prefs],5  (total, prefs) => {6    const amount = (total / 100) * RATES[prefs.currency]7    return amount.toFixed(2) + ' ' + prefs.currency.toUpperCase()8  }9)10// "24.00 USD", or "21.60 EUR" after switching

Pass an array of stores, and the function receives their values in the same order. The result updates when any of them changes. A computed store can be a source for another computed store too: $shownTotal is built on $total, itself built on $cart.

1export const $freeShipping = (2  ,3  (total) => total  50004)

• When nothing listens to it, a computed store does nothing: it is lazy.
• The first listener wakes it: it subscribes to its sources and computes.
• Afterwards, each change to a source recomputes it, straight away.
• get() on a sleeping computed store computes on demand, so you always get a correct value.
• It remembers its sources’ last values: if none changed, it doesn’t run its function again.

1const $a = atom(1)2const $b = atom(2)3const $sum = computed([$a, $b], (a, b) => {4  console.log('compute')5  return a + b6})7
8$sum.listen(() => {})9$a.set(10)10$b.set(20)

1import { atom, computed } from 'nanostores'2
3const $cart = atom([1200, 350])4const $total = computed($cart, (prices) => {5  console.log('working out the total')6  return prices.reduce((sum, price) => sum + price, 0)7})8
9$cart.set([1200]) // nobody watches: nothing is worked out10console.log('first get:', $total.get())11
12const stop = $total.listen((total) => console.log('total', total))13$cart.set([1200, 99])14$cart.set([1200, 99, 1])15stop()

A computed store is an atom inside, so its own result goes through the same Object.is check. If the cart changes but $freeShipping is still true, nobody listening to $freeShipping is told. That makes small computed values a cheap filter: widgets that only need a yes or no re-render only when the answer flips.

A pure function only reads its inputs and returns a result. It doesn’t change anything outside, doesn’t fetch, doesn’t read the clock. Nano Stores decides when to run your function (on first listener, on source changes, on get()), so anything else it does happens at times you don’t control.

• Derived state is worked out from other state: never store a copy you must keep in sync.
• computed(source, fn) or computed([a, b], fn) makes a read-only store.
• It is lazy: it works only while listened to, and get() computes on demand.
• Each source change recomputes it synchronously; an unchanged result notifies nobody.
• Computed stores can build on each other.
• Keep the function pure and synchronous: no fetching, sending or setting stores.

Until now, code called $cart.set(…) wherever it liked. On a real page that spreads the rules of the cart across every widget: one adds items one way, another a slightly different way. An action is a plain function, exported next to the store, that makes one kind of change. Widgets call the action; only actions call set.

1export const $cart = atom<CartItem[]>([])2
3export function addToCart(product: Product) {4  const cart = $cart.get()5  const line = cart.find((item) => item.id === product.id)6  if (line) {7    $cart.set(cart.map((item) =>8      item === line ? { ...item, quantity: item.quantity + 1 } : item9    ))10  } else {11    $cart.set([...cart, { ...product, quantity: 1 }])12  }13}

Action

An exported function, beside a store, that changes it in one named way: addToCart, clearCart.

Inside an action, get() reads the store at the moment the action runs, which is what you want: the cart as it is now, not as it was when a widget last drew. Actions can read several stores and change several too.

1export function checkout() {2  const cart = $cart.get()3  if (cart.length === 0) return4  $lastOrder.set({ items: cart, total: $total.get() })5  $cart.set([])6}

The rules of a to-do list belong in its actions, so every widget that adds a task gets them for free.

1import { atom } from 'nanostores'2
3type Todo = { id: number; text: string; done: boolean }4
5export const $todos = atom<Todo[]>([])6let lastId = 07const nextId = () => ++lastId8
9export function addTodo(text: string) {10  const todo = { id: nextId(), text, done: false }11  $todos.set([...$todos.get(), todo])12}13
14export function toggleTodo(id: number) {15  // TODO16}

• Small stores: one per piece of state, so readers are told only about what they show.
• One module per topic: everything about the cart in cart.ts.
• Widgets import, never define: a store made inside a widget file is easy to duplicate by mistake.
• Stores can use other modules’ stores: checkout can read $prefs from prefs.ts.

1import { atom, readonlyType } from 'nanostores'2
3const $cartWritable = atom<CartItem[]>([])4
5export const $cart = readonlyType($cartWritable)6
7export function clearCart() {8  $cartWritable.set([])9}

readonlyType returns the very same store, but typed as a ReadableAtom. Outside the file, $cart.set(…) is a type error, so every change goes through the actions. It is a fence for TypeScript, not at run time: the object still has set. That is all a team needs.

setCart(...)setCartItems(...)updateMap(...)

addToCart(product)setQuantity(id, 3)removeFromCart(id)clearCart()

Widgets should read like a description of the page: “when clicked, add to cart”. Names about storage leak how the store works, and must change when it does. Good names also make the module’s exports a short, readable list of everything the cart can do.

• An action is an exported function beside a store that makes one named change.
• Widgets call actions; only actions call set. The rules live in one place.
• Actions read with get() at the moment they run.
• Small stores, one module per topic; widgets import stores, never define them.
• readonlyType exports a store that TypeScript won’t let others set.
• Name actions for what happens: addToCart, not setCart.

1import { useState } from 'react'2
3export function Counter() {4  const [count, setCount] = useState(0)5  return (6    <button onClick={() => setCount(count + 1)}>7      Clicked {count} times8    </button>9  )10}

• A React component is a function that returns what to show, written in JSX: HTML-like tags inside TypeScript (files end in .tsx).
• useState gives the component its own remembered value and a function to change it.
• When state changes, React calls the function again (re-renders) and updates the screen.
• That state belongs to this one component. Another component can’t see it.

Component

A function that returns a piece of interface; React’s word for a widget.

Re-render

React calling a component again to get its new output after something changed.

Hook

A function starting with use that gives a component a React feature: useState, useStore.

1npm install @nanostores/react

1import { useStore } from '@nanostores/react'2import { $itemCount } from '../stores/cart'3
4export function CartBadge() {5  const count = useStore($itemCount)6  if (count === 0) return null7  return <span className="badge">{count}</span>8}

When the component is removed from the page, useStore unsubscribes for you. Under the hood it uses React’s useSyncExternalStore, the hook React provides for reading stores that live outside it.

1import { addToCart } from '../stores/cart'2
3export function ProductList({ products }: { products: Product[] }) {4  return (5    <ul>6      {products.map((product) => (7        <li key={product.id}>8          {product.name}9          <button onClick={() => addToCart(product)}>Add</button>10        </li>11      ))}12    </ul>13  )14}

This component doesn’t read the cart at all, so it needs no useStore: it never re-renders when the cart changes. It only calls an action. Meanwhile the badge, which does read the cart, updates. The two components don’t know about each other.

1const $form = map({ email: '', password: '', busy: false })2
3function SubmitButton() {4  const { busy } = useStore($form, { keys: ['busy'] })5  return <button disabled={busy}>Sign up</button>6}

Without keys, the button re-renders on every keystroke in the email field, because the map’s object changes. With keys: ["busy"], it is told only when busy changes. The value returned is still the whole object; only the notifications are filtered.

const cart = useStore($cart)const count = cart.reduce(  (sum, item) => sum + item.quantity,  0)

const count = useStore($itemCount)

Say a product’s price is updated in the cart. $cart changes, but the number of items doesn’t. A component reading $itemCount stays still, because the computed result is the same number. One that reads $cart and counts by itself re-renders for nothing.

• npm install @nanostores/react; useStore($store) subscribes and returns the value.
• The component re-renders when the value changes, and unsubscribes when removed.
• Components that only call actions don’t need useStore, and don’t re-render.
• useStore($map, { keys: [...] }) re-renders only for those keys.
• Compute in computed stores, not in components.
• One component’s state stays in useState; shared state goes to a store.

Many sites are mostly plain HTML, with a few interactive widgets dropped in: a cart badge in the header, an “Add” button by each product, a checkout panel. Each widget is an island: it is sent as HTML, then started on its own in the browser. Astro builds pages this way, and so do other tools.

Island

An interactive widget, started on its own, inside a page that is otherwise static HTML.

Hydration

A framework taking over HTML that was already drawn: attaching click handlers and state to it so it becomes interactive.

Each island is a separate React root: its own tree, started on its own. React state and React context don’t cross from one root to another, because there is no component above them both. What they do share is the page’s JavaScript: when two islands import stores/cart.ts, the module runs once and both get the same $cart.