Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 38 ยท Composition and Setup Stores

Setup or Options: Choosing a Style

Compare Pinia's setup and options store syntax side by side: readability, TypeScript, $reset, watchers, composables, testing and migration, with a clear rule for choosing.

Pinia offers two ways to define a store, and both are fully supported. Neither is deprecated and neither is "the old way". This lesson compares them honestly, so you can choose on purpose instead of by habit. You can even mix them in one app.

The same store, twice

A small product list with a filter, written both ways.

JavaScript
// options
export const useShopStore = defineStore("shop", {
  state: () => ({ products: [], query: "" }),
  getters: {
    visible: (state) =>
      state.products.filter((p) => p.name.toLowerCase().includes(state.query.toLowerCase())),
  },
  actions: {
    setQuery(q) { this.query = q; },
    add(name) { this.products.push({ name }); },
  },
});
JavaScript
// setup
export const useShopStore = defineStore("shop", () => {
  const products = ref([]);
  const query = ref("");
  const visible = computed(() =>
    products.value.filter((p) => p.name.toLowerCase().includes(query.value.toLowerCase())),
  );
  function setQuery(q) { query.value = q; }
  function add(name) { products.value.push({ name }); }
  return { products, query, visible, setQuery, add };
});

Run the setup version and the options version below side by side. They behave identically, which is the first thing to remember: the choice does not change how components use the store.

Two definitions, one behavior

Comparison

Topic Options store Setup store
Shape Fixed sections, easy to scan Free-form function, you decide the order
Learning curve Gentle; like Vuex or the Options API Needs the Composition API
this Used in getters and actions None; closures
$reset() Built in Not available; write your own
watch and watchEffect Not possible inside the store Natural
Composables Cannot be used directly Natural
Private helpers Outside the object, in the module Inside the function
TypeScript Inference mostly works; this getters need return types Types flow from refs and functions, no annotations on this
Boilerplate Moderate Must return every state, getter and action
Mistakes that bite Arrow function with this Forgetting to return a ref

Where options stores shine

  • Readability for teams. Anyone opening the file sees state, getters, actions immediately. Code reviews are quick.
  • $reset() for free. Forms and wizards use it constantly.
  • Few ways to go wrong. There is nothing to forget to return.
  • Easy migration from Vuex and from the Options API.

Where setup stores shine

  • Composables and watchers. If the store should react to something (save when a value changes, debounce a query), you want watch, and that is only available in the setup syntax.
  • Complex derived logic that shares private helpers between getters and actions.
  • Reuse. You can extract part of a store into a function and share it across several stores, which is awkward with options.
  • Advanced reactivity such as shallowRef for large lists.
flowchart TD
    A["New store"] --> B{"Need watch, composables<br/>or shared private logic?"}
    B -->|"Yes"| C["Setup store"]
    B -->|"No"| D{"Need $reset or a<br/>Vuex-like structure?"}
    D -->|"Yes"| E["Options store"]
    D -->|"Either is fine"| F["Follow your team's convention"]

A practical way to decide. When both fit, consistency beats cleverness.

Mixing styles

Both styles can coexist in one app, and one store can use the other:

JavaScript
// a setup store reading an options store
export const useReportStore = defineStore("report", () => {
  const cart = useCartStore(); // defined with options
  const summary = computed(() => `${cart.items.length} items`);
  return { summary };
});

Because both produce the same kind of store object, they interoperate perfectly. A common team rule is "options by default, setup when you need watch or composables".

Converting between the two

The mapping is mechanical, so conversion is safe:

  1. Each state property becomes a ref (or one reactive object).
  2. Each getter becomes a computed, replacing state.x with x.value and this.y with y.value.
  3. Each action becomes a function; replace this.x = ... with x.value = ....
  4. Return everything.
  5. If anything called $reset(), add your own reset() function.

Converting the other way is the reverse, except that watch calls and composables must be moved out (into a plugin or into components), since options stores cannot hold them.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which style lets you use watch() inside the store definition?

    A setup function is a normal Composition API function, so watch and composables work.
  2. 2. Which style provides $reset() without extra code?

    Pinia can re-run an options store's state() function; for a setup store you write reset yourself.
  3. 3. Do components need to know which style a store uses?

    Both styles produce the same store interface.
  4. 4. What is the most common mistake in setup stores?

    Anything not returned is invisible to Pinia, DevTools and SSR.

Summary

  • Both styles are fully supported and interoperate; components cannot tell them apart.
  • Options: easy to scan, built-in $reset, few pitfalls.
  • Setup: watch, composables, shared private logic, flexible reuse.
  • Convert mechanically: state to refs, getters to computed, actions to functions, then return everything.
  • Choose by need, then keep the team consistent.

Next: Composables and Watchers in Setup Stores