Artwork from Pinia

pinia-plugin-webext-storage

Persistence and rehydration of Pinia stores, backed by `browser.storage`.

✨ Features

• Persist Pinia stores to the WebExtension storage.
• Configurable per Pinia store.
• Still compatible with Vue 2 and 3.
• No external dependencies apart from webextension-polyfill (only needed if you target non-mozilla browsers).
• A bit larger than the original pinia-plugin-persistedstate, but still super small (<1.5kB).

⚙️ Installing

1. Install with your favorite package manager:

   • pnpm : pnpm i pinia-plugin-webext-storage
   • npm : npm i pinia-plugin-webext-storage
   • yarn : yarn add pinia-plugin-webext-storage

2. Add the plugin to pinia:

import { createPinia } from 'pinia';
import piniaPluginWebextStorage from 'pinia-plugin-webext-storage';

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

🚀 Usage

You just need to add the persist option to the store you want to be persisted as follows:

import { defineStore } from 'pinia';

//* using option store syntax
export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
    };
  },
  persist: true,
});

//* or using setup store syntax
export const useStore = defineStore(
  'main',
  () => {
    const someState = ref('hello pinia');
    return { someState };
  },
  {
    persist: true,
  },
);

In case you want to configure how the data should be persisted, persist can take options:

• key: string : Key to use in storage (defaults to the current store id).
• storageType: 'local' | 'sync' | 'managed' : The storage area to sync the store with (defaults to 'local')
• paths: Array<string> : Array of dot-notation paths to partially persist the state, [] means no state is persisted (defaults to undefined and persists the whole state).
• beforeRestore: (context) => void : Hook executed (if set) before restoring the state from local storage.
• afterRestore: (context) => void : Hook executed (if set) after restoring the state from local storage.

The context passed to the hooks is the PiniaPluginContext. It exposes properties such as the current store. More infos here.

import { defineStore } from 'pinia';

export const useStore = defineStore('main', {
  state: () => {
    return {
      someState: 'hello pinia',
      nested: {
        data: 'nested pinia',
      },
    };
  },
  persist: {
    key: 'store-key',
    storageType: 'sync',
    paths: ['nested.data'],
    beforeRestore: (context) => {
      console.log('Before hydration...');
    },
    afterRestore: (context) => {
      console.log('After hydration...');
    },
  },
});

The config above will only persist the nested.data property in browser.storage.sync under store-key.

It will also execute the beforeRestore and afterRestore hooks respectively before and after hydration.

🔧 Factory function configuration

Need to override default options? You can import and use createWebextStorage(options):

import { createPinia } from 'pinia';
import { createWebextStorage } from 'pinia-plugin-webext-storage;
const pinia = createPinia();
pinia.use(
  createWebextStorage({
    storageType: 'sync',
    beforeRestore: () => {},
    afterRestore: () => {},
  }),
);

The options passed will be used in any store declaring persist: true. You can still override these defaults with per-store options.

⚠️ Limitations

References do not persist

Beware of the following:

const a = {
  1: 'one',
  2: 'two',
  ...
}
const b = a

// Before hydration 'a' and 'b'
// point to the same object:
a === b -> true

// After hydration (page reload)
// 'a' and 'b' are different objects
// with the same content:
a === b -> false

As a consequence, reactivity between a and b is lost.

To get around this you can exclude either a or b from persisting and use the afterRestore hook to populate them after hydration. That way a and b have the same reference again and reactivity is restored after page reload.

Non primitive types are not persisted

Due to serialization (JSON.stringify/JSON.parse) needed to persist in storage, non primitive typed data such as Date are no rehydrated as Date but as string instead.

To get around this you can use the afterRestore hook to reformat the data as needed.

📝 License

Copyright © 2022 ohmree.
Copyright © 2022 Sacha Bouillez.
This project is under the MIT license.