Type Safety

Overview

TanStack Store is built with TypeScript from the ground up, providing excellent type inference and type safety throughout your application. This guide covers TypeScript patterns, generic types, and best practices for maintaining type safety.

Type Inference

Automatic Type Inference

TanStack Store automatically infers types from initial values:

import { createStore } from '@tanstack/store'

// Type is inferred as Store<number>
const countStore = createStore(0)

// ✅ Type-safe: accepts number
countStore.setState(10)

// ❌ Type error: Type 'string' is not assignable to type 'number'
countStore.setState('hello')

Derived Store Type Inference

Derived stores automatically infer their return type:

const countStore = createStore(10)

// Type is inferred as ReadonlyStore<number>
const doubledStore = createStore(() => countStore.state * 2)

// Type is inferred as ReadonlyStore<string>
const messageStore = createStore(() => {
  const count = countStore.state
  return `Count is ${count}`
})

Explicit Type Annotations

When to Use Type Annotations

Use explicit type annotations when:

The initial value is null or undefined
You want to enforce a specific interface
Working with complex or nested types

interface User {
  id: number
  name: string
  email: string
}

// Explicit type annotation for nullable values
const userStore = createStore<User | null>(null)

// Type annotation for complex objects
const stateStore = createStore<User>({
  id: 1,
  name: 'John Doe',
  email: 'john@example.com',
})

Type-Safe State Updates

Function Updaters

Function updaters provide the previous state with full type safety:

interface Counter {
  count: number
  lastUpdated: Date
}

const counterStore = createStore<Counter>({
  count: 0,
  lastUpdated: new Date(),
})

// ✅ Type-safe: prev is typed as Counter
counterStore.setState((prev) => ({
  ...prev,
  count: prev.count + 1,
  lastUpdated: new Date(),
}))

// ❌ Type error: Property 'invalid' does not exist on type 'Counter'
counterStore.setState((prev) => ({
  ...prev,
  invalid: true,
}))

Direct Value Updates

Direct value updates are also type-checked:

const nameStore = createStore('John')

// ✅ Type-safe
nameStore.setState('Jane')

// ❌ Type error
nameStore.setState(123)

Generic Types and Atoms

Generic Atom Creation

Create reusable atom factories with generics:

import { createAtom, ReadonlyAtom } from '@tanstack/store'

function createLoadingAtom<T>(
  initialValue: T
): {
  dataAtom: ReadonlyAtom<T>
  loadingAtom: ReadonlyAtom<boolean>
} {
  const atom = createAtom(initialValue)
  const loadingAtom = createAtom(false)

  return {
    dataAtom: atom,
    loadingAtom: loadingAtom,
  }
}

// Usage with full type inference
const { dataAtom, loadingAtom } = createLoadingAtom<string[]>([])

Constrained Generics

Use type constraints for more specific generic types:

interface Entity {
  id: number
}

function createEntityStore<T extends Entity>(initialEntity: T) {
  const store = createStore(initialEntity)

  const updateEntity = (updates: Partial<T>) => {
    store.setState((prev) => ({
      ...prev,
      ...updates,
    }))
  }

  return { store, updateEntity }
}

interface User extends Entity {
  name: string
  email: string
}

const { store, updateEntity } = createEntityStore<User>({
  id: 1,
  name: 'John',
  email: 'john@example.com',
})

// ✅ Type-safe updates
updateEntity({ name: 'Jane' })

// ❌ Type error: 'invalid' does not exist in type 'User'
updateEntity({ invalid: true })

Working with Union Types

Discriminated Unions

Use discriminated unions for type-safe state machines:

type RequestState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: string }

const requestStore = createStore<RequestState<User>>({
  status: 'idle',
})

// Type-safe state transitions
requestStore.setState({ status: 'loading' })

requestStore.setState({
  status: 'success',
  data: { id: 1, name: 'John', email: 'john@example.com' },
})

requestStore.setState({
  status: 'error',
  error: 'Failed to fetch user',
})

// Type narrowing in derived stores
const userDataStore = createStore(() => {
  const state = requestStore.state
  if (state.status === 'success') {
    // TypeScript knows state.data is available here
    return state.data
  }
  return null
})

Type Safety with Subscriptions

Typed Observers

Subscriptions receive properly typed values:

interface AppState {
  count: number
  message: string
}

const appStore = createStore<AppState>({
  count: 0,
  message: 'Hello',
})

// value is typed as AppState
appStore.subscribe((value) => {
  console.log(value.count) // ✅ Type-safe
  console.log(value.invalid) // ❌ Type error
})

// Observer pattern with full typing
appStore.subscribe({
  next: (value: AppState) => {
    console.log('State updated:', value)
  },
  error: (error: unknown) => {
    console.error('Error:', error)
  },
})

Advanced Type Patterns

Readonly vs Mutable Stores

TanStack Store distinguishes between mutable and readonly stores at the type level:

import { Store, ReadonlyStore } from '@tanstack/store'

// Mutable store (created with initial value)
const mutableStore = createStore(0)
type MutableType = typeof mutableStore // Store<number>
mutableStore.setState(10) // ✅ Has setState method

// Readonly store (created with function)
const readonlyStore = createStore(() => mutableStore.state * 2)
type ReadonlyType = typeof readonlyStore // ReadonlyStore<number>
// readonlyStore.setState(10) // ❌ Type error: Property 'setState' does not exist

Type Guards for Complex States

Create type guards for complex state shapes:

type AsyncState<T, E = Error> =
  | { status: 'pending' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: E }

function isSuccess<T, E>(
  state: AsyncState<T, E>
): state is { status: 'success'; data: T } {
  return state.status === 'success'
}

function isError<T, E>(
  state: AsyncState<T, E>
): state is { status: 'error'; error: E } {
  return state.status === 'error'
}

const asyncStore = createStore<AsyncState<User>>({
  status: 'pending',
})

const state = asyncStore.state

if (isSuccess(state)) {
  // TypeScript knows state.data is available
  console.log(state.data.name)
}

if (isError(state)) {
  // TypeScript knows state.error is available
  console.error(state.error)
}

Mapped Types for Store Collections

Create type-safe collections of stores:

type StoreCollection<T> = {
  [K in keyof T]: Store<T[K]>
}

interface FormFields {
  username: string
  email: string
  age: number
}

function createFormStores<T extends Record<string, any>>(
  initialValues: T
): StoreCollection<T> {
  const stores = {} as StoreCollection<T>

  for (const key in initialValues) {
    stores[key] = createStore(initialValues[key])
  }

  return stores
}

const formStores = createFormStores<FormFields>({
  username: '',
  email: '',
  age: 0,
})

// ✅ Fully typed
formStores.username.setState('john_doe')
formStores.age.setState(25)

// ❌ Type error
formStores.username.setState(123)

NoInfer for Improved Type Inference

TanStack Store uses TypeScript’s NoInfer utility type internally to prevent unintended type inference:

// From source: packages/store/src/store.ts:6
constructor(getValue: (prev?: NoInfer<T>) => T)

// This prevents TypeScript from inferring T from the function parameter
// ensuring the type flows from the return value instead

This pattern ensures that:

Generic types are inferred correctly
Function parameters don’t widen the inferred type
Return types take precedence in type inference

Type Testing

Test your types using TypeScript’s type checking:

import { expectType } from 'vitest'
import { createStore, Store, ReadonlyStore } from '@tanstack/store'

// Test that types are inferred correctly
const numStore = createStore(0)
expectType<Store<number>>(numStore)

const strStore = createStore('hello')
expectType<Store<string>>(strStore)

// Test readonly stores
const derivedStore = createStore(() => numStore.state * 2)
expectType<ReadonlyStore<number>>(derivedStore)

// Type error tests can be done with @ts-expect-error
// @ts-expect-error - Cannot call setState on readonly store
derivedStore.setState(10)

Best Practices

Use Type Inference When Possible

Let TypeScript infer types from your initial values. This reduces boilerplate and keeps your code maintainable:

// ✅ Good: Type inferred as Store<number>
const count = createStore(0)

// ❌ Unnecessary: Redundant type annotation
const count = createStore<number>(0)

Annotate Complex Types

Use explicit type annotations for complex interfaces or when the initial value doesn’t fully represent the type:

// ✅ Good: Clear interface definition
interface AppState {
  user: User | null
  settings: Settings
}
const appStore = createStore<AppState>(initialState)

Use Discriminated Unions for State Machines

Leverage TypeScript’s discriminated unions for type-safe state transitions:

type State =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: Data }
  | { status: 'error'; error: Error }

Create Type Guards for Complex Logic

Use type guards to narrow types and improve type safety:

function isLoaded<T>(state: State<T>): state is { data: T } {
  return 'data' in state
}

Common Type Errors and Solutions

Error: Type is not assignable

// ❌ Error: Type 'string' is not assignable to type 'number'
const store = createStore(0)
store.setState('hello')

// ✅ Solution: Ensure the value matches the store's type
store.setState(42)

Error: Property does not exist on type

interface User {
  name: string
}

const userStore = createStore<User>({ name: 'John' })

// ❌ Error: Property 'age' does not exist on type 'User'
userStore.setState({ name: 'Jane', age: 30 })

// ✅ Solution: Extend the interface or use a different type
interface ExtendedUser extends User {
  age: number
}

Next Steps

Explore Performance optimization with selectors
Learn about Async Atoms for async data
See createStore API for complete type signatures

Get Started

Core Concepts

Framework Guides

Guides

Overview

Type Inference

Automatic Type Inference

Derived Store Type Inference

Explicit Type Annotations

When to Use Type Annotations

Type-Safe State Updates

Function Updaters

Direct Value Updates

Generic Types and Atoms

Generic Atom Creation

Constrained Generics

Working with Union Types

Discriminated Unions

Type Safety with Subscriptions

Typed Observers

Advanced Type Patterns

Readonly vs Mutable Stores

Type Guards for Complex States

Mapped Types for Store Collections

NoInfer for Improved Type Inference

Type Testing

Best Practices

Common Type Errors and Solutions

Error: Type is not assignable

Error: Property does not exist on type

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Framework Guides

Guides

Documentation Index

​Overview

​Type Inference

​Automatic Type Inference

​Derived Store Type Inference

​Explicit Type Annotations

​When to Use Type Annotations

​Type-Safe State Updates

​Function Updaters

​Direct Value Updates

​Generic Types and Atoms

​Generic Atom Creation

​Constrained Generics

​Working with Union Types

​Discriminated Unions

​Type Safety with Subscriptions

​Typed Observers

​Advanced Type Patterns

​Readonly vs Mutable Stores

​Type Guards for Complex States

​Mapped Types for Store Collections

​NoInfer for Improved Type Inference

​Type Testing

​Best Practices

​Common Type Errors and Solutions

​Error: Type is not assignable

​Error: Property does not exist on type

​Next Steps

Build docs developers (and LLMs) love

Overview

Type Inference

Automatic Type Inference

Derived Store Type Inference

Explicit Type Annotations

When to Use Type Annotations

Type-Safe State Updates

Function Updaters

Direct Value Updates

Generic Types and Atoms

Generic Atom Creation

Constrained Generics

Working with Union Types

Discriminated Unions

Type Safety with Subscriptions

Typed Observers

Advanced Type Patterns

Readonly vs Mutable Stores

Type Guards for Complex States

Mapped Types for Store Collections

NoInfer for Improved Type Inference

Type Testing

Best Practices

Common Type Errors and Solutions

Error: Type is not assignable

Error: Property does not exist on type

Next Steps