State Management with Nanostores in Astro

Introduction

Welcome to the first part of "Nanostores in Astro: A Multi-Framework Adventure" series. If you've been grappling with state management in your multi-framework Astro projects, you're in for a treat. Today, we're exploring Nanostores, a lightweight state management solution that seamlessly integrates with Astro's component islands architecture.

In this article, we'll delve into how Nanostores can streamline state management across Astro, React, Vue, and Svelte components. We'll cover independent state, shared state, and introduce persistent state management. Let's embark on this journey to simplify our Astro projects' state management.

TL;DR

If you're eager to dive right in, here's a quick summary and some essential links:

This article explores Nanostores for state management in multi-framework Astro projects.
We cover independent, shared, and persistent state management across Astro, React, Vue, and Svelte.
Check out these resources:

Feel free to explore the demo and code alongside this article for a hands-on learning experience!

Understanding Nanostores

What are Nanostores?

Nanostores is a minimalist state management library designed with framework agnosticism in mind. It provides a straightforward API for creating and managing atomic pieces of state, which can be easily shared and updated across different parts of your application.

Why Use Nanostores in Astro?

Lightweight and Fast: Nanostores is incredibly small (Between 265 and 814 bytes), ensuring it won't bloat your bundle size.
Framework-Agnostic: Perfect for Astro's multi-framework ecosystem. It integrates seamlessly with React, Vue, Svelte, Solid and vanilla JavaScript.
Simple API: No complex setup or boilerplate. It's straightforward and intuitive to use.
Complementary to Astro's Component Islands: Nanostores enhances Astro's islands architecture, allowing efficient state management across isolated interactive components.

Basic Concepts

Nanostores revolves around three main concepts:

Atoms: Simple stores that hold a single value.
Maps: Stores that hold objects with multiple properties.
Computed Stores: Derived stores that calculate their value based on other stores.

Let's look at a quick example:

import { atom, map, computed } from 'nanostores'

// Atom
const count = atom(0)

// Map
const user = map({ name: 'Astro Fan', isLoggedIn: false })

// Computed Store
const greeting = computed([user], (user) => 
  user.isLoggedIn ? `Welcome back, ${user.name}!` : 'Hello, guest!'
)

In this snippet, we've created an atom for a counter, a map for user data, and a computed store for a dynamic greeting. Simple, right?

Setting Up Nanostores in an Astro Project

Getting started with Nanostores in your Astro project is straightforward. Here's how to do it:

First, install Nanostores and its framework integrations:

# Using npm
npm install nanostores
npm install @nanostores/react  # For React
npm install @nanostores/vue    # For Vue

# Using yarn
yarn add nanostores
yarn add @nanostores/react     # For React
yarn add @nanostores/vue       # For Vue

# Using pnpm
pnpm add nanostores
pnpm add @nanostores/react     # For React
pnpm add @nanostores/vue       # For Vue

# Note: Svelte doesn't require a separate integration

Create a new file for your stores, let's say src/stores/counterStore.js:

import { atom } from 'nanostores'

export const count = atom(0)

export function increment() {
  count.set(count.get() + 1)
}

export function decrement() {
  count.set(count.get() - 1)
}

Now you can use this store in any of your components. Here's a quick example in an Astro component:

---
import { count, increment, decrement } from '../stores/counterStore'
---

<div>
  <button onclick={decrement}>-</button>
  <span>{count.get()}</span>
  <button onclick={increment}>+</button>
</div>

<script>
  import { count } from '../stores/counterStore'

  count.subscribe(value => {
    document.querySelector('span').textContent = value
  })
</script>

And there you have it! You've just set up a Nanostore in your Astro project.

Independent State Management

In multi-framework Astro projects, you might want to manage state independently within components of different frameworks. Nanostores makes this seamless. Let's explore how to implement independent state management across React, Vue, Svelte, and Astro components.

Counter Example

We'll implement a simple counter in each framework to demonstrate independent state management.

First, let's create our independent counter store:

// src/stores/independentCounterStore.js
import { atom } from 'nanostores'

export const reactCount = atom(0)
export const vueCount = atom(0)
export const svelteCount = atom(0)
export const astroCount = atom(0)

export function increment(store) {
  store.set(store.get() + 1)
}

export function decrement(store) {
  store.set(store.get() - 1)
}

Now, let's implement this counter in each framework:

React Counter

// src/components/ReactCounter.jsx
import { useStore } from '@nanostores/react'
import { reactCount, increment, decrement } from '../stores/independentCounterStore'

export function ReactCounter() {
  const count = useStore(reactCount)

  return (
    <div>
      <button onClick={() => decrement(reactCount)}>-</button>
      <span>{count}</span>
      <button onClick={() => increment(reactCount)}>+</button>
    </div>
  )
}

Vue Counter

<!-- src/components/VueCounter.vue -->
<template>
  <div>
    <button @click="decrement(vueCount)">-</button>
    <span>{{ count }}</span>
    <button @click="increment(vueCount)">+</button>
  </div>
</template>

<script setup>
import { useStore } from '@nanostores/vue'
import { vueCount, increment, decrement } from '../stores/independentCounterStore'

const count = useStore(vueCount)
</script>

Svelte Counter

<!-- src/components/SvelteCounter.svelte -->
<script>
import { svelteCount, increment, decrement } from '../stores/independentCounterStore'
</script>

<div>
  <button on:click={() => decrement(svelteCount)}>-</button>
  <span>{$svelteCount}</span>
  <button on:click={() => increment(svelteCount)}>+</button>
</div>

Astro Counter

---
import { astroCount, increment, decrement } from '../stores/independentCounterStore'
---

<div>
  <button id="decrement">-</button>
  <span id="count">{astroCount.get()}</span>
  <button id="increment">+</button>
</div>

<script>
  import { astroCount, increment, decrement } from '../stores/independentCounterStore'

  document.getElementById('decrement').addEventListener('click', () => decrement(astroCount))
  document.getElementById('increment').addEventListener('click', () => increment(astroCount))

  astroCount.subscribe(value => {
    document.getElementById('count').textContent = value
  })
</script>

As you can see, each framework component maintains its own independent counter state using Nanostores. This approach allows for isolated state management within each component, regardless of the framework used.

Shared State Across Frameworks

Now, let's explore how Nanostores enables shared state across different framework components. This is particularly useful when you need to synchronize state between various parts of your application.

Shared Counter Example

We'll create a shared counter that can be updated and displayed across React, Vue, Svelte, and Astro components.

First, let's create our shared counter store:

// src/stores/sharedCounterStore.js
import { atom } from 'nanostores'

export const sharedCount = atom(0)

export function increment() {
  sharedCount.set(sharedCount.get() + 1)
}

export function decrement() {
  sharedCount.set(sharedCount.get() - 1)
}

Now, let's implement components in each framework that use this shared state:

React Shared Counter

// src/components/ReactSharedCounter.jsx
import { useStore } from '@nanostores/react'
import { sharedCount, increment, decrement } from '../stores/sharedCounterStore'

export function ReactSharedCounter() {
  const count = useStore(sharedCount)

  return (
    <div>
      <h2>React Shared Counter</h2>
      <button onClick={decrement}>-</button>
      <span>{count}</span>
      <button onClick={increment}>+</button>
    </div>
  )
}

Vue Shared Counter

<!-- src/components/VueSharedCounter.vue -->
<template>
  <div>
    <h2>Vue Shared Counter</h2>
    <button @click="decrement">-</button>
    <span>{{ count }}</span>
    <button @click="increment">+</button>
  </div>
</template>

<script setup>
import { useStore } from '@nanostores/vue'
import { sharedCount, increment, decrement } from '../stores/sharedCounterStore'

const count = useStore(sharedCount)
</script>

Svelte Shared Counter

<!-- src/components/SvelteSharedCounter.svelte -->
<script>
import { sharedCount, increment, decrement } from '../stores/sharedCounterStore'
</script>

<div>
  <h2>Svelte Shared Counter</h2>
  <button on:click={decrement}>-</button>
  <span>{$sharedCount}</span>
  <button on:click={increment}>+</button>
</div>

Astro Shared Counter

---
import { sharedCount, increment, decrement } from '../stores/sharedCounterStore'
---

<div>
  <h2>Astro Shared Counter</h2>
  <button id="shared-decrement">-</button>
  <span id="shared-count">{sharedCount.get()}</span>
  <button id="shared-increment">+</button>
</div>

<script>
  import { sharedCount, increment, decrement } from '../stores/sharedCounterStore'

  document.getElementById('shared-decrement').addEventListener('click', decrement)
  document.getElementById('shared-increment').addEventListener('click', increment)

  sharedCount.subscribe(value => {
    document.getElementById('shared-count').textContent = value
  })
</script>

With this setup, all these components will share the same counter state. Incrementing or decrementing the counter in any component will update the value across all components, regardless of the framework used.

Persistent State Management

While independent and shared states are powerful, sometimes we need our state to persist across page reloads or even browser sessions. This is where @nanostores/persistent comes into play. Let's explore how to implement persistent state in our Astro project.

Setting Up Persistent State

First, we need to install the persistent addon for Nanostores:

# Using npm
npm install @nanostores/persistent

# Using yarn
yarn add @nanostores/persistent

# Using pnpm
pnpm add @nanostores/persistent

Now, let's create a persistent counter that will maintain its value even when the page is refreshed:

// src/stores/persistentCounterStore.js
import { persistentAtom } from '@nanostores/persistent'

export const persistentCount = persistentAtom('persistentCount', 0)

export function increment() {
  persistentCount.set(persistentCount.get() + 1)
}

export function decrement() {
  persistentCount.set(persistentCount.get() - 1)
}

export function reset() {
  persistentCount.set(0)
}

In this example, 'persistentCount' is the key used to store the value in localStorage, and 0 is the initial value.

Multi-Framework Persistent Counter Example

Let's implement a persistent counter using components from different frameworks. This counter will maintain its value across page reloads and will be accessible from any framework.

React Persistent Counter (Increment)

// src/components/ReactPersistentIncrement.jsx
import { useStore } from '@nanostores/react'
import { persistentCount, increment } from '../stores/persistentCounterStore'

export function ReactPersistentIncrement() {
  const count = useStore(persistentCount)

  return (
    <button onClick={increment}>
      React Increment: {count}
    </button>
  )
}

Vue Persistent Counter (Decrement)

<!-- src/components/VuePersistentDecrement.vue -->
<template>
  <button @click="decrement">
    Vue Decrement: {{ count }}
  </button>
</template>

<script setup>
import { useStore } from '@nanostores/vue'
import { persistentCount, decrement } from '../stores/persistentCounterStore'

const count = useStore(persistentCount)
</script>

Svelte Persistent Counter (Display)

<!-- src/components/SveltePersistentDisplay.svelte -->
<script>
import { persistentCount } from '../stores/persistentCounterStore'
</script>

<div>
  Svelte Display: {$persistentCount}
</div>

Astro Persistent Counter (Reset)

---
import { reset } from '../stores/persistentCounterStore'
---

<button id="reset-button">Astro Reset</button>

<script>
  import { persistentCount, reset } from '../stores/persistentCounterStore'

  document.getElementById('reset-button').addEventListener('click', reset)

  persistentCount.subscribe(value => {
    console.log('Persistent count updated:', value)
  })
</script>

Now, you can use these components together in an Astro page:

---
import ReactPersistentIncrement from '../components/ReactPersistentIncrement'
import VuePersistentDecrement from '../components/VuePersistentDecrement.vue'
import SveltePersistentDisplay from '../components/SveltePersistentDisplay.svelte'
---

<div>
  <h2>Persistent Counter Across Frameworks</h2>
  <ReactPersistentIncrement client:load />
  <VuePersistentDecrement client:load />
  <SveltePersistentDisplay client:load />
  <button id="reset-button">Astro Reset</button>
</div>

<script>
  import { persistentCount, reset } from '../stores/persistentCounterStore'

  document.getElementById('reset-button').addEventListener('click', reset)

  persistentCount.subscribe(value => {
    console.log('Persistent count updated:', value)
  })
</script>

This setup demonstrates a persistent counter where:

React handles the increment
Vue handles the decrement
Svelte displays the current count
Astro provides a reset button

The counter's value will persist across page reloads, showcasing the power of @nanostores/persistent in maintaining state.

Use Cases for Persistent State

Persistent state is particularly useful for:

User preferences (e.g., theme settings, language choices)
Partially completed forms (to prevent data loss on accidental page refresh)
Authentication tokens (for maintaining user sessions)
Local cache of frequently accessed data

By leveraging @nanostores/persistent, you can enhance user experience by maintaining important state data across page loads and browser sessions.

Best Practices and Tips

As you integrate Nanostores into your Astro projects, keep these best practices and tips in mind to make the most of this lightweight state management solution.

1. Choose the Right Store Type

Use atom for simple, single-value states.
Use map for object-like states with multiple properties.
Use computed for derived states that depend on other stores.
Use persistentAtom or persistentMap when you need state to persist across page reloads.

2. Keep Stores Small and Focused

Instead of creating large, monolithic stores, prefer smaller, more focused stores. This approach improves maintainability and performance by allowing for more granular updates.

// Prefer this:
const userProfile = map({ name: '', email: '' })
const userPreferences = map({ theme: 'light', language: 'en' })

// Over this:
const user = map({ name: '', email: '', theme: 'light', language: 'en' })

3. Use Computed Stores for Derived State

When you have state that depends on other pieces of state, use computed stores. This helps keep your state DRY (Don't Repeat Yourself) and ensures derived state is always up-to-date.

import { atom, computed } from 'nanostores'

const firstName = atom('John')
const lastName = atom('Doe')

const fullName = computed(
  [firstName, lastName],
  (first, last) => `${first} ${last}`
)

4. Leverage TypeScript for Type Safety

Nanostores has excellent TypeScript support. Use it to catch errors early and improve the developer experience.

import { atom } from 'nanostores'

interface User {
  id: number
  name: string
}

const currentUser = atom<User | null>(null)

5. Consider Performance in Large Applications

While Nanostores is lightweight, be mindful of performance in larger applications. Use the batched function to group multiple store updates together, reducing the number of re-renders.

import { atom, batched } from 'nanostores'

const count1 = atom(0)
const count2 = atom(0)

export const incrementBoth = batched(() => {
  count1.set(count1.get() + 1)
  count2.set(count2.get() + 1)
})

6. Keep Framework-Specific Logic Separate

When using Nanostores in a multi-framework Astro project, try to keep the core state logic framework-agnostic. This makes it easier to share state between different framework components.

// stores/themeStore.js
import { atom } from 'nanostores'

export const theme = atom('light')

export function toggleTheme() {
  theme.set(theme.get() === 'light' ? 'dark' : 'light')
}

// React component
import { useStore } from '@nanostores/react'
import { theme, toggleTheme } from '../stores/themeStore'

function ThemeToggle() {
  const currentTheme = useStore(theme)
  return <button onClick={toggleTheme}>{currentTheme}</button>
}

7. Use Persistent Stores Judiciously

While persistent stores are powerful, use them thoughtfully. Not all state needs to persist across sessions. Overusing persistent stores can lead to unexpected behavior and potential performance issues.

8. Debugging Nanostores

For easier debugging, you can use the onMount function to log state changes:

import { atom, onMount } from 'nanostores'

const count = atom(0)

if (import.meta.env.DEV) {
  onMount(count, () => {
    count.listen((value) => {
      console.log('Count changed:', value)
    })
  })
}

9. Clean Up Subscriptions

When using Nanostores in components that can be unmounted, make sure to clean up subscriptions to prevent memory leaks.

import { useEffect } from 'react'
import { count } from '../stores/countStore'

function Counter() {
  useEffect(() => {
    const unsubscribe = count.subscribe(() => {
      // Do something
    })
    return unsubscribe
  }, [])

  // Rest of the component
}

By following these best practices and tips, you'll be able to effectively manage state in your Astro projects using Nanostores, regardless of which frameworks you're integrating.

Conclusion

As we've explored throughout this article, Nanostores provides a powerful yet lightweight solution for state management in Astro projects, especially when working with multiple frameworks. Let's recap the key takeaways:

Versatility: Nanostores seamlessly integrates with Astro, React, Vue, Svelte and Solid, making it an ideal choice for multi-framework projects.
Simplicity: With its straightforward API, Nanostores offers a low learning curve while still providing robust state management capabilities.
Flexibility: From simple atomic stores to complex computed states and even persistent storage, Nanostores adapts to a wide range of state management needs.
Performance: Its lightweight nature ensures that Nanostores won't bloat your application, maintaining Astro's performance benefits.
Best Practices: By following the guidelines we've discussed, such as keeping stores small and focused, leveraging TypeScript, and using computed stores for derived state, you can create maintainable and efficient state management systems.

Nanostores shines in Astro's component islands architecture, allowing you to manage state across isolated interactive components efficiently. Whether you're building a simple website with a few interactive elements or a complex web application with multiple frameworks, Nanostores provides the tools you need to handle state effectively.

As you continue your journey with Astro and Nanostores, remember that the best way to learn is by doing. Experiment with different store types, try implementing shared state across frameworks, and explore the possibilities of persistent storage. Each project will bring new challenges and opportunities to refine your state management skills.

Stay tuned for the next articles in our "Nanostores in Astro: A Multi-Framework Adventure" series, where we'll dive deeper into practical applications and advanced techniques for state management in Astro projects.

Further Resources

To deepen your understanding of Nanostores and its use in Astro projects, check out these valuable resources:

Happy coding, and may your Astro projects be ever stateful and performant!

State Management in Astro: A Deep Dive into Nanostores

Table of contents