Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 38 ยท Composition and Setup Stores

Setup Stores

Learn the Pinia setup syntax: write a store like a Vue setup function with ref, computed and functions, what you must return, how $reset and private state behave, and when it fits.

So far you have written stores with an object of state, getters and actions, the options syntax. Pinia has a second way to define a store: the setup syntax. You pass a function instead of an object, and inside it you write ordinary Vue Composition API code. If you know <script setup>, you already know how to write a setup store.

From options to setup

Here is the same counter store written both ways.

JavaScript
// options syntax
export const useCounterStore = defineStore("counter", {
  state: () => ({ count: 0 }),
  getters: { doubled: (state) => state.count * 2 },
  actions: { increment() { this.count++; } },
});
JavaScript
// setup syntax
import { ref, computed } from "vue";

export const useCounterStore = defineStore("counter", () => {
  const count = ref(0);
  const doubled = computed(() => count.value * 2);
  function increment() {
    count.value++;
  }
  return { count, doubled, increment };
});

The mapping is direct:

Options store Setup store
state property ref() or reactive()
getters computed()
actions plain functions
this not needed; use the variables

Components use both versions in exactly the same way: store.count, store.doubled, store.increment(). The only difference is how you wrote the definition.

A counter written as a setup store

Notice v-model.number="counter.step" works directly on the store, because step is a ref that Pinia exposes as a state property.

You must return everything

Pinia sees only what the setup function returns. Whatever you return becomes the store; whatever you keep inside is private to the function. The rules are strict:

  • Every piece of state must be returned. If you create const count = ref(0) and forget to return it, it will not appear in DevTools, will not be part of $state, and breaks SSR and persistence plugins, because Pinia cannot find it.
  • Computed values you want to expose must be returned (they become getters).
  • Functions you return become actions and are wrapped, so $onAction can see them.

You may keep helper functions and temporary variables private by not returning them. Private state, however, is not allowed, because state must be visible to Pinia. Private functions and constants are fine.

JavaScript
defineStore("cart", () => {
  const items = ref([]);               // returned: state
  const TAX = 0.2;                     // not returned: private constant, fine
  const subtotal = computed(() => sum(items.value));   // returned: getter
  function sum(list) { /* private helper */ }
  function add(item) { items.value.push(item); }
  return { items, subtotal, add };
});

What a setup store gives you

Setup stores allow things that the options syntax cannot do so naturally:

  • Use watch and watchEffect inside the store (covered in the composables lesson).
  • Use composables, your own or from libraries, to build state.
  • Share local variables between state, getters and actions without this.
  • Create refs with advanced types (shallowRef, customRef).

The price is that you write a bit more yourself, as the next section shows.

$reset does not exist

An options store knows its initial state because state() is a function Pinia can call again. In a setup store Pinia cannot know how you built the refs, so $reset() is not available; calling it throws an error that tells you so. Write your own:

JavaScript
defineStore("form", () => {
  const initial = () => ({ name: "", email: "" });
  const form = ref(initial());

  function reset() {
    form.value = initial();
  }

  return { form, reset };
});

The initial() function plays the role that state() had. You can also use $patch and $state on setup stores; only $reset is missing.

Writing your own reset

The built-in $reset() button reports the problem, while the store's own reset() clears the form. (The exact error text can vary between Pinia versions, so the demo shows only the start of it.)

Everything you know still works

All the store APIs work on setup stores:

  • store.$patch(...) and store.$state
  • store.$subscribe(...) and store.$onAction(...) (watching state and watching actions)
  • storeToRefs(store) to destructure state and getters (lesson)
  • DevTools time travel, hot module replacement and plugins

A note on this

There is no this in a setup store. Functions refer to the variables of the closure. That also means actions can be passed around freely: const { increment } = counter and setTimeout(counter.increment, 100) work without worrying about binding.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a setup store, what do computed() values become?

    ref becomes state, computed becomes getters and functions become actions.
  2. 2. What happens to a ref that you create but do not return from the setup function?

    Pinia only sees what you return. Unreturned state breaks DevTools, hydration and persistence.
  3. 3. Which store method is not available on setup stores?

    Pinia cannot re-run your refs' initialisation, so you write your own reset function.
  4. 4. How do components use a setup store compared with an options store?

    The definition style is an implementation detail; the store object looks the same.

Summary

  • A setup store is defineStore(id, () => { ...; return { ... } }).
  • ref is state, computed is a getter, functions are actions.
  • Return every state property; unreturned state breaks DevTools, SSR and plugins.
  • $reset() is missing, so write your own reset function.
  • Everything else ($patch, $subscribe, $onAction, storeToRefs) works the same.

Next: Setup or Options: Choosing a Style