Pinia

https://pinia.vuejs.org/
Admin
Pinia is an intuitive, type-safe, extensible, and modular store for Vue.js, designed to simplify...
Tokens:54,174
Snippets:585
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install store plugins in tests with createApp and pinia.use

Source: https://pinia.vuejs.org/cookbook/testing.html

Shows how to make store plugins available in unit tests by creating an empty Vue app and installing the pinia instance with the plugin. The app is created once outside beforeEach, and each test gets a fresh pinia with the plugin.

```TypeScript
import { setActivePinia, createPinia } from 'pinia'
import { createApp } from 'vue'
import { somePlugin } from '../src/stores/plugin'

// same code as above...

// you don't need to create one app per test
const app = createApp({})
beforeEach(() => {
  const pinia = createPinia().use(somePlugin)
  app.use(pinia)
  setActivePinia(pinia)
})
```

--------------------------------

### Install @pinia/testing

Source: https://pinia.vuejs.org/cookbook/testing.html

Install the testing package as a development dependency.

```shell
npm i -D @pinia/testing
```

--------------------------------

### Define custom options with setup syntax

Source: https://pinia.vuejs.org/core-concepts/plugins.html

When using the setup syntax for defineStore, custom options are passed as the third argument.

```javascript
defineStore(
  'search',
  () => {
    // ...
  },
  {
    // this will be read by a plugin later on
    debounce: {
      // debounce the action searchContacts by 300ms
      searchContacts: 300,
    },
  }
)
```

--------------------------------

### Install @pinia/nuxt

Source: https://pinia.vuejs.org/cookbook/migration-v1-v2.html

Install the dedicated Nuxt package for Pinia.

```bash
npm i @pinia/nuxt
```

--------------------------------

### Using useStore in setup

Source: https://pinia.vuejs.org/ssr

Pinia automatically detects the application context when calling useStore inside setup functions.

```vue
<script setup>
// this works because pinia knows what application is running inside of
// `setup`
const main = useMainStore()
</script>
```

--------------------------------

### Nested Setup Stores

Source: https://pinia.vuejs.org/cookbook/composing-stores.html

Shows how to use another store at the top of a setup store function.

```ts
import { defineStore } from 'pinia'
import { useUserStore } from './user'
import { apiPurchase } from './api'

export const useCartStore = defineStore('cart', () => {
  const user = useUserStore()
  const list = ref([])

  const summary = computed(() => {
    return `Hi ${user.name}, you have ${list.value.length} items in your cart. It costs ${price.value}.`
  })

  function purchase() {
    return apiPurchase(user.id, list.value)
  }

  return { list, summary, purchase }
})
```

--------------------------------

### Using setup() in Options API

Source: https://pinia.vuejs.org/core-concepts/getters.html

Use the setup() hook to expose a store to an Options API component. This is intended as a migration step and should not be used to mix API styles long-term.

```vue
<script>
import { useCounterStore } from '../stores/counter'

export default defineComponent({
  setup() {
    const counterStore = useCounterStore()

    // **only return the whole store** instead of destructuring
    return { counterStore }
  },
  computed: {
    quadrupleCounter() {
      return this.counterStore.doubleCount * 2
    },
  },
})
</script>
```

--------------------------------

### Initialize Pinia before calling useStore

Source: https://pinia.vuejs.org/core-concepts/outside-component-usage.html

Demonstrates that calling useStore() before the pinia instance is created and installed via app.use(pinia) will fail, while calling it after installation succeeds.

```javascript
import { useUserStore } from '@/stores/user'
import { createPinia } from 'pinia'
import { createApp } from 'vue'
import App from './App.vue'

// ❌  fails because it's called before the pinia is created
const userStore = useUserStore()

const pinia = createPinia()
const app = createApp(App)
app.use(pinia)

// ✅ works because the pinia instance is now active
const userStore = useUserStore()
```

--------------------------------

### Use actions with setup() in Options API

Source: https://pinia.vuejs.org/core-concepts/actions.html

Utilize the setup() hook to access the store directly within an Options API component without needing map helpers.

```vue
<script>
import { useCounterStore } from '../stores/counter'

export default defineComponent({
  setup() {
    const counterStore = useCounterStore()

    return { counterStore }
  },
  methods: {
    incrementAndPrint() {
      this.counterStore.increment()
      console.log('New Count:', this.counterStore.count)
    },
  },
})
</script>
```

--------------------------------

### install(app)

Source: https://pinia.vuejs.org/api/pinia/interfaces/Pinia.html

Installs the Pinia instance into a Vue application. This method is called when the Pinia plugin is used with the app.

```APIDOC
## install(app)

### Description
Installs the Pinia instance into a Vue application. This method is called when the Pinia plugin is used with the app.

### Method
install

### Parameters
#### Parameters
- **app** (App) - Required - The Vue application instance.

### Returns
`void`
```

--------------------------------

### Add a static property to all stores with pinia.use()

Source: https://pinia.vuejs.org/core-concepts/plugins.html

The simplest plugin example: returns an object with a 'secret' property added to every store created after installation. Useful for adding global objects like router, modal, or toast managers.

```javascript
import { createPinia } from 'pinia'

// add a property named `secret` to every store that is created
// after this plugin is installed this could be in a different file
function SecretPiniaPlugin() {
  return { secret: 'the cake is a lie' }
}

const pinia = createPinia()
// give the plugin to pinia
pinia.use(SecretPiniaPlugin)

// in another file
const store = useStore()
store.secret // 'the cake is a lie'
```

--------------------------------

### Install Pinia with bun

Source: https://pinia.vuejs.org/getting-started.html

Use bun to add the pinia package to your project.

```bash
bun add pinia
```

--------------------------------

### Install latest 0.x version

Source: https://pinia.vuejs.org/cookbook/migration-v1-v2.html

Ensure you are running the latest 0.x version to identify deprecations before upgrading.

```shell
npm i 'pinia@^0.x.x'
# or with yarn
yarn add 'pinia@^0.x.x'
```

--------------------------------

### Define a Pinia store with Setup function

Source: https://pinia.vuejs.org/introduction.html

Define a store using a function similar to a component setup() for advanced use cases.

```javascript
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  function increment() {
    count.value++
  }

  return { count, increment }
})
```

--------------------------------

### $onAction Method

Source: https://pinia.vuejs.org/api/pinia/interfaces/StoreWithState.html

Setups a callback to be called every time an action is about to get invoked.

```typescript
$onAction(callback, detached?): () => void;
```

```typescript
(): void;
```

```javascript
store.$onAction(({ after, onError }) => {
 // Here you could share variables between all of the hooks as well as
 // setting up watchers and clean them up
 after((resolvedValue) => {
   // can be used to cleanup side effects
.  // `resolvedValue` is the value returned by the action, if it's a
.  // Promise, it will be the resolved value instead of the Promise
 })
 onError((error) => {
   // can be used to pass up errors
 })
})
```

--------------------------------

### Hydrate method example

Source: https://pinia.vuejs.org/api/pinia/interfaces/DefineStoreOptionsInPlugin.html

Example showing how to manually hydrate custom refs like useLocalStorage in the hydrate method.

```typescript
const useStore = defineStore('main', {
  state: () => ({
    n: useLocalStorage('key', 0)
  }),
  hydrate(storeState, initialState) {
    // @ts-expect-error: https://github.com/microsoft/TypeScript/issues/43826
    storeState.n = useLocalStorage('key', 0)
  }
})
```

--------------------------------

### Using the store outside of setup

Source: https://pinia.vuejs.org/ssr

When using stores outside of setup, you must pass the pinia instance to the useStore function.

```js
const pinia = createPinia()
const app = createApp(App)

app.use(router)
app.use(pinia)

router.beforeEach((to) => {
  // ✅ This will work make sure the correct store is used for the
  // current running app
  const main = useMainStore(pinia)

  if (to.meta.requiresAuth && !main.isLoggedIn) return '/login'
})
```

--------------------------------

### Avoid Infinite Loops in Setup Stores

Source: https://pinia.vuejs.org/cookbook/composing-stores.html

Demonstrates the restriction against two stores directly reading each other's state in their setup functions, which causes infinite loops.

```js
const useX = defineStore('x', () => {
  const y = useY()

  // ❌ This is not possible because y also tries to read x.name
  y.name

  function doSomething() {
    // ✅ Read y properties in computed or actions
    const yName = y.name
    // ...
  }

  return {
    name: ref('I am X'),
  }
})

const useY = defineStore('y', () => {
  const x = useX()

  // ❌ This is not possible because x also tries to read y.name
  x.name

  function doSomething() {
    // ✅ Read x properties in computed or actions
    const xName = x.name
    // ...
  }

  return {
    name: ref('I am Y'),
  }
})
```

--------------------------------

### defineStore(id, storeSetup, options?)

Source: https://pinia.vuejs.org/api/pinia/functions/defineStore.html

Creates a useStore function that retrieves the store instance using an id, a setup function, and optional extra options.

```APIDOC
## defineStore(id, storeSetup, options?)

### Description
Creates a useStore function that retrieves the store instance using an id, a setup function, and optional extra options.

### Signature
function defineStore<Id, SS>(id, storeSetup, options?): StoreDefinition<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>;

### Type Parameters
- **Id** (string) - Required - The type of the store id.
- **SS** (any) - Required - The type of the setup store.

### Parameters
- **id** (Id) - Required - id of the store (must be unique).
- **storeSetup** ((helpers) => SS) - Required - function that defines the store.
- **options?** (DefineSetupStoreOptions<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>) - Optional - extra options.

### Returns
- **StoreDefinition<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>** - The store definition.
```

--------------------------------

### Reset Setup Store State

Source: https://pinia.vuejs.org/core-concepts/state.html

Manually implement a $reset() method when using Setup Stores.

```typescript
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)

  function $reset() {
    count.value = 0
  }

  return { count, $reset }
})
```

--------------------------------

### Install Pinia module

Source: https://pinia.vuejs.org/ssr/nuxt.html

Use the Nuxt CLI to add the Pinia module to your project.

```bash
npx nuxi@latest module add pinia
```

--------------------------------

### Accessing getters in setup()

Source: https://pinia.vuejs.org/core-concepts/getters.html

Access getters directly as properties of the store instance within a setup() function.

```vue
<script setup>
const store = useCounterStore()

store.count = 3
store.doubleCount // 6
</script>
```

--------------------------------

### Install Pinia with npm

Source: https://pinia.vuejs.org/getting-started.html

Use npm to add the pinia package to your project.

```bash
npm install pinia
```

--------------------------------

### $onAction(callback, detached?)

Source: https://pinia.vuejs.org/api/pinia/interfaces/StoreWithState.html

Setups a callback to be called every time an action is about to get invoked. The callback receives an object with all the relevant information of the invoked action.

```APIDOC
## $onAction(callback, detached?)

### Description
Setups a callback to be called every time an action is about to get invoked. The callback receives an object with all the relevant information of the invoked action: `store`, `name`, `args`. It also receives two functions that allow setting up a callback once the action finishes or when it fails. It returns a function to remove the callback. Note that when calling `store.$onAction()` inside of a component, it will be automatically cleaned up when the component gets unmounted unless `detached` is set to true.

### Method
$onAction(callback, detached?)

### Parameters
- **callback** (`StoreOnActionListener<Id, S, G, A>`) - Required - callback called before every action
- **detached?** (`boolean`) - Optional - detach the subscription from the context this is called from

### Returns
function that removes the watcher: `(): void;`

### Example
```js
store.$onAction(({ after, onError }) => {
  // Here you could share variables between all of the hooks as well as
  // setting up watchers and clean them up
  after((resolvedValue) => {
    // can be used to cleanup side effects
    // `resolvedValue` is the value returned by the action, if it's a
    // Promise, it will be the resolved value instead of the Promise
  })
  onError((error) => {
    // can be used to pass up errors
  })
})
```

```

--------------------------------

### Install Pinia with yarn

Source: https://pinia.vuejs.org/getting-started.html

Use yarn to add the pinia package to your project.

```bash
yarn add pinia
```

--------------------------------

### Using a composable in a Setup Store

Source: https://pinia.vuejs.org/cookbook/composables.html

Shows how to use composables in a Setup Store where properties are automatically discerned into state, actions, or getters. Non-serializable references like DOM elements should not be returned directly.

```typescript
import { defineStore } from 'pinia'
import { useMediaControls } from '@vueuse/core'

export const useVideoPlayer = defineStore('video', () => {
  // we won't expose (return) this element directly
  const videoElement = ref<HTMLVideoElement>()
  const src = ref('/data/video.mp4')
  const { playing, volume, currentTime, togglePictureInPicture } =
    useMediaControls(videoElement, { src })

  function loadVideo(element: HTMLVideoElement, src: string) {
    videoElement.value = element
    src.value = src
  }

  return {
    src,
    playing,
    volume,
    currentTime,

    loadVideo,
    togglePictureInPicture,
  }
})
```

--------------------------------

### Install Pinia with pnpm

Source: https://pinia.vuejs.org/getting-started.html

Use pnpm to add the pinia package to your project.

```bash
pnpm add pinia
```

--------------------------------

### mapActions Example with Keys Array

Source: https://pinia.vuejs.org/api/pinia/functions/mapActions.html

Example of using mapActions with an array of action names to map them directly to component methods.

```javascript
export default {
  methods: {
    // other methods properties
    ...mapActions(useCounterStore, ['increment', 'setCount'])
  },

  created() {
    this.increment()
    this.setCount(2) // pass arguments as usual
  }
}
```

--------------------------------

### Use store outside setup

Source: https://pinia.vuejs.org/ssr/nuxt.html

Pass the pinia instance to useStore when working outside of setup or injection-aware contexts.

```ts
import { useStore } from '~/stores/myStore'

// this line is usually inside a function that is able to retrieve
// the pinia instance
const store = useStore(pinia)
```

--------------------------------

### Example Counter Store

Source: https://pinia.vuejs.org/core-concepts/state.html

A basic counter store used for demonstrating Options API integration.

```javascript
// Example File Path:
// ./src/stores/counter.js

import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
})
```

--------------------------------

### Access Global Properties in Setup Stores

Source: https://pinia.vuejs.org/core-concepts

Setup stores can use inject() to access properties provided at the App level. Do not return these injected properties in the store's return object as they are not part of the store's state.

```typescript
import { inject } from 'vue'
import { useRoute } from 'vue-router'
import { defineStore } from 'pinia'

export const useSearchFilters = defineStore('search-filters', () => {
  const route = useRoute()
  // this assumes `app.provide('appProvided', 'value')` was called
  const appProvided = inject('appProvided')

  // ...

  return {
    // ...
  }
})
```

--------------------------------

### Define store for initial state testing

Source: https://pinia.vuejs.org/cookbook/testing.html

Example store definition to be used with initial state testing.

```ts
import { defineStore } from 'pinia'

const useCounterStore = defineStore('counter', {
  state: () => ({ n: 0 }),
  // ...
})
```

--------------------------------

### Instantiate a Pinia store in a component

Source: https://pinia.vuejs.org/core-concepts

Use the useStore hook within a script setup block to access the store instance.

```vue
<script setup>
import { useCounterStore } from '@/stores/counter'

// access the `store` variable anywhere in the component ✨
const store = useCounterStore()
</script>
```

--------------------------------

### Define a Setup Store with defineStore

Source: https://pinia.vuejs.org/core-concepts

Use a function to define reactive properties, computed getters, and actions. All state properties must be returned in the object to ensure compatibility with SSR and devtools.

```javascript
export const useCounterStore = defineStore('counter', () => {
  const count = ref(0)
  const name = ref('Eduardo')
  const doubleCount = computed(() => count.value * 2)
  function increment() {
    count.value++
  }

  return { count, name, doubleCount, increment }
})
```

--------------------------------

### Upgrade to Pinia v2

Source: https://pinia.vuejs.org/cookbook/migration-v1-v2.html

Install the latest 2.x version of Pinia.

```shell
npm i 'pinia@^2.x.x'
# or with yarn
yarn add 'pinia@^2.x.x'
```

--------------------------------

### Install @pinia/nuxt dependency

Source: https://pinia.vuejs.org/cookbook/migration-v1-v2.html

Use yarn to add the @pinia/nuxt package to your project.

```bash
yarn add @pinia/nuxt
```

--------------------------------

### Example usage of acceptHMRUpdate

Source: https://pinia.vuejs.org/api/pinia/functions/acceptHMRUpdate.html

Shows how to integrate acceptHMRUpdate with Vite's import.meta.hot to enable hot module replacement for a store.

```javascript
const useUser = defineStore(...)
if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useUser, import.meta.hot))
}
```

--------------------------------

### TestingPinia Properties and Methods

Source: https://pinia.vuejs.org/api/%40pinia/testing/interfaces/TestingPinia.html

Documentation of the TestingPinia interface, including its properties (app, state) and methods (install, use) that users can call directly.

```APIDOC
## TestingPinia Interface

### Description
Pinia instance specifically designed for testing. Extends a regular Pinia instance with test specific properties.

### Extends
- Pinia

### Properties

#### app
- Type: App
- Description: App used by Pinia

#### state
- Type: Ref<Record<string, StateTree>>
- Description: root state (inherited from Pinia)

### Methods

#### install(app)
- Parameters:
  - app (App) - The app to install Pinia into.
- Returns: void
- Description: Installs the Pinia instance into the given app. Inherited from Pinia.install.

#### use(plugin)
- Parameters:
  - plugin (PiniaPlugin) - Store plugin to add.
- Returns: Pinia
- Description: Adds a store plugin to extend every store. Inherited from Pinia.use.

```

--------------------------------

### DefineStoreOptionsBase<S, Store>

Source: https://pinia.vuejs.org/api/pinia/interfaces/DefineStoreOptionsBase.html

Interface for common options passed to defineStore(). Extend this interface to add custom options to both option and setup stores.

```APIDOC
## DefineStoreOptionsBase<S, Store>

### Description
Options passed to `defineStore()` that are common between option and setup stores. Extend this interface if you want to add custom options to both kinds of stores.

### Type Parameters
- **S** (extends StateTree) - The state tree type.
- **Store** - The store type.

### Extended By
- `DefineStoreOptions`
- `DefineSetupStoreOptions`

### Usage
This interface is used as a base for defining store options in Pinia. It is not directly instantiated but extended by other interfaces.
```

--------------------------------

### Using store in onServerPrefetch

Source: https://pinia.vuejs.org/ssr

No special configuration is required when using onServerPrefetch within setup.

```vue
<script setup>
const store = useStore()
onServerPrefetch(async () => {
  // ✅ this will work
  await store.fetchData()
})
</script>
```

--------------------------------

### Pinia store actions and state configuration

Source: https://pinia.vuejs.org/cookbook/migration-vuex.html

Example of defining actions in a Pinia store, showing how to use 'this' instead of context and how to handle state updates.

```typescript
      // alternative if other modules are still in Vuex
      // return {
      //   ...state,
      //   fullName: this.fullName,
      //   ...vuexStore.state.auth.preferences,
      //   ...vuexStore.getters['auth/email'].details
      // }
    }
  },
  actions: {
    // no context as first argument, use `this` instead
    async loadUser (id: number) {
      if (this.userId !== null) throw new Error('Already logged in')
      const res = await api.user.load(id)
      this.updateUser(res)
    },
    // mutations can now become actions, instead of `state` as first argument use `this`
    updateUser (payload) {
      this.firstName = payload.firstName
      this.lastName = payload.lastName
      this.userId = payload.userId
    },
    // easily reset state using `$reset`
    clearUser () {
      this.$reset()
    }
  }
})
```

--------------------------------

### Vuex module implementation

Source: https://pinia.vuejs.org/cookbook/migration-vuex.html

A Vuex module example using namespaced state, getters, actions, and mutations.

```typescript
// Vuex module in the 'auth/user' namespace
import { Module } from 'vuex'
import { api } from '@/api'
import { RootState } from '@/types' // if using a Vuex type definition

interface State {
  firstName: string
  lastName: string
  userId: number | null
}

const storeModule: Module<State, RootState> = {
  namespaced: true,
  state: {
    firstName: '',
    lastName: '',
    userId: null
  },
  getters: {
    firstName: (state) => state.firstName,
    fullName: (state) => `${state.firstName} ${state.lastName}`,
    loggedIn: (state) => state.userId !== null,
    // combine with some state from other modules
    fullUserDetails: (state, getters, rootState, rootGetters) => {
      return {
        ...state,
        fullName: getters.fullName,
        // read the state from another module named `auth`
        ...rootState.auth.preferences,
        // read a getter from a namespaced module called `email` nested under `auth`
        ...rootGetters['auth/email'].details
      }
    }
  },
  actions: {
    async loadUser ({ state, commit }, id: number) {
      if (state.userId !== null) throw new Error('Already logged in')
      const res = await api.user.load(id)
      commit('updateUser', res)
    }
  },
  mutations: {
    updateUser (state, payload) {
      state.firstName = payload.firstName
      state.lastName = payload.lastName
      state.userId = payload.userId
    },
    clearUser (state) {
      state.firstName = ''
      state.lastName = ''
      state.userId = null
    }
  }
}

export default storeModule
```

--------------------------------

### Using mockedStore in a test

Source: https://pinia.vuejs.org/cookbook/testing.html

Shows how to use the mockedStore wrapper to get a correctly typed store and mock an action's resolved value.

```TypeScript
import { mockedStore } from './mockedStore'
import { useSomeStore } from '@/stores/myStore'

const store = mockedStore(useSomeStore)
// typed!
store.someAction.mockResolvedValue('some value')
```

--------------------------------

### mapActions

Source: https://pinia.vuejs.org/api/pinia

Allows directly using actions from your store without using the composition API (setup()) by generating an object to be spread in the methods field of a component.

```APIDOC
## mapActions

### Description
Allows directly using actions from your store without using the composition API (setup()) by generating an object to be spread in the methods field of a component.

### Parameters
- **useStore** (Function) - The store definition function.
- **keyMapper** (object | string[]) - An object mapping action names to new names, or an array of action names.

### Returns
- An object of action methods to be spread in the methods field.
```

--------------------------------

### SetupStoreDefinition()

Source: https://pinia.vuejs.org/api/pinia/interfaces/SetupStoreDefinition.html

Call signature for SetupStoreDefinition. Returns a store, creating it if necessary.

```APIDOC
## SetupStoreDefinition()

### Description
Returns a store, creating it if necessary. This is the call signature for the SetupStoreDefinition interface, which is the return type of defineStore() with a setup function.

### Signature
```ts
SetupStoreDefinition(pinia?, hot?): Store<Id, _ExtractStateFromSetupStore<SS>, _ExtractGettersFromSetupStore<SS>, _ExtractActionsFromSetupStore<SS>>;
```

### Parameters
- **pinia?** (`Pinia` | `null`) - Optional - Pinia instance to retrieve the store
- **hot?** (`StoreGeneric`) - Optional - dev only hot module replacement

### Returns
`Store`<`Id`, `_ExtractStateFromSetupStore`<`SS`>, `_ExtractGettersFromSetupStore`<`SS`>, `_ExtractActionsFromSetupStore`<`SS`>>
```

--------------------------------

### Asynchronous Actions with Mande

Source: https://pinia.vuejs.org/core-concepts/actions.html

Actions can be asynchronous, allowing the use of await for API calls or other actions. This example demonstrates using the Mande library to perform an asynchronous user registration.

```js
import { mande } from 'mande'

const api = mande('/api/users')

export const useUsers = defineStore('users', {
  state: () => ({
    userData: null,
    // ...
  }),

  actions: {
    async registerUser(login, password) {
      try {
        this.userData = await api.post({ login, password })
        showTooltip(`Welcome back ${this.userData.name}!`)
      } catch (error) {
        showTooltip(error)
        // let the form component display the error
        return error
      }
    },
  },
})
```

--------------------------------

### $subscribe(callback, options?)

Source: https://pinia.vuejs.org/api/pinia/interfaces/StoreWithState.html

Setups a callback to be called whenever the state changes. It also returns a function to remove the callback. Note that when calling `store.$subscribe()` inside of a component, it will be automatically cleaned up when the component gets unmounted unless `detached` is set to true.

```APIDOC
## $subscribe(callback, options?)

### Description
Setups a callback to be called whenever the state changes. It also returns a function to remove the callback. Note that when calling `store.$subscribe()` inside of a component, it will be automatically cleaned up when the component gets unmounted unless `detached` is set to true.

### Method
$subscribe(callback, options?)

### Parameters
- **callback** (`SubscriptionCallback<S>`) - Required - callback passed to the watcher
- **options?** (`object & WatchOptions<boolean>`) - Optional - `watch` options + `detached` to detach the subscription from the context (usually a component) this is called from. Note that the `flush` option does not affect calls to `store.$patch()`.

### Returns
function that removes the watcher: `(): void;`

```

--------------------------------

### mapActions Example with KeyMapper

Source: https://pinia.vuejs.org/api/pinia/functions/mapActions.html

Example of using mapActions with an object to rename actions for use in a component.

```javascript
export default {
  methods: {
    // other methods properties
    // useCounterStore has two actions named `increment` and `setCount`
    ...mapActions(useCounterStore, { more: 'increment', setIt: 'setCount' })
  },

  created() {
    this.more()
    this.setIt(2)
  }
}
```

--------------------------------

### Define a Pinia store with state, getters, and actions

Source: https://pinia.vuejs.org/introduction.html

This example demonstrates a complete store definition using defineStore, including state initialization, computed getters, and state-mutating actions with JSDoc type annotations.

```javascript
import { defineStore } from 'pinia'

export const useTodos = defineStore('todos', {
  state: () => ({
    /** @type {{ text: string, id: number, isFinished: boolean }[]} */
    todos: [],
    /** @type {'all' | 'finished' | 'unfinished'} */
    filter: 'all',
    // type will be automatically inferred to number
    nextId: 0,
  }),
  getters: {
    finishedTodos(state) {
      // autocompletion! ✨
      return state.todos.filter((todo) => todo.isFinished)
    },
    unfinishedTodos(state) {
      return state.todos.filter((todo) => !todo.isFinished)
    },
    /**
     * @returns {{ text: string, id: number, isFinished: boolean }[]}
     */
    filteredTodos(state) {
      if (this.filter === 'finished') {
        // call other getters with autocompletion ✨
        return this.finishedTodos
      } else if (this.filter === 'unfinished') {
        return this.unfinishedTodos
      }
      return this.todos
    },
  },
  actions: {
    // any amount of arguments, return a promise or not
    addTodo(text) {
      // you can directly mutate the state
      this.todos.push({ text, id: this.nextId++, isFinished: false })
    },
  },
})
```

--------------------------------

### DefineSetupStoreOptions Interface

Source: https://pinia.vuejs.org/api/pinia/interfaces/DefineSetupStoreOptions.html

The DefineSetupStoreOptions interface is the options parameter for defineStore() when creating setup stores. It can be extended to augment stores with the plugin API. It extends DefineStoreOptionsBase and includes type parameters for the store's id, state, getters, and actions.

```APIDOC
## DefineSetupStoreOptions<Id, S, G, A>

### Description
Options parameter of defineStore() for setup stores. Can be extended to augment stores with the plugin API.

### Type Parameters
- **Id** (string) - The type of the store id.
- **S** (StateTree) - The type of the state.
- **G** - The type of the getters.
- **A** - The type of the actions.

### Extends
- DefineStoreOptionsBase<S, Store<Id, S, G, A>>

### Properties
#### actions? (optional)
- **Type**: A
- **Description**: Extracted actions. Added by useStore(). SHOULD NOT be added by the user when creating the store. Can be used in plugins to get the list of actions in a store defined with a setup function. Note this is always defined.

### Example
```ts
interface MyStoreOptions extends DefineSetupStoreOptions<'myStore', MyState, MyGetters, MyActions> {
  // custom options
}
```
```

--------------------------------

### Initialize Pinia instance

Source: https://pinia.vuejs.org/getting-started.html

Create a Pinia instance and register it as a plugin with the Vue application.

```js
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const pinia = createPinia()
const app = createApp(App)

app.use(pinia)
app.mount('#app')
```

--------------------------------

### Skipping hydration in a Setup Store

Source: https://pinia.vuejs.org/cookbook/composables.html

Uses the skipHydrate() helper in a Setup Store to prevent specific state properties from being picked up from the initial server state.

```typescript
import { defineStore, skipHydrate } from 'pinia'
import { useEyeDropper, useLocalStorage } from '@vueuse/core'

export const useColorStore = defineStore('colors', () => {
  const { isSupported, open, sRGBHex } = useEyeDropper()
  const lastColor = useLocalStorage('lastColor', sRGBHex)
  // ...
  return {
    lastColor: skipHydrate(lastColor), // Ref<string>
    open, // Function
    isSupported, // boolean (not even reactive)
  }
})
```

--------------------------------

### $subscribe Method

Source: https://pinia.vuejs.org/api/pinia/interfaces/StoreWithState.html

Setups a callback to be called whenever the state changes.

```typescript
$subscribe(callback, options?): () => void;
```

```typescript
(): void;
```

--------------------------------

### Mount component with createTestingPinia

Source: https://pinia.vuejs.org/cookbook/testing.html

Use createTestingPinia in the global plugins configuration to mock stores during component mounting.

```js
import { mount } from '@vue/test-utils'
import { createTestingPinia } from '@pinia/testing'
// import any store you want to interact with in tests
import { useSomeStore } from '@/stores/myStore'

const wrapper = mount(Counter, {
  global: {
    plugins: [createTestingPinia()],
  },
})

const store = useSomeStore() // uses the testing pinia!

// state can be directly manipulated
store.name = 'my new name'
// can also be done through patch
store.$patch({ name: 'new name' })
expect(store.name).toBe('new name')

// actions are stubbed by default, meaning they don't execute their code by default.
// See below to customize this behavior.
store.someAction()

expect(store.someAction).toHaveBeenCalledTimes(1)
expect(store.someAction).toHaveBeenLastCalledWith()
```

--------------------------------

### Using store in serverPrefetch

Source: https://pinia.vuejs.org/ssr

Access the pinia instance via this.$pinia within serverPrefetch.

```js
export default {
  serverPrefetch() {
    const store = useStore(this.$pinia)
  },
}
```

--------------------------------

### Counter store definition

Source: https://pinia.vuejs.org/core-concepts/getters.html

The base store used for the following Options API examples.

```javascript
// Example File Path:
// ./src/stores/counter.js

import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
  getters: {
    doubleCount(state) {
      return state.count * 2
    },
  },
})
```

--------------------------------

### getActivePinia()

Source: https://pinia.vuejs.org/api/pinia/variables/getActivePinia.html

Get the currently active pinia if there is any. Returns the active Pinia instance or undefined.

```APIDOC
## getActivePinia()

### Description
Get the currently active pinia if there is any.

### Signature
const getActivePinia: () => Pinia | undefined;

### Returns
`Pinia` | `undefined`
```

--------------------------------

### Define a Pinia store with Options API

Source: https://pinia.vuejs.org/introduction.html

Create a store using the defineStore function with state and actions defined as objects.

```javascript
// stores/counter.js
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => {
    return { count: 0 }
  },
  // could also be defined as
  // state: () => ({ count: 0 })
  actions: {
    increment() {
      this.count++
    },
  },
})
```

--------------------------------

### use(plugin)

Source: https://pinia.vuejs.org/api/pinia/interfaces/Pinia.html

Adds a store plugin to extend every store. The plugin is applied to all stores created after this call.

```APIDOC
## use(plugin)

### Description
Adds a store plugin to extend every store. The plugin is applied to all stores created after this call.

### Method
use

### Parameters
#### Parameters
- **plugin** (PiniaPlugin) - Required - The store plugin to add.

### Returns
`Pinia`
```

--------------------------------

### Using mapStores in a component

Source: https://pinia.vuejs.org/api/pinia/functions/mapStores.html

Example of spreading mapStores into the computed property of a component to access stores in the options API.

```javascript
export default {
  computed: {
    // other computed properties
    ...mapStores(useUserStore, useCartStore)
  },

  created() {
    this.userStore // store with id "user"
    this.cartStore // store with id "cart"
  }
}
```

--------------------------------

### storeToRefs<SS>(store): StoreToRefs<SS>

Source: https://pinia.vuejs.org/api/pinia/functions/storeToRefs.html

Creates an object of references with all the state, getters, and plugin-added state properties of the store. Similar to toRefs() but specifically designed for Pinia stores so methods and non reactive properties are completely ignored.

```APIDOC
## storeToRefs<SS>(store): StoreToRefs<SS>

### Description
Creates an object of references with all the state, getters, and plugin-added state properties of the store. Similar to toRefs() but specifically designed for Pinia stores so methods and non reactive properties are completely ignored.

### Signature
```ts
function storeToRefs<SS>(store): StoreToRefs<SS>;
```

### Type Parameters
- **SS** - extends StoreGeneric

### Parameters
- **store** (SS) - Required - store to extract the refs from

### Returns
- **StoreToRefs<SS>** - An object of references to the store's state, getters, and plugin-added state properties.
```

--------------------------------

### Mapping getters with mapState()

Source: https://pinia.vuejs.org/core-concepts/getters.html

Use mapState() to map store getters to component computed properties without using setup().

```javascript
import { mapState } from 'pinia'
import { useCounterStore } from '../stores/counter'

export default {
  computed: {
    // gives access to this.doubleCount inside the component
    // same as reading from store.doubleCount
    ...mapState(useCounterStore, ['doubleCount']),
    // same as above but registers it as this.myOwnName
    ...mapState(useCounterStore, {
      myOwnName: 'doubleCount',
      // you can also write a function that gets access to the store
      double: (store) => store.doubleCount,
    }),
  },
}
```

--------------------------------

### createTestingPinia(options)

Source: https://pinia.vuejs.org/api/%40pinia/testing/functions/createTestingPinia.html

Creates a Pinia instance for unit testing with mocked actions. Accepts optional TestingOptions to configure the testing pinia.

```APIDOC
## createTestingPinia(options)

### Description
Creates a pinia instance designed for unit tests that requires mocking the stores. By default, all actions are mocked and therefore not executed. This allows you to unit test your store and components separately. You can change this with the stubActions option. If you are using jest, they are replaced with jest.fn(), otherwise, you must provide your own createSpy option.

### Signature
function createTestingPinia(options): TestingPinia;

### Parameters
#### options
- **options** (TestingOptions) - Optional - Default: {} - options to configure the testing pinia

### Returns
- **TestingPinia** - a augmented pinia instance
```

--------------------------------

### Invoking Actions in Components

Source: https://pinia.vuejs.org/core-concepts/actions.html

Actions are invoked like regular functions and methods, both within the script setup and directly in the template.

```vue
<script setup>
const store = useCounterStore()
// call the action as a method of the store
store.randomizeCounter()
</script>

<template>
  <!-- Even on the template -->
  <button @click="store.randomizeCounter()">Randomize</button>
</template>
```
Tokens:
Raw