Function-based component API (extended discussion)

[abalashov]

Opening an issue here with a copy of my original comment to #42, per @yyx990803's request:

---

I am the author of "Love letter to Vue": http://www.evaristesys.com/blog/love-letter-to-vue/

As a big booster of Vue who can appreciate its distinctive characteristics and the way it has stood apart from competing frameworks, I must say that I am perturbed and disappointed by the function API proposal. I have to agree with the above posters who say that no serious problem is being solved here which would warrant such a radical shift, and that in essence, this proposal amounts to chasing shiny new things. Yes, there are indeed some code decomposition and modularity problems that this change addresses. But not all theoretical problems are worth addressing.

One of the biggest virtues of Vue, which I mention in the article, is that here, halfway through 2019, it's still quite literally the same Vue I first picked up in late 2016. This is a refreshing contrast to the general pace of change and deprecation in the JS/web world. Frank Chimero's high-level, perspicacious take on this problem bears mention here: https://frankchimero.com/writing/everything-easy-is-hard-again/

From a political and a philosophical point of view, I think it's vital to understand that introducing radical API changes of any kind to any project is breaking, and a generous offer of backward compatibility with old APIs does not solve this problem. With due acknowledgment to the fact that the 2.x API is not slated for deprecation and the labourious emphasis this has received, you're still sunsetting it in an overall ecosystem sense. The 2.x API will no longer be a first-class citizen. A completely new way of doing things insinuates a preferred new way of doing things, and sample code, tutorials, books, etc. will inevitably adopt it over time, leading to a manageability and direction crisis for those with investments in huge Vue code bases. New APIs are unavoidably ideological statements, and the devaluation of old APIs -- indeed, the very ontology of "old" vs. "new" -- have an ideological valence.

While change is inevitable, people want to follow "best practices" in an effort to stave off bit rot, and feel a psychological pressure to buy into the current wave of thinking. So, offering to support the old options API is not of much help; this RFC raises the prospect that the commitment to maintaining backward compatibility with the 2.x option API is not steadfast, and will slowly de-orbit over time, like the Mir space station. In effect, you are decreeing that there's now a new way of doing things, and this is the way they should be done.

I also agree with the criticism mentioned in the Downsides section above: the concern that this way of doing things is arcane and more likely to lead to byzantine or labyrinthine "spaghetti code". One of the biggest selling points of Vue is its simplicity and approachability. It's static enough that a major organisational commitment to Vue has shelf life and durability, rather than evaporating in one's hands, as so many other JavaScript-related commitments do owing to capricious, whimsical API changes and architectural gewgaws.

Thus, technical bickering about code organisation and modularity notwithstanding, from a business and ecosystem health point of view, I think this is the light in which this RFC should be considered, and the cost against which the (from my perspective, marginal) improvements offered should be carefully and judiciously weighed. I do not see a sufficiently captivating problem here worthy of such a radical solution, even if commitment to the 2.x approach is scrupulously observed for some time. It's not worth throwing away the things that make Vue good.

I'm natively Russian, and there is an old political anecdote about this:

Lazar Kaganovich brings Stalin a scaled-down model of a new, reconstituted Moscow, the grandiose global Capital of Socialism that Stalin envisioned (not unlike the visions of Hitler & Speer for the Thousand Year Reich architecture). Most iconic historical features of pre-revolutionary Moscow are demolished, and replaced with grand plazas and enormous, titanic buildings that capture the idealism of the class-conscious revolutionary proletariat, the enormity of the Generalissimus's futuristic vision, and the zeal to shed bourgeois architecture and aesthetics and break with the past.

Stalin asks: "Lazar, where is Saint Basil's Cathedral?"

"It was removed; it will be demolished."

Stalin heaves a sigh and rolls his eyes.
"Lazar, put it back."

[yyx990803]

I respect your opinion so please don't take any of the following as being personal.

no serious problem is being solved here which would warrant such a radical shift, and that in essence, this proposal amounts to chasing shiny new things

I couldn't disagree with this more. Logic composition is probably one of the most serious problems in terms of scaling projects. Quoting myself from another thread:

• the RFC thread also has MANY users expressing how they find the RFC to be solving the exact problem they are facing right now. And they have also mentioned that the current object-based syntax is the exact bottleneck that hinders the scalability of their projects. I acknowledge that many of you may never personally experienced this (which is totally valid, and even great!), but if an aesthetics choice comes at a real maintenance burden (admittedly only in certain types of projects), then it's no longer just an aesthetics problem. Denying some users' opportunity to solve their problems with a better abstraction due to the aesthetics preference of some other users seems like the wrong trade-off to make.

Vue started small, but today it's being used in a very wide range of projects, with varying level of complexity and business domains. Users dealing with different types of projects will run into different needs, some can be easily dealt with using the object-based API, while some cannot. The primary example is

1. Large components (hundreds of lines long) with encapsulates multiple logical tasks
2. The need for sharing the logic of such tasks between multiple components.

For (1), each logical task is forced to be split between option types. For example, a single data-fetching task may need a prop, a data property, a computed property, a mounted hook and a watcher to work together. This means when you pick up this component and try to understand its data-fetching logic, you are constantly jumping up and down in the options list trying to locate the pieces that are related to it. At the same time, when you skim over a property, although you know what type it is, it's quite a bit harder to tell which logical task it is supposed to be dealing with. This gets worse as more logical topics are added to the component. In comparison, with the new API, all related logic for data fetching can be grouped together, and more importantly, cleanly extracted into a separate function, or even a separate file.

An analogy for this problem is file organization in projects. Many of us have come to agree that organizing files by file type (e.g. splitting everything into html, js and css folders) don't really scale. The code related to a feature will be forced to be split between three folders, just for a false impression of "separation of concerns". The key here is that "concerns" is not defined by file type. Instead, most of us opt to organize files by feature or responsibility. This is exactly why people love Vue single-file components. SFC is a way to organize code by feature. Ironically, when SFCs were first introduced, many resisted it because they feel that it violated separation of concerns, only later to acknowledge that SFCs are in fact the more reasonable way to separate concerns.

Point (2) has largely been explained in the Motivations section of the RFC, showing that it achieves what mixins/HOCs/scoped slots can achieve without any of their drawbacks.

With React Hooks, we discovered some of its characteristics could help those users solve these problems described above. This is the fundamental reason for us to come up with this proposal. It is indeed a "new thing", but we are adopting the new thing because it presents a solution to objectively existing problems, not just because they are "new". In the long run, the availability of this new API will pay huge dividends in the hours saved for the developers dealing with the mentioned problems.

Type safety is also an important consideration - again, this is something many users wanted badly but may not appear valuable to those who do not use TS. That's understandable - but I think it's a bit selfish to claim that it's not solving any problems because the problems being solved does not affect you.

introducing radical API changes of any kind to any project is breaking, and a generous offer of backward compatibility with old APIs does not solve this problem

"Breaking" is defined by users forced to change their code. Since users will not have to change their existing code, it is not breaking. I don't think there's anything else to argue about in this aspect.

If even backwards compatibility is not enough, then you are essentially saying a project should never introduce any radical new ideas, ever. I think that's project policy level argument, which if I get to vote, I will firmly vote against. We will try our best to keep the best interest of our users in mind, but the project must and will evolve.

this way of doing things is arcane and more likely to lead to byzantine or labyrinthine "spaghetti code". One of the biggest selling points of Vue is its simplicity and approachability. It's static enough that a major organisational commitment to Vue has shelf life and durability, rather than evaporating in one's hands, as so many other JavaScript-related commitments do owing to capricious, whimsical API changes and architectural gewgaws.

On the contrary, the very motivation of this proposal was to improve the maintainability of long-term Vue projects.

If we look at any JavaScript project, all code starts from an entry file, which is essentially an implicit "main" function being called when your app starts. If having a single function entry will lead to spaghetti code, then all JavaScript projects should be spaghetti code - which is obviously not the case. Why? Because as developers we've learned to organize our code by splitting it up, either into modules or into smaller functions.

A core characteristics of the function-based API design is that understanding code in setup() is not any different from understanding idiomatic JavaScript code and any technique you can use to organize ordinary JavaScript code can be used to organize your setup() function. Any knowledge / style guide / code review process that applies to normal JavaScript code written by your team can be applied to code in Vue setup() functions.

I agree that with the new API you have a theoretically lower bottom threshold for code quality, but as mentioned that can be mitigated by whatever you are already doing to prevent spaghetti code in non-Vue parts of your codebase. On the other hand, code written with the new API also has a substantially higher upper limit in terms of code quality. Any code written with the new API can be refactored into much higher quality code than their options-based equivalent, whereas with the options-based API you will have to resort to mixins and deal with its drawbacks.

I also want to point out that this RFC is not about trading simplicity for maintainability. We should be aware that we are comparing the impressions between an API you've probably been using for years vs. an API you've just seen for the first time. Fundamentally, this is a shift of how you think of a component:

• Options-based API thinks of a component as defined by the types of properties/methods/options it contains.
• Function-based API thinks of a component as defined by the logical topics it is encapsulating.

What many users are lamenting when they talk about "losing simplicity" is in fact losing the ability to inspect a component by option types. But with the new API, it should be quite straightforward to implement a component analyzer that provides a view that allows you to inspect the component by property types. That is to say we would be able to look at our component from both perspectives, whereas with options-based API you are limited to one (since the intention about logical topics is lost when split between options).

It's not worth throwing away the things that make Vue good

I'm getting tired of repeating "nothing is being thrown away." But let's try to define what "things that make Vue good" really is. Many users against this RFC seem to define that as the object-syntax, and as if taking the object-syntax away takes away everything that makes Vue Vue. But let's take a look at what is left intact:

• The template syntax does not change (and the performance is getting better!)
• The way the reactivity system works does not change
• The concepts of computed properties, watchers & component lifecycle do not change
• The SFC format does not change
• The CLI does not change
• The progressive nature of the framework does not change
• The team's commitment to providing better development tools does not change
• Technically, even the object format does not change: everything that worked will still work.

Vue's object syntax has existed since day one. Many of the above were added later along the way, and each contributed to Vue's growth. If you believe the object-syntax is all that matters to you, I would kindly ask you to take a step back and rethink what really makes Vue what it is. After all, this RFC is not that radical a change as it may seem.

[smolinari]

I have to agree with the above posters who say that no serious problem is being solved here which would warrant such a radical shift, and that in essence, this proposal amounts to chasing shiny new things.

The new API solves these problems:

1. It fixes the issues Vue currently has with logic composition.
2. It solves the issues of type inference, leading the way for Vue to be built on TypeScript and offering first class TypeScript support.
3. And not directly mentioned in the RFC, but core to the whole RFC, is the way features of one or more components can now be encapsulated properly and still have strong cohesion. It's allows for better following of the SOLID design principles.

I wrote an article many moons ago about the "separation of responsibilities" Vue affords the community and I knew at that time, it was why Vue was so cherished by those who "understood" it. It's why I love Vue too. Yes, Vue was also my favorite and still is, because every time I leave Vue and work even a little on some React project, even a simple to-do list, it feels......icky.

So, I get it. I do understand the feeling of having been let down, by leaving Vue's "norm" of object option API.

But, I also understand the benefits of the new API. I wouldn't consider myself an advanced programmer, and I'm learning more and more. I'm on the Quasar Framework team and I'm only mentioning that, because here and there, I get to work on bugs and dig into sometimes complex components. For instance, just the other day, I dug into QEditor to fix a link button/ link editor issue. It was hard for me to get into that component's code, because so much of the feature's code I needed to look at was split up into the different options. Some of the code was in a mixin, the rest spread out across a 400 line component, using a render function. It was hard for me to get the gist of the whole feature of the link button and the link editor.

In the end, I fixed the bug, but my solution wasn't elegant and of course, Razvan, the founder and lead dev of Quasar, came up with a much more elegant (and cross-browser complete) solution.

Thing is, I know for sure, had QEditor been built with a more "feature based" code design, where the link button and editor were more encapsulated, I'd have been able to understand the inner workings of the component much faster and might even have come up with a more elegant solution.

I also wrote an article asking users to actually dig into the source code of Quasar. But, I also understood the "nah, it's wonderful magic, I don't want to learn the tricks" kind of mentality. And it's Vue's option object magic that more advanced developers want to break. And, unfortunately, it's also that kind of magic that makes Vue so wonderful.

I realize that story and my impressions/ opinions aren't going to persuade many users, who haven't gotten into that kind of depth of component code yet. And that is more than likely 80% of Vue's user base. However, the things most of you are counting on, the component frameworks you are using, could very much take advantage of better code encapsulation. So, maybe we can all see this as a good addition (and most importantly, always an addition) to the current API for more advanced users????

One thing that also just hit me while writing this reply was this. We are all happy with Vue's template DSL, which is staying despite the new API btw 😄. When I reread this part of the RFC......

Options removed in the Lean Build
These options will not be available in the lean build of 3.0.

data (replaced by setup() + value + state)
computed (replaced by computed returned from setup())
methods (replaced by plain functions returned from setup())
watch (replaced by watch)
provide/inject (replaced by provide and inject)
mixins (replaced by function composition)
extends (replaced by function composition)
All lifecycle hooks (replaced by onXXX functions)

......all v3.0 is doing is the same for HTML. It's a (rather simple) DSL for getting Vue's reactivity into standard JavaScript. I'm not sure how many of you can agree with that, but if you look at the 7 function + the lifecycle hook onXXX additions, it's really not that much to learn or use. It's most definitely easier than React's hook system (and also doesn't have it disadvantages). And in the end, Vue's SFCs, even with this new API, is absolutely nothing like React. Why people say that, I have no idea.

What is similar to React is offering more flexiblity and yes that means more responsibility on us, the users of Vue. But, it's still Vue and it's still better than the rest and now it's even more awesome.

Scott

[beeplin]

@smolinari totally agree... digging into Quasar's complex components and finding something among all kinds of mixins is a nightmare. :))

EDIT: in case of misunderstanding: I am talking about the flaws of mixin mechanism. Nothing to do with quasar ;)

[smolinari]

@beeplin - And just to be clear, you would also agree when I say, Quasar isn't poorly written either. It's Vue's built-in constraints, which make it that nightmare.

Scott

[martinsotirov]

I think the elephant in the room is that the problems this RFC solves (logic composition and better type support) are legitimate but not faced by the community at large.

I have used Vue exclusively for frontend work since 2016 (from small one-off things to large enterprise projects), and I have yet to face any of the problems this RFC solves. I admit that mixin usage can be a problem for large codebases (see Vuetify) so I just avoid using mixins. There are just better ways to structure large modular codebases.

[thatandyrose]

Hi guys and gals, not sure if this is the right place to comment on the RFC (if not let me know!) but here goes:

What's great about the current options based API is clarity and opinion. It's clear what is framework hook/code and what is your code.

What's bad about the new proposal is, it lacks opinion and everything is kinda just mixed in there. It's not as clear nor as friendly.

Having said that, I 100% agree this is solving a real issue, which is separating different concerns of your component. And I also agree mixins don't kinda work.

However, could we find another middle ground? vuex has a nice example of "modules" within a store to separate concerns of different sections of your app.

In this way, could we not think of the options API as having many concerns? So, you could perhaps have many data options, many computed options, but all nested within their own concern.

I realise this is just an off the cuff idea, but could be path towards solving the concerns issue while still maintaining the API friendliness and simplicity of vue!

Thoughts? or... shall I just "get my coat" (reference to an old British sitcom 😬 )

[smolinari]

In this way, could we not think of the options API as having many concerns? So, you could perhaps have many data options, many computed options, but all nested within their own concern.

That IS the whole idea of the function-based API. It takes the options you mentioned and makes them functions, which need to be called within a setup method, but can be encapsulated in different "feature" functions or rather - for better TS support - feature objects.

@yyx990803 - If you could just say, Vue will offer both APIs forever. Then all this will stop. The fear comes from the greatness of the options API possibly being lost at some point (doesn't matter when). It is what makes Vue so attractive to beginner, intermediate and maybe even early advanced programmers (if that is such a thing, but you get the point). You did make a great API and again, the fear is, you want to make it into something different, something where those who love Vue aren't seeing or even contemplating finding that same love with the new API. Those others aren't seeing the advantages of the new API and in fact, are seeing it as something "ugly". I too still feel that sentiment. It doesn't really look elegant to me either. But, I can overlook those "warts", as I do see the practical advantages.

If you could find a better more "elegant" way to have a function-based API, next to the options API, you'll probably be hitting the home run it should be. 😄 Your "programming art" just needs to be more "pretty" and less "abstract". 😉

Scott

[yyx990803]

@martinsotirov I'd be curious to hear about "better ways to structure large modular codebases" when using the options-based API, especially how they allow you to avoid all these mentioned problems in a large enterprise codebase.

[martinsotirov]

@martinsotirov I'd be curious to hear about "better ways to structure large modular codebases" when using the options-based API, especially how they allow you to avoid all these mentioned problems in a large enterprise codebase.

Export shared functionality in a separate vanilla JS service class that you just import in every component that needs it. Much easier to track things later than trying to figure out where X or Y was inherited from.

Structuring code in a way that avoids mixin usage also forces you to rethink your architecture and discover potential problems, similar to how writing unit-testable code forces you to think about your code. And in many other cases it is better even to reimplement a nuanced version of some functionality instead of blindly following the DRY principle, if it helps keep clarity of the codebase better.

[martpie]

I don't have as much experience with Vue.js as I have with React.js so take what I am going to say with a pinch of salt. Though I absolutely like this proposal, I think one point has been really wrongly formulated.

One advantage of Vue.js is also one of the advantage of the Go language: you have "one way" of doing things, instead of 20 different ones. Whereas React falls short is this aspect: classes/function components, hooks/higher-order-components/decorators for example, are just solving the same problems in 2 or 3 different ways.

Yes, they are all supported and nothing is deprecated, but when opening a file, you will never know with what concepts the developer wrote this component (redux or providers? HoC or decorators? etc..), and the cognitive effort to switch from one to the other is not trivial.

Of course this could be enforced by team decisions, but still, the point remains.

Here is I think one of the key of the ranting going on: giving more tools/flexibility to the community also gives more tools to fracture how everyone will write Vue components.

I don't think there's a solution to this problem, but I just wanted to share that.

[yyx990803]

@martinsotirov I think what you are doing is essentially side-stepping the options-based API and introducing a custom pattern, whereas the function-based API provides first-class affordance to such logic extraction. Reactivity inside service classes are also somewhat implicit (I assume you are returning class instances in data()?). In addition, note that your service class can only encapsulate pure state logic and won't be able to encapsulate logic that has to do with side effects (i.e. watchers or component lifecycle hooks), so there's a limitation on what type of logic you can extract.

[martinsotirov]

In addition, note that your service class won't be able to encapsulate logic that has to do with side effects (i.e. watchers or component lifecycle hooks), so there's a limitation on what type of logic you can extract.

If you get to the point of having to reuse things tightly bound to the component (side effects etc.), then you are doing something wrong and have to rethink your architecture or break up the component. That's the benefit of avoiding mixins, at least for me – it forces me to write simpler and better structured components.

[Akryum]

@martpie Vue is already providing a lot of different ways for doing the sames things, and it's been fine!
For example:

• Inline templates, SFC templates, render functions, JSX, x-template, ...
• Extends, Mixins, HOC, Renderless components
• Script tag, vue-cli, custom build setup
• Directive shorthands or full directives
• Root state, event bus, Vuex, other community solutions