Stores outside components#

Export the plain accessor alongside the React Hook:

import { defineStore } from 'pinia-react'

export const { useAuthStore, getAuthStore } = defineStore('auth', {
  state: () => ({ isAuthenticated: false }),
  actions: {
    logout() { this.isAuthenticated = false },
  },
})

In a single-root browser application, initialize with createPinia() before calling getAuthStore(). The accessor is an ordinary function, not a Hook:

import { getAuthStore } from './stores/auth'

export function logout() {
  getAuthStore().logout()
}

Multiple instances and services#

Keep the Pinia instance at the application boundary and pass it explicitly to external code:

import { createPinia, PiniaProvider } from 'pinia-react'
import type { Pinia } from 'pinia-react'
import { getAuthStore } from './stores/auth'

function logout(pinia: Pinia) {
  getAuthStore(pinia).logout()
}

// Browser bootstrap: retain this instance for this mounted application.
const pinia = createPinia()
const application = (
  <PiniaProvider pinia={pinia}>
    <button onClick={() => logout(pinia)}>Log out</button>
  </PiniaProvider>
)

Both the named accessor and generic getStore(pinia?) accept an explicit instance without changing active Pinia. A supplied Provider instance must be initialized by its owner; do not combine it with Provider plugins or initialStores. It remains the instance for that Provider lifetime.

An optional Hook string is a diagnostic label, not an instance argument. Multiple Providers can coexist, but external services cannot depend on whichever instance became active last. Pass the instance or close over it in application-level services. Cross-Store Actions need the same explicit dependency before and after await; see Actions.

Requests and SSR#

For ordinary request services, retain one local instance per request and pass it to every accessor, including after async work. createPinia() still sets global active Pinia for compatibility; never use that global as a request container or keep request Stores at module scope.

For Next.js App Router, Server Components fetch plain JSON and pass initialStores to a Client Provider. They do not call client Store APIs. Transfer snapshots, not Pinia instances, Stores, Proxies, or Actions. Server Provider rendering isolates its instance without setting global active Pinia. See Next.js.

Testing and final cleanup#

Use a fresh instance per test and register plugins before creating Stores. See testing real Stores.

The final application owner may release an instance when it will never be reused:

import { createPinia, disposePinia } from 'pinia-react'

const pinia = createPinia()
try {
  getAuthStore(pinia).logout()
} finally {
  disposePinia(pinia)
}

Unmount dependent components first. disposePinia(pinia) is synchronous, irreversible, and idempotent. It closes Stores, clears subscriptions and Getter dependencies, and runs registered plugin cleanup. If this instance is active, active Pinia is cleared; a different active instance is unchanged. Storage and Cookies are not deleted.

Old Store references, captured methods, and Action reads/writes after await fail after disposal. Network requests and arbitrary Promises are not cancelled automatically; the resource owner must arrange cancellation. Extracted plain values and snapshots cannot be revoked. Cleanup continues after a callback fails and reports an AggregateError afterward.

Provider unmount does not dispose automatically. Do not put irreversible disposal in an Effect cleanup: Strict Mode replays Effects with the same instance. Retain the explicit instance at the application boundary, unmount the tree, then dispose that exact instance. There is no public per-Store disposal method.

A plugin installation failure releases resources registered by that installation and restores its initial snapshot for retry. It does not undo completed storage writes, callbacks, or changes to other Stores. See plugin cleanup.