nanostores

Nano Stores

A tiny state manager for React, Preact, Vue and Svelte. It uses many atomic stores and direct manipulation.

• Small. 152 bytes (minified and gzipped). Zero dependencies. It uses Size Limit to control size.
• Fast. With small atomic and derived stores, you do not need to call the selector function for all components on every store change.
• Tree Shakable. The chunk contains only stores used by components in the chunk.
• Was designed to move logic from components to stores. Already has router and persistent stores.
• It has good TypeScript support.

// store/users.ts
import { createStore, getValue } from 'nanostores'

export const users = createStore<User[]>(() => {
  users.set([])
})

export function addUser(user: User) {
  users.set([...getValue(users), user])
}

// store/admins.ts
import { createDerived } from 'nanostores'

import { users } from './users.js'

export const admins = createDerived(users, list =>
  list.filter(user => user.isAdmin)
)

// components/admins.tsx
import { useStore } from 'nanostores/react'

import { admins } from '../stores/admins.js'

export const Admins = () => {
  const list = useStore(admins)
  return (
    <ul>
      {list.map(user => <UserItem user={user} />)}
    </ul>
  )
}

It is part of Logux project but can be used without any other Logux parts.

Install

npm install nanostores

Tools

• Persistent store to save data to localStorage.
• Router store.
• Logux Client: stores with WebSocket sync and CRDT conflict resolution.

Stores

In Nano Stores, stores are smart. They subscribe to events, validate input, send AJAX requests, etc. For instance, build-in Router store subscribes to click on <a> and window.onpopstate. It simplifies testing and switching between UI frameworks (like from React to React Native).

import { createStore } from 'nanostores'

export type StoreType = …

export const simpleStore = createStore<StoreType>(() => {
  simpleStore.set(initialValue)
  // initializer: subscribe to events
  return () => {
    // destructor: unsubscribe from all events
  }
})

Stores have two modes: active and disabled. From the beginning, the store is in disabled mode and does not keep value. On the first subscriber, the store will call the initializer and will move to active mode. One second after unsubscribing of the last listener, the store will call the destructor.

The only way to get store’s value is to subscribe to store’s changes:

const unsubscribe2 = store.listen(value => {
  // Call listener on store changes
})

const unsubscribe1 = store.subscribe(value => {
  // Call listener immediately after subscribing and then on any changes
})

By we have shortcut to subscribe, return value and unsubscribe:

import { getValue } from 'nanostores'

getValue(store) //=> store’s value

Simple Store

Simple store API is the basement for all other stores.

import { createStore, getValue } from 'nanostores'

export const counter = createStore<number>(() => {
  counter.set(0)
})

export function increaseCounter() {
  counter.set(getValue(counter) + 1)
}

You can change store value by calling the store.set(newValue) method.

Map Store

This store with key-value pairs.

import { createMap } from 'nanostores'

export interface ProfileValue {
  name: string,
  email?: string
}

export const profile = createMap<ProfileValue>(() => {
  profile.setKey('name', 'anonymous')
})

In additional to store.set(newObject) it has store.setKey(key, value) to change specific key.

Changes listener receives changed key as a second argument.

profile.listen((value, changed) => {
  console.log(`${changed} new value ${value[changed]}`)
})

Map store object link is the same. store.set(newObject) changes all keys inside the old object.

Derived Store

The store is based on other store’s value.

import { createDerived } from 'nanostores'

import { users } from './users.js'

export const admins = createDerived(users, all => {
  // This callback will be called on every `users` changes
  return all.filter(user => user.isAdmin)
})

You can combine a value from multiple stores:

import { lastVisit } from './lastVisit.js'
import { posts } from './posts.js'

export const newPosts = createDerived([lastVisit, posts], (when, allPosts) => {
  return allPosts.filter(post => post.publishedAt > when)
})

Store Builder

A template to create a similar store. Each store made by the template is map store with at least the id key.

import { defineMap, BuilderStore } from 'nanostores'

export interface PostValue {
  id: string
  title: string
  updatedAt: number
}

export const Post = defineMap<PostValue>((newPost, id) => {
  newPost.setKey('title', 'New post')
  newPost.setKey('updatedAt', Date.now())
  // initializer: subscribe to events
  return () => {
    // destructor: unsubscribe from all events
  }
})

export function renamePost (post: BuilderStore<typeof Post>, newTitle: string) {
  post.setKey('title', newTitle)
  post.setKey('updatedAt', Date.now())
}

Builder is a function, which returns a new store instance.

import { Post } from '../stores/post.js'

const post = Post(id)

If a store has listeners, the builder will return the old post instance on the same store’s ID.

Post('same ID') === Post('same ID')

Best Practices

Move Logic from Components to Stores

Stores are not only to keep values. You can use them to track time, to load data from server.

import { createStore } from 'nanostores'

export const currentTime = createStore<number>(() => {
  currentTime.set(Date.now())
  const updating = setInterval(() => {
    currentTime.set(Date.now())
  }, 1000)
  return () => {
    clearInterval(updating)
  }
})

Use derived stores to create chains of reactive computations.

import { createDerived } from 'nanostores'

import { currentTime } from './currentTime.js'

const appStarted = Date.now()

export const userInApp = createDerived(currentTime, now => {
  return now - appStarted
})

We recommend moving all logic, which is not highly related to UI to the stores. Let your stores track URL routing, validation, sending data to a server.

With application logic in the stores, it’s much easy to write and run tests. It is also easy to change your UI framework. For instance, add React Native version of the application.

Think about Tree Shaking

We recommend doing all store changes in separated functions. It will allow to tree shake unused functions from JS bundle.

export function changeStore (newValue: string) {
  if (validate(newValue)) {
    throw new Error('New value is not valid')
  } else {
    store.set(newValue)
  }
}

For builder, you can add properties to the store, but try to avoid it.

interface UserExt {
  avatarCache?: string
}

export function User = defineMap<UserValue, [], UserExt>((store, id) => {
  …
})

function getAvatar (user: BuilderStore<typeof User>) {
  if (!user.avatarCache) {
    user.avatarCache = generateAvatar(getValue(user).email)
  }
  return user.avatarCache
}

Integration

React & Preact

Use useStore() hook to get store’s value and re-render component on store’s changes.

import { useStore } from 'nanostores/react' // or 'nanostores/preact'

import { profile } from '../stores/profile.js'
import { User } from '../stores/user.js'

export const Header = () => {
  const profile = useStore(profile)
  const currentUser = useStore(User(profile.userId))
  return <header>${currentUser.name}<header>
}

Vue

Use useStore() composable function to get store’s value and re-render component on store’s changes.

<template>
  <header>{{ currentUser.name }}</header>
</template>

<script>
  import { useStore } from 'nanostores/vue'

  import { profile } from '../stores/profile.js'
  import { User } from '../stores/user.js'

  export default {
    setup () {
      const profile = useStore(profile)
      const currentUser = useStore(User(profile.value.userId))
      return { currentUser }
    }
  }
</script>

Svelte

Every store implements Svelte store contract. Put $ before store variable to get store’s value and subscribe for store’s changes.

<script>
  import { profile } from '../stores/profile.js'
  import { User } from '../stores/user.js'

  const profile = useStore(profile)
  const currentUser = useStore(User(profile.userId))
</script>

<header>{$currentUser.name}</header>

Tests

Adding an empty listener by keepActive(store) keeps the store in active mode during the test. cleanStores(store1, store2, …) cleans stores used in the test.

import { getValue, cleanStores, keepActive } from 'nanostores'

import { profile } from './profile.js'

afterEach(() => {
  cleanStores(profile)
})

it('is anonymous from the beginning', () => {
  keepActive(profile)
  expect(getValue(profile)).toEqual({ name: 'anonymous' })
})

Build-in Stores

Persistent

You can create a store to keep value with some prefix in localStorage.

import { createPersistent } from 'nanostores'

export interface CartValue {
  list: string[]
}

export const shoppingCart = createPersistent<CartValue>({ list: [] }, 'cart')

This store also listen for keys changes in localStorage and can be used to synchronize changes between browser tabs.

Router

Since we promote moving logic to store, the router is a good part of the application to be moved from UI framework like React.

import { createRouter } from 'nanostores'

// Types for :params in route templates
interface Routes {
  home: void
  category: 'categoryId'
  post: 'categoryId' | 'id'
}

export const router = createRouter<Routes>({
  home: '/',
  category: '/posts/:categoryId',
  post: '/posts/:categoryId/:id'
})

Store in active mode listen for <a> clicks on document.body and Back button in browser.

You can use getPagePath() to avoid hard coding URL to a template. It is better to use the router as a single place of truth.

import { getPagePath } from 'nanostores'

…
  <a href={getPagePath(router, 'post', { categoryId: 'guides', id: '10' })}>

If you need to change URL programmatically you can use openPage or replacePage:

import { openPage, replacePage } from 'nanostores'

function requireLogin () {
  openPage(router, 'login')
}

function onLoginSuccess() {
  // Replace login route, so we don’t face it on back navigation
  replacePage(router, 'home')
}

Changelog

0.3.2

• Fixed map store initializer regression.