What Vue’s Creator Learned the Hard Way with Vue 3
“The first mistake that we made was that there were too many small breaking changes each,” You said in a video of the November message that posted Nov. 2. “The core of the issue here is that every single change looked manageable in isolation, but the complexity really compounds exponentially when the many changes are combined.”
As a corollary to that, he learned that when making changes, it’s wise to keep things working by default. That’s led to a workflow change for the framework’s maintainers, he added, in which it will use a deprecating cycle in the future.
“For everything that I want to change or break or remove, we always first keep everything working, and then deprecated it,” he clarified. “Then there will be an opt-in phase where the new behavior is introduced under a flag, and the user can explicitly opt in to the new behavior without breaking anything. And then eventually, the deprecated behavior is removed in the future release.”
Vue maintainers will also stagger changes between releases so there will never again be a “big bunch of breaking changes altogether,” he explained. He compared the plan to Angular and Ember’s approaches, which spread out small breaking changes between the major versions over a relatively long time.
“Vue has gotten to the stage where we believe this is going to be extremely important for the long run,” he said. “We can assure you that in the short term, we definitely are not thinking about any breaking changes. And for the long run, we want V3 to be the stable foundation. And we will take this kind of change very seriously.”
Mind the Ecosystem
The second lesson he learned is to reach out to the ecosystem library authors when there are changes, to ensure that issues are addressed before the release hits the registry, You said.
“Mistake number two is underestimating the impact on ecosystem libraries,” You said. “We didn’t think in the context of the amount of work library authors would have to [do] to adapt their existing libraries to be V3.”
The result is that when they changed a lot of internal APIs and other internal behavior, it made it “very difficult” for big libraries that relied on these internal behaviors to upgrade to Vue 3, he said. That’s led to long upgrade times for major ecosystem libraries, including Nuxt and Beautify.
“In fact, these are also two of the most prominent examples of mutual applications being stuck on old versions because of the difficulty of upgrading from those dependencies,” he said. “So the lesson learned here is that, obviously, ecosystem dependencies are critical.”
To combat this potentiality, Vue has adopted an ecosystem-automated Continuous Integration system that allows it to run all the changes in the Vue core against its downstream ecosystem dependencies and downstream projects that depend on Vue.
“As of now we have over 15 projects integrated in the system, and we will be adding more in the future,” he said. “Every commit can be run against all these downstream libraries before we make releases, and we will know whether things break before we even do the release. We can reach out to these ecosystem library authors to work with them to resolve these issues before the release actually hits the registry.”
Related to this is that Vue wants to discourage and prohibit the use of internal APIs because they noticed that has been a major contributing factor of difficulty for library subgroups, he added.
“So luckily, with the availability of TypeScript in most of these projects, nowadays, we’re able to enforce that both at the type level and at the runtime level,” he said. “We still need to expose some internal APIs for official tools or libraries to hook into. But for ecosystem libraries that we don’t have direct control over, we will essentially move those private APIs from the type definitions so that it will be an error if these libraries ever tend to use them.”
Release Everything Together
It was a mistake to not release everything together, he continued. Vue 3 core was released in September 2020, while many ecosystem parts were still a work in progress. There were documentation issues and the composition API wasn’t introduced as a first-class concept in the documentation in the beginning, he said. Official libraries, migration build, dev tools support — all were lacking when Vue core stable was released, he added.
“The reason we did that was because we felt it was important to get something out of the door, so the ecosystem can have the incentive to […] start trying things out,” You said. “But the result is releasing it without a completed ecosystem brought confusion to a lot of early adopters.”
In a big release, he said, it’s more important to have things polished and make sure everything is ready than to get something out the door, he acknowledged.
“More importantly, before big releases, you want to find ways to gather feedback and work with library maintainers to upgrade the projects before releasing,” he said. “This is being more proactive in the collaboration of the stakeholders and ecosystem, and this is something we definitely want to improve on if we want to do big changes in the future.”
What Vue 3 Got Right
That said, there are things Vue got right with this release, he continued, starting with embracing TypeScript.
“Nowadays, type checking is table stakes for frontend solutions,” You said. “If you look at any major TypeScript [or] major frontend solutions, right now TypeScript integration [and] TypeScript support is going to be the first thing people look at.”
TypeScript has proven to “vastly improve” maintainability, especially in large team environments working on long-term projects, he said. Moving to TypeScript in the codebase also vastly improved the maintainability of Vue itself, he added, creating a good foundation for future iterations.
Another thing Vue got right was embracing composition, he said. That was something people originally questioned that has worked out well for Vue, he added.
“We still remember the early days when composition API was introduced. It was inspired by React hooks, obviously, but it’s rooted in Vue’s own reactivity system — but in the early days, there was a lot of controversy. People didn’t really get why we are doing it,” he said.
In fact, there are still people who prefer the Options API, but there are limitations with it that the composition API does not have. Part of this is because Vue’s user base has shifted, he said. In the early days, most users were focused on small to medium-use cases where the focus was easy integration into existing backend systems. But over time, Vue maintainers have seen users build more complex and demanding use cases, as well as large-scale single page applications.
“For Vue to first adapt to its changing user base, and also to adapt to the changing demands of the industry, we have to come up with something that addresses those new problems that arises with these new demands, and that is scalability,” he said. “So composition API was invented, essentially, to try to provide a way to unlock this kind of scalability, while retaining as much user-friendliness that’s routed in Vue — as much as possible.”
Those who have adopted composition API have found that it has real benefits, he added.
“This also has led to really strong community efforts like VueUse, which provides us with a collection of extremely useful utilities that addresses a lot of problems that [aren’t] really suitable to be included in Vue core, but it’s nicely addressed by the community,” he said. “In fact, I believe VueUse is probably one of the biggest benefits that’s directly resulted from composition API.”
Developer Experience Investments Pay off
Vue also made the right choice by investing in developer experience, he added. That actually led to the creation of the popular web build tool, Vite, which was born out of a Vue-only dev server prototype. Now, a number of frameworks leverage Vite, including Nuxt.
Vue has seen its investments in its IDE pay off in the form of an expanded ecosystem that benefits web developers as a whole, he said. The IDE investments led to Volar, an umbrella project for a subset of projects that includes Vue’s language server and Vue TSC, which is a command line interface that wraps TypeScript and provides command line time checking for Vue components.
“This whole set of tools, initially only for Vue — again, similar to Vite — got expanded into an ecosystem of a collection of tools that helps frameworks build improved IDE and TypeScript support,” You said. “Volar is now also spinning into its own framework agnostic core that not only supports Vue, but is also powering Astro and MDX and […] other potential frameworks that will adopt this.”
That’s unique to Vue’s ecosystem, he claimed. “We’re seeing a lot of good ideas that start in the ecosystem, and then start having bigger impact than just the Vue ecosystem,” You said.
Finally, Vue 3 fulfills the goals that they set out for it — including better performance, better types for support, better scalability and a better development experience, he said. With Vue 2 support ending this month, downloads of Vue 3 have reached nearly 50% with V3 adoption almost doubling in the past year.
Editor’s Note: Evan You’s first name was corrected in the photo caption.