Quickstart

Build your first TanStack Store in 5 minutes with step-by-step examples

Quickstart Guide

Get up and running with TanStack Store in minutes. This guide walks you through creating your first store and integrating it with your framework.

Your First Store

Let’s create a simple counter application to demonstrate the core concepts.

1. Install TanStack Store

   First, install the appropriate package for your framework:

   React

   npm install @tanstack/react-store
   
2. Create a Store

   Create a store to manage your application state. Stores can be created inside or outside of components:

   React

   import { Store } from '@tanstack/react-store'
   
   // Create a store with initial state
   export const store = new Store({
     dogs: 0,
     cats: 0,
   })
   

   Stores can be instantiated outside of components and shared across your entire application.

3. Read Store State

   Use the framework adapter’s hook/composable to read from the store. Only the specific data you select will trigger re-renders:

   React

   import { useStore } from '@tanstack/react-store'
   import { store } from './store'
   
   function Display({ animal }: { animal: 'dogs' | 'cats' }) {
     // This component only re-renders when state[animal] changes
     const count = useStore(store, (state) => state[animal])
     
     return <div>{animal}: {count}</div>
   }
   

   The selector function enables fine-grained subscriptions. Components only re-render when their selected data changes, not when any part of the store updates.

4. Update Store State

   Update the store state using setState. Updates are immutable and trigger subscriptions:

   React

   import { store } from './store'
   
   function Increment({ animal }: { animal: 'dogs' | 'cats' }) {
     const updateCount = () => {
       store.setState((state) => ({
         ...state,
         [animal]: state[animal] + 1,
       }))
     }
   
     return (
       <button onClick={updateCount}>
         My Friend Likes {animal}
       </button>
     )
   }
   
5. Compose Your Application

   Bring it all together in your application:

   React

   function App() {
     return (
       <div>
         <h1>How many of your friends like cats or dogs?</h1>
         <p>
           Press one of the buttons to add a counter of how many of your friends
           like cats or dogs
         </p>
         <Increment animal="dogs" />
         <Display animal="dogs" />
         <Increment animal="cats" />
         <Display animal="cats" />
       </div>
     )
   }
   

Core Concepts

Now that you’ve built your first store, let’s explore the key concepts:

Creating Stores

You can create stores with values or functions:

import { createStore } from '@tanstack/store'

// Store with a value
const countStore = createStore(0)

// Store with an object
const userStore = createStore({
  name: 'John',
  age: 30,
})

Derived Stores

Create stores that compute values from other stores:

const count = createStore(5)

// Derived store automatically updates when count changes
const double = createStore(() => count.state * 2)

console.log(double.state) // 10
count.setState(() => 10)
console.log(double.state) // 20

You can access the previous computed value:

const count = createStore(1)

const sum = createStore<number>((prev) => {
  return count.state + (prev ?? 0)
})

console.log(sum.state) // 1
count.setState(() => 2)
console.log(sum.state) // 3

Subscriptions

Subscribe to store changes for side effects:

const count = createStore(0)

const { unsubscribe } = count.subscribe((state) => {
  console.log('Count changed to:', state)
})

count.setState(() => 5) // Logs: "Count changed to: 5"

// Cleanup
unsubscribe()

Batched Updates

Batch multiple updates to trigger subscribers only once:

import { batch } from '@tanstack/store'

const countStore = createStore(0)

// Subscribers will only trigger once with the final value
batch(() => {
  countStore.setState(() => 1)
  countStore.setState(() => 2)
})

console.log(countStore.state) // 2

Framework-Specific Examples

React Complete Example

Here’s the complete React example from the source code:

import ReactDOM from 'react-dom/client'
import { Store, useStore } from '@tanstack/react-store'

// Create store outside of components
export const store = new Store({
  dogs: 0,
  cats: 0,
})

// Display component with fine-grained subscriptions
const Display = ({ animal }: { animal: 'dogs' | 'cats' }) => {
  const count = useStore(store, (state) => state[animal])
  return <div>{`${animal}: ${count}`}</div>
}

// Update helper
const updateState = (animal: 'dogs' | 'cats') => {
  store.setState((state) => ({
    ...state,
    [animal]: state[animal] + 1,
  }))
}

// Increment component
const Increment = ({ animal }: { animal: 'dogs' | 'cats' }) => (
  <button onClick={() => updateState(animal)}>
    My Friend Likes {animal}
  </button>
)

function App() {
  return (
    <div>
      <h1>How many of your friends like cats or dogs?</h1>
      <Increment animal="dogs" />
      <Display animal="dogs" />
      <Increment animal="cats" />
      <Display animal="cats" />
    </div>
  )
}

const root = ReactDOM.createRoot(document.getElementById('root')!)
root.render(<App />)

Vue Complete Example

<!-- store.ts -->
<script lang="ts">
import { Store } from '@tanstack/vue-store'

export const store = new Store({
  dogs: 0,
  cats: 0,
})

export function updateState(animal: 'dogs' | 'cats') {
  store.setState((state) => ({
    ...state,
    [animal]: state[animal] + 1,
  }))
}
</script>

<!-- Display.vue -->
<script setup>
import { useStore } from '@tanstack/vue-store'
import { store } from './store'

const props = defineProps({ animal: String })
const count = useStore(store, (state) => state[props.animal])
</script>

<template>
  <div>{{ animal }}: {{ count }}</div>
</template>

<!-- App.vue -->
<script setup>
import Increment from './Increment.vue'
import Display from './Display.vue'
</script>

<template>
  <h1>How many of your friends like cats or dogs?</h1>
  <Increment animal="dogs" />
  <Display animal="dogs" />
  <Increment animal="cats" />
  <Display animal="cats" />
</template>

Solid Complete Example

import { Store, useStore } from '@tanstack/solid-store'
import { render } from 'solid-js/web'

// Create store outside of components
export const store = new Store({
  cats: 0,
  dogs: 0,
})

// Display component
export const Display = (props: { animals: 'dogs' | 'cats' }) => {
  const count = useStore(store, (state) => state[props.animals])
  return <div>{props.animals}: {count()}</div>
}

// Button component
export const Button = (props: { animals: 'dogs' | 'cats' }) => {
  return (
    <button
      onClick={() => {
        store.setState((state) => ({
          ...state,
          [props.animals]: state[props.animals] + 1,
        }))
      }}
    >
      Increment
    </button>
  )
}

const App = () => {
  return (
    <div>
      <h1>How many of your friends like cats or dogs?</h1>
      <Button animals="dogs" />
      <Display animals="dogs" />
      <Button animals="cats" />
      <Display animals="cats" />
    </div>
  )
}

const root = document.getElementById('root')
render(() => <App />, root!)

Next Steps

You’ve successfully created your first TanStack Store! Here’s what to explore next:

Core Concepts

Deep dive into stores, atoms, and reactivity

API Reference

Explore the complete API documentation

Framework Guides

Framework-specific patterns and best practices

Examples

Browse example applications and patterns