vue-reactive-provide

What this is and what it does

This library is a Vue plugin and mixin that wraps Vue's own provide API and makes the object that is provided to children reactive.

This makes it much easier to pass reactive updates down from the parent component down to the children and grandchildren that consume the provided object via inject.

Installation

npm install -D vue-reactive-provide
# or
yarn add -D vue-reactive-provide

You can use this library as a pure mixin or use it via an options interface injected with a Plugin.

To Install the Plugin:

import Vue from 'vue'
import ReactiveProvide from 'vue-reactive-provide'

// not necessary when used as a mixin, see below for details
Vue.use(ReactiveProvide)

// overwrite the option's name:
Vue.use(ReactiveProvide, {
  name: 'reactiveProvide', // default value
})

Basic Usage

You can use this library in two ways:

through an option defined in a component (requires installation as a plugin with Vue.use() as described above)
as a mixin (Vue.use() not required)

A. Options config

Provide:

// in the parent component
export default {
  name: 'Parent',

  reactiveProvide: {
    name: 'nameOfInject',
    include: ['items', 'filteredItems'],
  }

  data() {
    return {
      items [ /* .... */ ]
    }
  },
  computed: {
    numItems() {
      return this.items.length
    }
  }
}

B. Mixin

import { ReactiveProvideMixin } from 'vue-reactive-provide'
export default {
  name: 'Parent',

  mixins: [
    ReactiveProvideMixin({
      name: 'nameOfInject',
      include: ['items', 'filteredItems'],
    })
  ],
  data() {
    return {
      items [ /* .... */ ]
    }
  },
  computed: {
    numItems() {
      return this.items.length
    }
  }
}

Using it in the Child:

export default {
  name: 'Child',
  inject: ['nameOfInject'],
  /**
   * {
   *   items: [ ...],
   *   numItems: [ ...],
   * }
   */
}

Why Is that better than the native `provide` option?

While Vue's native provide implemention is very useful on its own, if you're like me you quickly found that the lack of reactivity limits it in many situations.

While we an provide a reactive object as a property on the provided object quite easily, this doesn't work for a reactive property containing a string, for example:

data: () => ({
  items: ['item 1', 'item 2],
  message: 'A reactive message'
})
provide() {
  return {
    items: this.items, // changes to the array will be reactive in the consuming component
    message: this.message // this will not be reactive
  }
}

We could pass down $data, but the we possibly pass down more than we want. And we also can't pass down computed props in a reactive way, either.

This small lib aims to fix these problems. You just tell it which properties of your component you want to provide to its children, and they will be put on a reactive object for you.

Options

Option	Required	Type (Default)	Description
name	yes	`string` (`undefined`)	The name under which to `provide` the object
include	no	`string[]` (`false`)	An array of strings, each a property name of the component
props	no	`boolean` (`false`)	Provide all `$props` properties on the object.
attrs	no	`boolean` (`false`)	Works like the `props` option, but for $attrs
listeners	no	`boolean` (`false`)	Works like the `props` option, but for $listeners
nameForComputed	no	`string	false `(`false`)
inheritAs	no	`string	false `(`false`)

Advanced Usage

Passing down all...

Props:

reactiveProvide: {
  name: 'nameOfInject',
  props: true,
}

inject: ['nameOfInject'],
// {
//   "prop1": <value>
//   "prop3": <value>
//   "prop2": <value>
//   "propX": <value>
// }

Attributes:

reactiveProvide: {
  name: 'nameOfInject',
  attrs: true,
}

Props:

reactiveProvide: {
  name: 'nameOfInject',
  listeners: true,
}

Using the computed property

With scoped slots:

The object that is provided to the children is also available as a computed prop of the same name in the component that defined it.

This works great with scoped slots:

<script>
export default {
  reactiveProvide: {
    name: 'nameOfInject',
    include: ['message', 'items']
  },
  computed: {
    // a computed property with the name 'nameOfInject' is automatically added
  }
}
</script>
<template>
  <div>
    <!-- This slot will receive `items` and `message` as props -->
    <slot v-bind="nameOfInject">
  </div>
</template>

Inheriting an injection from the parent

When building a complicated tree of components, you may find yourself in a situation where you want to essentially pass an injection from the parent further down to the children, but also add or overwrite something. This option makes it possible.

// defined in Parent.vue
data: () => ({
  static: 'this doesnt get changed',
  message: 'the original message'
}),
reactiveProvide: {
  name: 'nameOfInject',
  include: ['message', 'items']
},

// Middleman.vue
data: () => ({
  message: 'a better message',
  plus: 'something else'
}),
reactiveProvide: {
  name: 'nameOfInject',
  include: ['message', 'plus'],
  inheritAs: 'injectFromParent'
},

Your Middleman.vue, you will now have two props (the computed one, this.nameOfInject and the originall injected one, this.injectFromParent) and the object that's provided to the children will look like this:

{
  static: 'this doesnt get changed',
  message: 'a better message',
  plus: 'something else'
}

Working on this

The following instructions are only relevant to people working on this repository:

Development

Compiles and hot-reloads for development

yarn run serve

Build for production

yarn run build

Lints and fixes files

yarn run lint

Tests

This project runs unit tests with jest.

yarn run test:unit

# for watch mode:
yarn run test:unit:w

linusborg / vue-reactive-provide Goto Github PK