Difficulty documenting Vue 3 and avoiding a schism

[chrisvfritz]

The Problem

Many on the team would like the functions API to become the new recommended way of writing components in Vue 3. And even if we did not officially recommend it as the standard, many users would still gravitate toward it for its organizational and compositional advantages. That means a schism in the community is inevitable with the current API.

I've also been experimenting with how we might document Vue 3 and have been really struggling. I think I finally have to admit that with the current, planned API, making Vue feel as simple and elegant as it does now is simply beyond my abilities.

Proposed solution

I've been experimenting with potential changes to the API, outlining affected examples to create a gentler and more intuitive learning path. My goals are to:

• Make the recommended API feel intuitive and familiar.
• Make changes we're making feel like a logical simplification or extension of our current strategy, rather than a radical change in direction.
• Reduce the feeling of there being two different ways of writing components.
• Reduce the number of concepts users have to learn.
• Reduce the frequency and severity of context switching.

Finally, I think have a potential learning path that is worth attention from the team, though you may want to read my explanations for the proposed API changes before checking it out.

Proposed API changes

1. Rename setup to create

Example

Vue.component('button-counter', {
  props: ['initialCount'],
  create(props) {
    return {
      count: props.initialCount
    }
  },
  template: `
    <button v-on:click="count++">
      You clicked me {{ count }} times.
    </button>
  `
})

Advantages

• Avoid introducing a new concept with setup, since we already have a concept of instance creation with the beforeCreate and created lifecycle functions.

• With create, it's more obvious and easier to remember when in the lifecycle the function is called.

• Since this is first available in created, it will make more intuitive sense that it's not yet available in the create function.

Disadvantages

• Downsides related to autocomplete and confusion with lifecycle functions can be resolved with proposal 2.

2. Rename lifecycle function options to begin with on

Example

new Vue({
  el: '#app',
  onCreated() {
    console.log(`I've been created!`)
  }
})

Advantages

• Removes any confusion or autocomplete conflicts if setup is renamed to create (see proposal 1).

• Removes the only naming inconsistency between the option and function versions of an API. For example, computed and watch correspond to Vue.computed and Vue.watch, but created and mounted correspond to Vue.onCreated and Vue.onMounted.

• Users only have to make the context switch once, when going from Vue 2 to Vue 3, rather than every time they move between options and functions.

• Better intellisense for lifecycle functions, because when users type the on in import { on } from 'vue', they'll see a list of all available lifecycle functions.

Disadvantages

• None that I can see.

3. Consolidate 2.x data/computed/methods into create and allow its value to be an object just like data currently

Example

const app = new Vue({
  el: '#app',
  create: {
    count: 0,
    doubleCount: Vue.computed(() =>
      return app.count * 2
    ),
    incrementCount() {
      app.count++
    }
  }
})

Vue.component('button-counter', {
  props: ['initialCount'],
  create(props) {
    const state = {
      count: props.initialCount,
      countIncrease: Vue.computed(
        () => state.count - props.initialCount
      ),
      incrementCount() {
        state.count++
      }
    }

    return state
  },
  template: `
    <button v-on:click="incrementCount">
      You clicked me {{ count }}
      ({{ initialCount }} + {{ countIncrease }})
      times.
    </button>
  `
})

Advantages

• It's easier for users to remember which options add properties to the instance, since there would only be one: create.

• Users don't need to be more advanced to better organize their properties. This one change provides the vast majority of the organizational benefit, without the complexity that can arise once you get into advanced composition.

• New users won't have to learn methods as a separate concept - they're just functions.

• It's even less code and fewer concepts than the current status quo.

• Prevents the larger rift of people using create vs data/computed/methods, by having everyone start with create from the beginning. With everyone already familiar with and using the create function, sometimes moving more options there for organization purposes (e.g. watch, onMounted, etc) will be a dramatically smaller leap.

• Makes the transition to a create function feel more natural, both for current users ("oh, it's just like data - when it's a function, I just return the object") and new users ("oh, this is just like what I was doing before, except I return the object").

• Although Vue.computed will return a binding, users won't have to worry about learning the concept of bindings for the entirety of Essentials. Only once we get to advanced composition that splits features into reusable functions will it become relevant, because then you have to worry about whether you're passing a value or binding.

Disadvantages

• If users decided to log a computed property (e.g. console.log(state.countIncrease)) inside the create function, they would see an object with a value rather than the value directly. They won't understand exactly why Vue.computed returns this until they're introduced to bindings, but I don't see it as a significant problem because it won't stop them from getting their work done.

• When doing something very strange, like trying to immediately use the setter on a computed property inside create, the abstraction of a binding would leak. However, if we think this is likely to actually happen, I believe it could be resolved by emitting a warning on the setter of bindings, since I believe that's always likely to be a mistake.

  const state = {
    count: 0,
    doubleCount: Vue.computed(
      () => state.count * 2,
      newValue => {
        state.count = newValue / 2
      }
    )
  }
  
  // This will not work, because `doubleCount` has not yet
  // been normalized to a reactive property on `state`.
  state.doubleCount = 2
  
  return state

4. Make context the same exact object as this in other options

Example

Vue.component('button-counter', {
  create(props, context) {
    return {
      map: context.$parent.map
    }
  },
  onCreated() {
    console.log(this.$parent.map)
  },
  template: '...'
})

Vue.component('username-input', {
  create(props, context) {
    return {
      focus() {
        context.$refs.input.focus()
      }
    }
  },
  onMounted() {
    console.log(this.$refs.input)
  },
  template: '...'
})

Advantages

• Avoids a context switch (no pun intended 😄) when moving between options and the create function, because properties are accessed under the same name (e.g. this.$refs/context.$refs instead of this.$refs/context.refs).

• When users/plugins add properties to the prototype or to this in onBeforeCreate, users can rely on those properties being available on the context object in create.

Disadvantages

• Requires extra documentation to help people understand that this === context, and that properties are added/populated at different points in the lifecycle (e.g. props and state added in onCreated, $refs populated in onMounted, etc). We'll probably need a more detailed version of the lifecycle diagram with these details (or whatever the reality ends up being).

• For TypeScript users, every plugin that adds properties to the prototype (e.g. $router, $vuex) would require extending the interface of the Vue instance. I think they probably want to do this already for render functions though, right? Don't they still have access to this?

5. Reconsider staying consistent with object-based syntax in the arguments for the function versions of the API?

This one is more of a question than an argument. We have a lot of inconsistencies between the object-based and function-based APIs. For example, when a computed property takes a setter, it's a second argument:

Vue.computed(
  () => {}, // getter
  () => {} // setter
)

rather than providing an object with get and set, like this:

Vue.computed({
  get() {},
  set() {}
})

It's my understanding that these changes were made for the performance benefits of monomorphism. However, they have some significant disadvantages from a human perspective:

• They force users to learn two versions of every API, rather than being able to mostly copy/paste when refactoring between options and functions, creating more work and making them feel like a significant context switch.

• They create code that's less explicit and less readable, since either intellisense or comments are necessary to provide more information on what these arguments actually do.

As a starting place, could we create some benchmarks from realistic use cases so we can see exactly how much extra performance we're getting from monomorphism? That could make it easier to judge the pros and cons.

Thoughts?

@vuejs/collaborators What does everyone think about these? They include some big changes, but I think they would vastly simplify the experience of learning and using Vue. I'm also very open to alternatives I may have missed!

[johnleider]

Absolute fan of this.

[gustojs]

Point 3) is fine as long as it's an addition and not a replacement.

If it is a replacement of the current API, it will be treated as a betrayal of the "we won't drop Object API" promise, regardless of the changes making sense or not. Users want to keep using computed and methods as separate options.

Even making it the default learning version will be taken badly.

Point 4) will touch $router and $vuex too and users won't like it either, but it's easier to swallow than 3).

[Akryum]

I like it. 🐈

[gustojs]

What I like about 3) is that it offers a good middle step for those who want to rewrite their components from Object API to Composition API.

I also like 1) a lot.

[chrisvfritz]

@gustojs The two core concerns I've seen about the new API are:

• it's too complex and especially won't be friendly to beginners
• it will cause a schism

So I think as long as we address both of those concerns, people will be happy in the long run.

But either way, I think some people will be upset in the short term - I don't think we can get around that. The difference is with a replacement, some people being upset is a temporary problem until we convince them it's for the best (which I'm confident we can do) and they realize it's actually a simplification of the current API, rather than more complex. Or worst case, they just get used to it.

If we don't replace data/computed/methods, then we get a choice between two permanent problems:

• We can choose not to feature data/computed/methods prominently in the documentation, in which case the user reaction might be even worse than removing these options altogether, because it'll come across as actively dishonest because those options are obviously deprecated but we're pretending that's not the case. We'll also increase the pain for users who choose to stick with those options, because all the examples in the community will use the syntax we recommend in our documentation.

• If we do feature data/computed/methods prominently in the documentation, then we not only fail in our objective to avoid a schism, but we also make the documentation problem worse because now there's not only data, computed, methods, and create, but also an object syntax and function syntax for create.

Does that make sense?

[NataliaTepluhina]

Thank you, Chris, I think it's a brilliant proposal. I really like all renaming ideas, it seems very logical to me.

While I can understand @gustojs concerns about point 3), I think it's a typical 'lesser evil' choice. Obviously, there will be users complaining about the change but in fact, part of the user base will complain about any possible change we make just because they used to use an old way of doing things. I agree with Chris here, making APIs consistent and preventing a schism worth to make a part of the community temporarily unhappy about the upcoming change.

@chrisvfritz regarding learning path: great examples! However, I understand it's just a draft for now but the last example there should be explained in a very detailed manner. I have some concerns about using asynchronous logic there as it might create a cognitive overload for newer developers.

[nekosaur]

Touching on @gustojs comment on point 4, I actually think users won't swallow having to type e.g. this.$context.$vuex every time very easily.

I do like the other points, especially the renaming. My only concern with regard to point 3 is that while it resembles both the function api and the object api, it's still a 3rd way of doing things, which will potentially increase the amount of context switching done.

[posva]

I think the reasoning behind create naming is smart and I like it.

Prepending on is fine as long as we provide code transform and provide tools to use them (online, cli) and encourage its use so they appear high in search results.

create as an object for new Vue seems reasonable too

Avoids a significant context switch (no pun intended 😄) when moving between options and the create function (e.g. this.$context.refs -> context.refs instead of this.$refs -> context.refs).

I don't think it changes much between the two options so I would rather keep what we have not to break usage. I would rather see properties prepended with a $ in the context parameter so it becomes this.$refs -> context.$refs. But if this can be solved with a codemod too, then I rather not change it

Having the object with named get and set does make things more understandable for beginners imo. The overhead of having both options in the codebase should also be minimal

[Akryum]

I do like the other points, especially the renaming. My only concern with regard to point 3 is that while it resembles both the function api and the object api, it's still a 3rd way of doing things, which will potentially increase the amount of context switching done.

@nekosaur There is actually only one way. It's just that you don't declare them with variables but put them directly in the bindings object.

---

Regarding this, we could document it as the context too, so no $context necessary and no context switching?

[posva]

Regarding this, we could document it as the context too, so no $context necessary and no context switching?

But that could be very confusing because context do not have access to everything in create, eg: $refs aren't there yet

[chrisvfritz]

the last example there should be explained in a very detailed manner. I have some concerns about using asynchronous logic there as it might create a cognitive overload for newer developers.

@NataliaTepluhina I agree 100%! I think we can also think up some even simpler examples at that point in the docs, since we won't have to provide as much of an overview like in the blog post.

I actually think users won't swallow having to type e.g. this.$context.$vuex every time very easily.

I would rather see properties prepended with a $ in the context parameter so it becomes this.$refs -> context.$refs. But if this can be solved with a codemod too, then I rather not change it.

Regarding this, we could document it as the context too, so no $context necessary and no context switching?

I think if we consistently refer to this as the context throughout the documentation, then we'll have a good compromise. And I agree that staying consistent prepending with $ could help a lot too. I've seen a lot of people tripped up by that in the current API, because they keep forgetting.

But that could be very confusing because context do not have access to everything in create, eg: $refs aren't there yet.

If we offered a visual timeline of when everything is added to the context (e.g. props and state are added onCreated, $refs are added onMounted, etc) then we can resolve that confusion.

@nekosaur @posva @Akryum I'm happy to revise the proposal if you all agree that would be a good direction. What do you think?

[Akryum]

👍

[posva]

Can we properly type that by providing a this parameter to the different hooks like create, onCreated and others? eg: right now $el is always an element but it's undefined in beforeCreate.

I really don't like having a $context, I do believe people will find that to be very verbose. Having this seems to be a nice middle ground if people know what they have access to. It does bring a problem if plugins inject things in created that are accessible through Vue.prototype.$something and someone try to access it in a create hook. I hope this is marginal enough and not a good practice in general to not be a problem

[chrisvfritz]

Can we properly type that by providing a this parameter to the different hooks like create, onCreated and others? eg: right now $el is always an element but it's undefined in beforeCreate.

I think we probably can, at least as intellisense provided by Vetur - but many users either don't code in environments where they can access intellisense or they don't even look at the intellisense when it's there, so I don't think we can rely on tooling alone to solve any problems.

I really don't like having a $context, I do believe people will find that to be very verbose. Having this seems to be a nice middle ground if people know what they have access to.

@posva I've come to agree with you about $context, but I think documentation will be a better solution than adding this to create. The problem is that create is very likely to contain nested function contexts, and we've all seen less advanced users have trouble with function bindings.

Either way, it's a documentation problem: we help users understand that this === context, or we can help them understand function bindings. I think teaching this === context will be much easier. 😄