Migration Guide

Migrate to the latest version of TanStack Store and learn about breaking changes

Overview

This guide helps you migrate between major versions of TanStack Store and understand breaking changes. TanStack Store follows semantic versioning, so major version bumps indicate breaking changes.

Migrating to v0.9.x

Breaking Changes in v0.9.0

Version 0.9.0 introduced significant API changes to improve ergonomics and leverage a new reactive core based on alien-signals.

Major API Changes

Version 0.9.0 is a major rewrite with breaking changes. Review this section carefully before upgrading.

Class Constructors → Factory Functions

The biggest change is moving from class constructors to factory functions:

// ❌ Old API (v0.8.x)
import { Store, Derived, Effect } from '@tanstack/store'

const store = new Store(initialValue)
const derived = new Derived(() => store.state * 2)
const effect = new Effect(() => {
  console.log(store.state)
})

// ✅ New API (v0.9.x)
import { createStore } from '@tanstack/store'

const store = createStore(initialValue)
const derived = createStore(() => store.state * 2)
const subscription = store.subscribe(() => {
  console.log(store.state)
})

Derived Stores

The Derived class has been replaced with computed createStore() calls:

// ❌ Old API
import { Store, Derived } from '@tanstack/store'

const count = new Store(10)
const doubled = new Derived(() => count.state * 2)

// ✅ New API
import { createStore } from '@tanstack/store'

const count = createStore(10)
const doubled = createStore(() => count.state * 2)

The new API is simpler: if you pass a function to createStore, it creates a derived (readonly) store. If you pass a value, it creates a mutable store.

Effects → Subscriptions

The Effect class has been removed in favor of the subscribe() method:

// ❌ Old API
import { Store, Effect } from '@tanstack/store'

const store = new Store(0)
const effect = new Effect(() => {
  console.log('Count:', store.state)
})

// Cleanup
effect.destroy()

// ✅ New API
import { createStore } from '@tanstack/store'

const store = createStore(0)
const { unsubscribe } = store.subscribe((value) => {
  console.log('Count:', value)
})

// Cleanup
unsubscribe()

Type Changes

Import types from the main package:

// ❌ Old API
import { Store, StoreInstance } from '@tanstack/store'

const store: StoreInstance<number> = new Store(0)

// ✅ New API
import { createStore, Store, ReadonlyStore } from '@tanstack/store'

// Mutable store
const store: Store<number> = createStore(0)

// Readonly store
const derived: ReadonlyStore<number> = createStore(() => store.state * 2)

Observable Interop

The subscription API now follows the Observable spec more closely:

// ❌ Old API
effect.subscribe({
  onNext: (value) => console.log(value),
  onError: (error) => console.error(error),
})

// ✅ New API
store.subscribe({
  next: (value) => console.log(value),
  error: (error) => console.error(error),
  complete: () => console.log('complete'),
})

// Or use the simpler callback form
store.subscribe((value) => console.log(value))

Step-by-Step Migration

1. Update Dependencies

   Update your package.json to the latest version:

   npm install @tanstack/store@latest
   # or
   yarn add @tanstack/store@latest
   # or
   pnpm add @tanstack/store@latest
   
2. Replace Store Constructor Calls

   Find and replace all new Store() with createStore():

   // Before
   const store = new Store(initialValue)
   
   // After
   const store = createStore(initialValue)
   
3. Replace Derived Stores

   Replace new Derived() with derived createStore():

   // Before
   const derived = new Derived(() => store.state * 2)
   
   // After
   const derived = createStore(() => store.state * 2)
   
4. Replace Effects with Subscriptions

   Replace new Effect() with store.subscribe():

   // Before
   const effect = new Effect(() => {
     console.log(store.state)
   })
   effect.destroy() // cleanup
   
   // After
   const { unsubscribe } = store.subscribe((value) => {
     console.log(value)
   })
   unsubscribe() // cleanup
   
5. Update Type Imports

   Update your type imports:

   // Before
   import { Store, StoreInstance } from '@tanstack/store'
   
   // After
   import { createStore, Store, ReadonlyStore } from '@tanstack/store'
   
6. Test Your Application

   Run your test suite to ensure everything works:

   npm test
   

Migrating from Other State Libraries

From Redux

TanStack Store can replace Redux with less boilerplate:

// Redux
import { createStore } from 'redux'

const reducer = (state = { count: 0 }, action) => {
  switch (action.type) {
    case 'INCREMENT':
      return { count: state.count + 1 }
    case 'DECREMENT':
      return { count: state.count - 1 }
    default:
      return state
  }
}

const store = createStore(reducer)
store.dispatch({ type: 'INCREMENT' })

// TanStack Store
import { createStore } from '@tanstack/store'

const store = createStore({ count: 0 })

const increment = () => {
  store.setState((s) => ({ ...s, count: s.count + 1 }))
}

const decrement = () => {
  store.setState((s) => ({ ...s, count: s.count - 1 }))
}

increment()

From Zustand

TanStack Store has a similar API to Zustand:

// Zustand
import { create } from 'zustand'

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}))

// TanStack Store
import { createStore } from '@tanstack/store'
import { useStore } from '@tanstack/react-store'

const store = createStore({ count: 0 })

const increment = () => {
  store.setState((s) => ({ ...s, count: s.count + 1 }))
}

function Component() {
  const state = useStore(store)
  return <div onClick={increment}>{state.count}</div>
}

From Jotai

TanStack Store’s atoms work similarly to Jotai:

// Jotai
import { atom, useAtom } from 'jotai'

const countAtom = atom(0)
const doubledAtom = atom((get) => get(countAtom) * 2)

// TanStack Store
import { createAtom } from '@tanstack/store'
import { useStore } from '@tanstack/react-store'

const countAtom = createAtom(0)
const doubledAtom = createAtom(() => countAtom.get() * 2)

function Component() {
  const count = useStore(countAtom)
  const doubled = useStore(doubledAtom)
  return <div>{count} × 2 = {doubled}</div>
}

From MobX

TanStack Store provides similar reactivity with less boilerplate:

// MobX
import { makeObservable, observable, computed, action } from 'mobx'
import { observer } from 'mobx-react-lite'

class Store {
  count = 0

  constructor() {
    makeObservable(this, {
      count: observable,
      doubled: computed,
      increment: action,
    })
  }

  get doubled() {
    return this.count * 2
  }

  increment() {
    this.count++
  }
}

// TanStack Store
import { createStore } from '@tanstack/store'
import { useStore } from '@tanstack/react-store'

const countStore = createStore(0)
const doubledStore = createStore(() => countStore.state * 2)

const increment = () => {
  countStore.setState((c) => c + 1)
}

function Component() {
  const doubled = useStore(doubledStore)
  return <button onClick={increment}>{doubled}</button>
}

Common Migration Issues

Issue: Cannot call setState on readonly store

// ❌ Error: Property 'setState' does not exist
const derived = createStore(() => source.state * 2)
derived.setState(10)

Solution: Derived stores (created with a function) are readonly. Update the source store instead:

// ✅ Correct: Update the source
const source = createStore(5)
const derived = createStore(() => source.state * 2)
source.setState(10) // derived automatically updates to 20

Issue: Subscriptions fire immediately

Subscriptions fire once immediately on creation (this is intentional):

let count = 0
store.subscribe(() => {
  count++ // Fires immediately, then on each update
})
console.log(count) // 1 (not 0!)

Solution: Handle the initial call if needed:

let isFirst = true
store.subscribe(() => {
  if (isFirst) {
    isFirst = false
    return
  }
  // Handle subsequent updates
})

Issue: Type errors with generic stores

// ❌ Type error
const store = createStore<User>(null)

Solution: Use union types for nullable values:

// ✅ Correct
const store = createStore<User | null>(null)

Framework-Specific Migration

React

npm install @tanstack/react-store

import { createStore } from '@tanstack/store'
import { useStore } from '@tanstack/react-store'

const store = createStore(0)

function Component() {
  const count = useStore(store)
  return <div>{count}</div>
}

Vue

npm install @tanstack/vue-store

import { createStore } from '@tanstack/store'
import { useStore } from '@tanstack/vue-store'

const store = createStore(0)

export default {
  setup() {
    const count = useStore(store)
    return { count }
  },
}

Svelte

npm install @tanstack/svelte-store

import { createStore } from '@tanstack/store'
import { useStore } from '@tanstack/svelte-store'

const store = createStore(0)
const count = useStore(store)

<script>
  import { count } from './store'
</script>

<div>{$count}</div>

Version History

v0.9.1 (Latest)

• Fix: Derived createStore now returns readonly store (#278)

v0.9.0

• Breaking: new Store() → createStore() (#265)
• Breaking: new Derived() → derived createStore()
• Breaking: new Effect() → store.subscribe()
• New: Uses alien-signals for efficient reactivity

v0.8.1

• Fix: Issues with Derived Fields not Retriggering (#274)

Getting Help

If you encounter migration issues:

GitHub Discussions

Ask questions and get help from the community

GitHub Issues

Report bugs or migration problems

Discord

Join the TanStack Discord for real-time help

Twitter

Follow @tanstack for updates

Next Steps

• Review Type Safety for TypeScript best practices
• Learn about Performance optimization
• Explore Async Atoms for async data