directive install hook

[lidlanca]

• Start Date: 2021-08-02

• Target Major Version: 3.x

• Reference Issues:

• Implementation PR: feat(runtime-core): directive install hook core#4235

• RFC: directive install hook #370

Summary

add install hook for a custom directive

Basic example

export default {
   directives: {
      MyDir: {
         install(){ return { mounted(){}, unmounted(){} } 
      } 
   } 
}

Motivation

In current state when a function is passed as a directive, vue will register the function
to mounted and updated hooks only.
additionally there is no way to tell which hook invoked the function, or register to other hooks.

having an install hook will provide 2 main advantages.

1. allows for function based directive, that can target any of the supported directive hooks
2. having access to the directive early enough, that a function can be used to create the directive dynamically,
   with access to the directive binding(instance, value, etc)

Why are we doing this? What use cases does it support? What is the expected
outcome?

1. The current function based directive is limited to 2 fixed hooks, and no ability to know the life cycle phase
   when the function is invoked.

2. consider provide/inject api, a parent component can actually provide a directive as an install function
   where the child can then inject and use.
   ( currently inject() is not callable in a directive hook, however as a work around, a child can "resolve" the provided value via. instance.$.provides )
   which make this use case doable. even without full support from the inject functionality.

Detailed design

vuejs/core#4235

export default {
   directives: {
      myDir: {
          install(binding : DirectiveBinding): ObjectDirective {
            return { mounted(){}, unmounted(){}, ... } 
          }
      }
   } 
}

if install hook is provided it will be called and the result will be merged into the directive hooks object.

Drawbacks

a function based directive might have additional overhead, however vue already supports a very limited function based directive.

Alternatives

n/a

Adoption strategy

the feature is additive and should not have any impact on existing code.

Unresolved questions

is install the best hook name

[yyx990803]

I like the idea - I wish I could've changed how the function shorthand worked in v3 but it's too late to make a breaking change. So install sounds like a reasonable workaround here. However there might be a chance to overload the function shorthand:

• If nothing is returned, it would work as a shorthand for created + mounted;
• If an object is returned, the return object would then override the above behavior:

const MyDir = (el, binding) => {
  // created
  return {
    mounted() {},
    updated() {},
    unmounted() {}
  }
}

[lidlanca]

unfortunately, we can't pre-evaluate the function to know if it has a return value without causing an unexpected hook call.
and we can't add lazy resolver logic, because we need to evaluate on created or creation and beforeUpdate, to maintain state, with both phases in the life cycle not being expected by current "shorthand function", resulting in unexpected hook call.

I have experimented with the idea of marking the "shorthand function" to be treated differently as an install function
but I thought an actual hook is more visible and concrete.

// mark a  shorthand directive function as an install function.
function markDirectiveInstall( MyDir  ) {
  def(MyDir, '__install', true)
  return MyDir
}

const MyDir = markDirectiveInstall( (el, binding) => {
  // created
  return {
    mounted() {},
    updated() {},
    unmounted() {}
  }
})

[yyx990803]

Ah ok, I just realized the default shorthand is in fact mounted (instead of created) + updated so yes an additional hook seems necessary.

[lidlanca]

oh right, I corrected that in the description.

yes an additional hook seems necessary.

considering the alternatives I think the extra hook is probably the preferable solution

[keuby]

Is there any possibility of supporting the Composition API in the install function, like inject/provide

[dpschen]

With a wrapper function and the help of the effect scope api you can partly use the composition api:

I made a small test:
https://github.com/dpschen/vue3-directive-script-setup

[lidlanca]

with the feature as implemented in vuejs/core#4235

you can inject in the install() function. the install() is evaluated as part of the rendering in withDirective and will have access to the instance context which will allow inject to work as expected..

[lidlanca]

one of the original motivations for this feature was to allow the injection of the directive itself.

injecting directive using an install wrapper.

  // wrapper for injectable directive
  function injectableDirective(dirName){
    return {
      install : ()=> inject(dirName, {mounted:()=>{} }) 
    }
  }

  let myDir = injectableDirective('providedDirName')

  export default {
    directives: {
      myDir
    }
  }