Vue3 plugin to use reactivity with object that implements the Storage interface

🏠 Homepage

A Vue3 plugin to use reactivity with object that implements the Storage interface, for example: localStorage, sessionStorage or customer object. Working with one or various app instances. Based on @cljimenez/vue-localstorage-reactive. Include the class ReactiveWebStorageError used by ReactiveWebStorage to throw Errors.

Index

• Install
• How to use?
  • Install the plugin
  • Install options
  • About the ReactiveWebStorage methods
  • Use the composition API
• Author
• Contributing
• License

Install

npm install vue3-reactive-storage

How to use?

• Install the plugin.

  Using an app instance

  import { createApp, reactive, ref } from 'vue'
  import createReactiveWebStorageInstaller from 'vue3-reactive-storage'
  
  import { createApp } from 'vue'
  
  import App from './App.vue'
  
  const app = createApp(App)
  
  app.use(createReactiveWebStorageInstaller(), {
    webStorage: localStorage,
    reactiveStorage: ref({}),
  })
  
  const appReactiveStorage = app.config.globalProperties.$reactiveWebStorage
  
  app.provide('storage', appReactiveStorage)
  
  app.mount('#app')

  Using various app instances

  import { createApp, reactive, ref } from 'vue'
  import createReactiveWebStorageInstaller from 'vue3-reactive-storage'
  import App from './App.vue'
  import SubApp from './SubApp.vue'
  import OtherSubApp from './OtherSubApp.vue'
  
  const app = createApp(App)
  const subApp = createApp(SubApp)
  const otherSubApp = createApp(OtherSubApp)
  
  app.use(createReactiveWebStorageInstaller(), {
    webStorage: localStorage,
    reactiveStorage: ref({}),
  })
  
  subApp.use(createReactiveWebStorageInstaller(), {
    prefix: 'new_prefix',
    webStorage: sessionStorage,
    reactiveStorage: ref({}),
  })
  
  otherSubApp.use(createReactiveWebStorageInstaller(), {
    prefix: 'some_prefix',
    webStorage: localStorage,
    reactiveStorage: reactive({}),
  })
  
  const appReactiveStorage = app.config.globalProperties.$reactiveWebStorage
  const subAppReactiveStorage =
    subApp.config.globalProperties.$reactiveWebStorage
  const otherSubAppReactiveStorage =
    otherSubApp.config.globalProperties.$reactiveWebStorage
  
  app.provide('storage', appReactiveStorage)
  subApp.provide('storage', subAppReactiveStorage)
  otherSubApp.provide('storage', otherSubAppReactiveStorage)
  
  app.mount('#app')
  subApp.mount('#subapp')
  otherSubApp.mount('#othersubapp')

• Install options.

  When you installs this plugin using you can use options:

  app.use(createReactiveWebStorageInstaller(), options)

  The options object can contain the following attributes:

  • webStorage: Required value. localStorage, sessionStorage or other object that implements the Storage interface.

  • reactiveStorage: Required value. ref or reactive object.

  • prefix: Optional value. Used to segment the Storage object, the prefix is added to key (using '-') in Storage object. Generally used when using multiple app instances. For example:

    import { createApp, reactive, ref } from 'vue'
    import createReactiveWebStorageInstaller from 'vue3-reactive-storage'
    
    import { createApp } from 'vue'
    
    import App from './App.vue'
    
    const app = createApp(App)
    
    app.use(createReactiveWebStorageInstaller(), {
      prefix: 'hello_world'
      webStorage: localStorage,
      reactiveStorage: ref({}),
    })
    
    const appReactiveStorage = app.config.globalProperties.$reactiveWebStorage
    
    // Adds in Storage object
    // key: hello_world-my_key
    // value: data
    // Adds in reactive object
    // key: my_key
    // value: data
    appReactiveStorage.setItem('my_key', 'data')
    
    app.provide('storage', appReactiveStorage)
    
    app.mount('#app')

    by default, prefix is ''.

  • loadDataFromWebStorage: Optional value. By default is true. Loads the keys/values in Storage object to reactive object when the load event is fired by window object. Useful when closing and opening the browser window.

• About the ReactiveWebStorage methods

  The ReactiveWebStorage object provides an interface similar to the Storage interface, this methods are:

  • (getter) length: Obtains the number of elements saved in reactiveWebStorage.
  • (method) key(index): Returns the key in nth position into reactiveWebStorage.
  • (method) getItem(key): Returns the parsed key's value saved into reactiveWebStorage.
  • (method) setItem(key, item): Saves the pair key/value into reactiveWebStorage.
  • (method) removeItem(key): Removes the pair key/value from reactiveWebStorage.
  • (method) clear(): Removes all pairs key/value into reactiveWebStorage.

  And include others methods:

  • (getter) reactiveStorageAdapter: Returns the reactiveStorageAdapter (object that wraps the reactiveStorage using an insterface similar to Storage) object used by reactiveWebStorage instance.
  • (getter) reactiveStorage: Returns the reactiveStorage object used by reactiveWebStorage instance.

• Use the composition API:

  You can use the provide / inject functions.

  import { createApp, reactive, ref } from 'vue'
  import createReactiveWebStorageInstaller from 'vue3-reactive-storage'
  
  import { createApp } from 'vue'
  
  import App from './App.vue'
  
  const app = createApp(App)
  
  app.use(createReactiveWebStorageInstaller(), {
    webStorage: localStorage,
    reactiveStorage: ref({}),
  })
  
  const appReactiveStorage = app.config.globalProperties.$reactiveWebStorage
  
  app.provide('storage', appReactiveStorage)
  
  app.mount('#app')

  // you can use the inject function to access to the reactiveWebStorage.
  <template>
    <h2>{{ getUsername }}</h2>
    <button @click="storage.setItem('username', 'an username')">
      Add username
    </button>
    <button @click="storage.removeItem('username')">Delete username</button>
  </template>
  
  <script setup>
  import { inject, computed } from 'vue'
  
  const storage = inject('storage')
  
  const getUsername = computed(() => {
    return storage.getItem('username')
  })
  </script>

Author

👤 Cristopher Jiménez Meza

• Github: @cristopher1

🤝 Contributing

Contributions, issues and feature requests are welcome!Feel free to check issues page. You can also take a look at the contributing guide.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2024 Cristopher Jiménez Meza. This project is MIT licensed.

This README was generated with ❤️ by readme-md-generator