Nano Stores

Common errors

• ERR_REQUIRE_ESM ... require() of ES Module ... Not supported

  cause Attempting to use `require()` to import Nano Stores, which is distributed as an ES Module (ESM).
  fix Use ES Module `import` syntax (`import { atom } from 'nanostores'`). Ensure your project is configured for ESM (e.g., by setting `"type": "module"` in `package.json` or using a bundler like Webpack/Rollup/Vite).

• TypeError: $store.subscribe is not a function

  cause This error often indicates that you are trying to call a store method (like `.subscribe()`, `.get()`, or `.set()`) on a variable that is not a valid Nano Stores store object, or you've incorrectly imported a framework-specific utility instead of a core store.
  fix Verify that the variable `$store` is indeed a store created by `atom()` or `computed()`. Also, ensure you are importing core store functions (e.g., `atom`, `computed`) from `nanostores` and framework-specific utilities (e.g., `useStore`) from their respective packages (e.g., `@nanostores/react`).

• Error: Node.js v18.x is no longer supported.

  cause You are running a Nano Stores version 1.0.0 or higher on an unsupported Node.js v18.x environment.
  fix Upgrade your Node.js version to `20.0.0` or `22.0.0` (or newer) to meet the minimum engine requirements for Nano Stores v1.0.0 and above.

Warnings

• breaking Node.js v18.x support was removed in Nano Stores v1.0.0. Projects using older Node.js versions will encounter runtime errors or installation failures.
  Fix: Upgrade your Node.js environment to version 20.0.0 or newer (or 22.0.0 for the latest recommended). The `engines` field in `package.json` specifies `^20.0.0 || >=22.0.0`.
• deprecated The async `computed` functionality within the main `nanostores` package was deprecated in favor of a separate `@nanostores/async` package.
  Fix: For asynchronous computed stores, migrate to the `@nanostores/async` package. Update your imports and logic to use the dedicated async utilities from this new package.
• deprecated The `deepmap()` utility was deprecated in favor of a separate `@nanostores/deepmap` package.
  Fix: If you are using deep map stores, migrate to the `@nanostores/deepmap` package. Update your imports and code to use the `deepmap` utility from this external package.

Install

• npm install nanostores npm
• yarn add nanostores yarn
• pnpm add nanostores pnpm

Imports

• atom
  wrong:

  const { atom } = require('nanostores')

  correct:

  import { atom } from 'nanostores'

  The primary function for creating atomic stores. Nano Stores is ESM-first, so CommonJS `require()` is not supported directly without a transpilation layer.
• computed
  wrong:

  import { computed as asyncComputed } from 'nanostores'

  correct:

  import { computed } from 'nanostores'

  Used to derive state from one or more existing stores. Asynchronous `computed` was deprecated in v1.2.0; use `@nanostores/async` for async derivations.
• useStore
  wrong:

  import { useStore } from 'nanostores'

  correct:

  import { useStore } from '@nanostores/react'

  This is a framework-specific hook, exemplified here for React. Equivalent hooks for Vue, Svelte, etc., are available in their respective `@nanostores/<framework>` packages.

Quickstart

This example demonstrates creating an atomic store with `atom`, defining actions to modify it, deriving state with `computed`, and subscribing to changes using `listen` to observe state updates.

interface Task {
  id: string;
  text: string;
  completed: boolean;
}

import { atom, computed } from 'nanostores';

// 1. Create an atomic store using `atom`
export const $tasks = atom<Task[]>([]);

// 2. Define actions to manipulate the store
export function addTask(text: string) {
  const newTask: Task = {
    id: String(Date.now()),
    text,
    completed: false
  };
  $tasks.set([...$tasks.get(), newTask]);
  console.log(`Added task: "${text}"`);
}

export function toggleTask(id: string) {
  $tasks.set($tasks.get().map(task =>
    task.id === id ? { ...task, completed: !task.completed } : task
  ));
  console.log(`Toggled task with ID: ${id}`);
}

// 3. Create a derived store using `computed`
export const $pendingTasksCount = computed($tasks, tasks =>
  tasks.filter(task => !task.completed).length
);

// 4. Subscribe to store changes
console.log('--- Initial State ---');
console.log('Tasks:', $tasks.get());
console.log('Pending count:', $pendingTasksCount.get());

const unsubscribeTasks = $tasks.listen(currentTasks => {
  console.log('\n--- Tasks Updated ---');
  console.log('Current tasks:', currentTasks.map(t => `${t.text} (${t.completed ? 'Done' : 'Pending'})`).join(', '));
});

const unsubscribePendingCount = $pendingTasksCount.listen(count => {
  console.log('Current pending tasks count:', count);
});

// 5. Trigger actions to see state changes
addTask('Learn Nano Stores');
addTask('Build a cool app');
toggleTask($tasks.get()[0]?.id || '');

setTimeout(() => {
  addTask('Review documentation');
  toggleTask($tasks.get()[1]?.id || '');
  console.log('\n--- Final State after Timeout ---');
  console.log('Tasks:', $tasks.get().map(t => `${t.text} (${t.completed ? 'Done' : 'Pending'})`).join(', '));
  console.log('Pending count:', $pendingTasksCount.get());

  // Clean up subscriptions (important in real apps)
  unsubscribeTasks();
  unsubscribePendingCount();
}, 200);