Published on

Vue 3 as the New Default

Authors

TL;DR: Vue 3 is now the new default version as of Monday, February 7, 2022!

Make sure to read the Potential Required Actions section to see if you need to make certain changes before the switch to avoid breakage.

From a Library to a Framework ​

When Vue first started, it was just a runtime library. Over the years, it has evolved into a framework that encompasses many sub projects:

  • The core library, i.e. the vue npm package
  • The documentation, with enough content to be considered a book
  • The build toolchain, i.e. Vue CLI, vue-loader and other supporting packages
  • Vue Router for building SPA
  • Vuex for state management
  • Browser devtools extension for debugging and profiling
  • Vetur, the VSCode extension for Single-File Component IDE support
  • ESLint plugin for static style / error checking
  • Vue Test Utils for component testing
  • Custom JSX transforms that leverages Vue's runtime features
  • VuePress for Vue-based static site generation

This is only possible because Vue is a community-driven project. Many of these projects were started by community members who later became Vue team members. The rest were originally started by me, but are now almost entirely maintained by the team (with the exception of the core library).

Soft Launch of Vue 3 ​

With the core releasing a new major version, all the other parts of the framework needed to move forward together. We also needed to provide a migration path for Vue 2 users. This was a massive undertaking for a community-drive team like Vue. When Vue 3 core was ready, most other parts of the framework were either in beta or still awaiting update. We decided to go ahead and release the core so that the early adopters, library authors and higher-level frameworks can start building with it while we worked on the rest of the framework.

At the same time, we kept Vue 2 as the default for documentation and npm installs. This is because we knew that for many users, Vue 2 still provided a more coherent and comprehensive experience until other parts of Vue 3 are refined.

The New Vue ​

This soft launch process took longer than we hoped, but we are finally here: we are excited to announce that Vue 3 will become the new default version on Monday, February 7, 2022.

Outside of Vue core, we have improved almost every aspect of the framework:

  • Blazing fast, Vite-powered build toolchain
  • More ergonomic Composition API syntax via <script setup>
  • Improved TypeScript IDE support for Single File Components via Volar
  • Command line type checking for SFCs via vue-tsc
  • Simpler state management via Pinia
  • New devtools extension with simultaneous Vue 2 / Vue 3 support and a plugin system that allows community libraries to hook into the devtools panels

We also completely reworked the main documentation. The new vuejs.org (currently in staging) will provide updated framework overview and recommendations, flexible learning paths for users from different backgrounds, the ability to toggle between Options API and Composition API throughout the guide and examples, and many new deep dive sections. It's also very fast - which we will discuss in more details in a separate blog post soon.

Version Switch Details ​

Here are the details on what we mean by "the new default". In addition, please read the Potential Required Actions section to see if you need to make certain changes before the switch to avoid breakage.

npm dist tags ​

  • npm install vue now installs Vue 3 by default.

  • The latest dist tag of all other official npm packages now point to Vue 3 compatible versions, including vue-router, vuex, vue-loader, and @vue/test-utils.

Official docs and sites ​

All documentation and official sites now default to Vue 3 versions. These include:

  • vuejs.org
  • router.vuejs.org
  • vuex.vuejs.org
  • vue-test-utils.vuejs.org (moved to test-utils.vuejs.org)
  • template-explorer.vuejs.org

The current Vue 2 versions of these sites have been moved to new addresses (the version prefixes indicate the libraries' respective versions, not Vue core's):

  • vuejs.org -> v2.vuejs.org (old v2 URLs will auto redirect to the new address)
  • router.vuejs.org -> v3.router.vuejs.org
  • vuex.vuejs.org -> v3.vuex.vuejs.org
  • vue-test-utils.vuejs.org -> v1.test-utils.vuejs.org
  • template-explorer.vuejs.org -> v2.template-explorer.vuejs.org

GitHub repos ​

All GitHub repos under the vuejs organization have switched to Vue 3 versions in the default branch. In addition, we have renamed the following repos to remove next in their names:

Translation repos for the main documentation are moved to the vuejs-translations organization.

GitHub handles repo directs automatically, so previous links to source code and issues should still work.

Devtools extension ​

Devtools v6, which was previously published under the beta channel on Chrome Web Store, is now published under the stable channel.

The previous version of the devtools extension is still be available and has been moved to the legacy channel.

Potential Required Actions ​

Unversioned CDN Usage ​

If you are using Vue 2 via a CDN link without specifying a version, make sure to specify a version range via @2:

diff
- <script src="https://unpkg.com/vue"></script>
+ <script src="https://unpkg.com/vue@2"></script>

- <script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
+ <script src="https://cdn.jsdelivr.net/npm/vue@2/dist/vue.min.js"></script>

Note: even if using Vue 3, you should also always specify a version range in production to avoid accidentally loading future major versions.

NPM latest Tag ​

If you are installing Vue or other official libraries from npm using the latest tag or *, please update to explicitly use Vue 2 compatible versions:

diff
{
  "dependencies": {
-   "vue": "latest",
+   "vue": "^2.6.14",
-   "vue-router": "latest",
+   "vue-router": "^3.5.3",
-   "vuex": "latest"
+   "vuex": "^3.6.2"
  },
  "devDependencies": {
-   "vue-loader": "latest",
+   "vue-loader": "^15.9.8",
-   "@vue/test-utils": "latest"
+   "@vue/test-utils": "^1.3.0"
  }
}