Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 38 ยท Plugins and Persistence

Writing a Pinia Plugin

Learn what a Pinia plugin is, when it runs, what it receives and how to write one that adds a property to every store, with runnable examples.

Sooner or later you want behavior that applies to every store: logging every action, adding a $reset to setup stores, saving state to storage, reporting errors. Copying that code into each store is tedious and easy to forget. A Pinia plugin is the answer: one function that Pinia calls once for each store, right after the store is created.

In this chapter you learn how plugins work, how to extend stores with new properties and methods, and how to use them to persist state. This first lesson covers the basics: how to register a plugin, when it runs and what it can do.

What a plugin is

A plugin is a function that receives a context object. You register it with pinia.use():

JavaScript
import { createPinia } from "pinia";

function helloPlugin(context) {
  console.log("A store was created:", context.store.$id);
}

const pinia = createPinia();
pinia.use(helloPlugin);

Pinia calls helloPlugin every time a store is created for the first time, that is, the first time you call useXStore(). The function runs once per store, not once per component.

The context has four fields:

Field What it is
store The store that was just created (reactive, already usable).
app The Vue app the pinia is installed on (createApp() result).
pinia The pinia instance itself.
options The options object you passed to defineStore(), including any custom options.

Most plugins only need store. Destructuring keeps them short: ({ store }) => { ... }.

The order of things

Three rules decide whether your plugin sees a store:

  1. A plugin must be registered before the store is created. Stores created earlier never see it.
  2. The pinia must be installed on an app (app.use(pinia)) before any plugin runs, because app is part of the context. Plugins registered before installation are queued and run once the app is known.
  3. Plugins run in the order of registration.
flowchart LR
  A["createPinia()"] --> B["pinia.use(plugin)"]
  B --> C["app.use(pinia)"]
  C --> D["useStore() the first time"]
  D --> E["store created"]
  E --> F["plugin(context) runs"]

Plugins run after a store exists, once per store.

If a store seems to ignore your plugin, check the order first. Calling useStore() at module level, before pinia.use(...), is the usual cause.

Adding a property to every store

A plugin can return an object. Pinia merges its properties into the store:

JavaScript
function secretPlugin() {
  return { secret: "the cake is a lie" };
}

After that, store.secret exists on every store. You can also assign directly, which does the same thing:

JavaScript
pinia.use(({ store }) => {
  store.secret = "the cake is a lie";
});

Returning an object is nicer because it is explicit. Assigning is handy when you decide conditionally.

Try it. Two stores, one plugin: both get createdAt and a describe() method.

A plugin that adds a property and a method

Both stores got the same behavior without either store knowing about the plugin.

Reading custom options

The options field lets a plugin react to what a store declares. A store can opt in with a custom option, and the plugin reads it:

JavaScript
defineStore("notes", {
  state: () => ({ list: [] }),
  debug: true, // custom option
});

pinia.use(({ store, options }) => {
  if (options.debug) {
    console.log("debugging", store.$id);
  }
});

Custom options must be declared for TypeScript through module augmentation; plain JavaScript needs nothing. The next lesson digs into this and into the other things a plugin can attach to.

A plugin that only observes

A plugin does not have to return anything. A common use is observing. Here we log each store as it is created:

A plugin that only observes

Notice that c appears only after you press the button. Stores are created lazily, and the plugin follows.

Common mistakes

  • Registering after the store exists. Plugins are not applied retroactively.
  • Expecting one run per component. Plugins run once per store, not per use.
  • Returning non-reactive data you expect to be reactive. Returned values are added as plain properties. To add reactive state, see extending stores.
  • Heavy work in the plugin body. It runs for every store, so keep it light.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When does a Pinia plugin function run?

    Pinia calls each plugin when a store is created for the first time, not per component and not on state changes.
  2. 2. How do you register a plugin?

    Plugins are registered on the pinia instance with pinia.use().
  3. 3. A store was created before pinia.use(myPlugin) was called. What happens?

    Plugins only apply to stores created after registration.
  4. 4. Which context field holds the options passed to defineStore()?

    The context has store, app, pinia and options; options is the object given to defineStore().

Summary

  • A plugin is a function (context) => void | object registered with pinia.use().
  • It runs once per store, right after creation, in registration order.
  • The context gives you store, app, pinia and options.
  • Return an object (or assign to store) to add properties to every store.
  • Register plugins before any store is created.

Next: Extending Stores from Plugins