Update to Vue 3.0 before Vue 2 reaches End of Life

[NateWr]

Discussed in #7971

^{Originally posted by NateWr September 21, 2020}
Vue 3.0 has been released. Look into whether we can update and what breaking changes we'll need to navigate,. It is supposed to be largely compatible with 2.x, but many of the third-party dependencies we use may not yet be ready for the jump.

I've converted this back into an issue because Vue 2 will reach end of life on Dec 31, 2023. An upgrade needs to happen before then: https://v2.vuejs.org/lts/

[jardakotesovec]

(Reposted as last comment, so its not hidden among the commit notifications)

Because most of the dependencies were not vue3 compatible and in couple of cases they are abandoned - this end up being quite big update, including migrating to some better maintained dependencies. Apologise for big amount of changes to look at. I will try to sum up all notable changes here, which should help to understand the changes.

I will also add couple of notes to the PRs as well, but if you are curious and not sure why some change was done, feel free just ask on the PRs via comment and I will elaborate.

Todo

• Update ui-library docs about modal changes (will handle that in separate issue) to not hold review on this one
• create issue for upgrading to tinymce 6.
• Create separate issue to investigate replacing vue3-dropzone
• Create issue to do some testing on browserstack with above browsers before releasing new version to potentially fine tune the build setup if something is missing (more details below in browser support)

Dependencies

@tinymce/tinymce-vue && tinymce

Updated from @tinymce/tinymce-vue@3 to @tinymce/tinymce-vue@5.1.1 for vue3 support. Had some API breaking changes, thats adjusted.

Kept tinymce itself on version 5. As there is significant number of breaking changes for latest version 6. Better to deal with it separately as tinymce-vue@5 is compatible with both tinymce 5 and tinymce 6.

vue-announcer

Updated vue-announcer@1.0.6 to @vue-a11y/announcer@3.1.5, which is continuation of previous package and has vue3 support. This package has been updated in 2021, so also not under active development. There is no clear successor. Given its pretty small and simple dependency - replacing this with some other alternative is low priority.

v-tooltip

v-tooltip@2.0.3 is migrated to floating-vue@2.0.0-beta.24, which is continuation of previous package. Its relying on floating.js instead of popper.js as more modern and lightweight replacement. Its unfortunate its still marked as beta, but its being actively maintained and issues are being addressed. There were some breaking changes in API, which are addressed.

We now relying on their css styling with just few overrides to make the text smaller, rather than having entirely own css styling, as the html structure completely changed, so we can't easily use the styling we had before. And maintaining just couple of overrides is probably easier over time as new versions might have some significant internal changes as well.

vue-chartjs

Updated from vue-chartjs@3.5.1 to latest version vue-chartjs@5.2.0. Which means also moving from chart.js@2.9.4 to latest chat.js@4.3.3. That included lots of breaking changes - lots of options were changed. Its all updated in these PRs with intention to keep the chart styling almost entirely same.

vue-scrollto

Very rarely used in our code base, I did test it in ui-library in Steps component and works as before using same version. There is no new version for this package. At some point can be replaced with native scroll, but I think its low priority.

vue2-dropzone

At this point both original package and underlying dropzone.js package are unmaintained. As its relatively complex package, which is heavily used - I found drop-in replacement (just original updated to vue3) dropzone-vue3@1.0.2 to avoid big changes that would require to test lots of scenarios. This can be dealt with independently.

vue-autosuggest

Updated from vue-autosuggest@2.2.0 to @headlessui/vue/combobox@1.7.15.

https://headlessui.com is currently one of the better options for Vue.js to get good functionality&accessibility and easily make own css styling - currently well maintained by tailwindcss team.

There is small change in behaviour when first matching item gets automatically highlighted without pressing keydown. That seems to be within aria specification as there is couple of options. While testing - announcing options in Safari via VoiceOver was not working properly - did report that in the library.

Can be tested in ui-library under FieldBaseAutosuggest.

vue-js-modal

This one is abandoned with no vue3 support. Migrated to @headlessui/vue/dialog@1.1.16. This is first place to test tailwindcss in the setup. And see the benefit of being able to take tailwindcss examples and tweak them easily.

vue-js-modal was maintaining pool of modals and rendering them to special div, next to the body, which is useful for making rest of the DOM disabled for screen readers.

headlessui are using vue3 portals to do the same thing, which is new feature, but does not require to explicitly maintaining that. And headlessui is utilising that on the background. As result the $modal API to manage modals via global names is not necessary anymore.

Therefore decided that for modals - their state (open/close) is managed by the component which is rendering them.

For dialogs its bit more complicated, because dialogs in our case are driven just by the data structure, not really existing in templates. Also we have cases where we open dialog from autosave mixin - and mixin for sure does not have template where the dialog would live. In this case decided to mimic the openDialog mixin API. Which just works bit differently internally. So the Dialog lives in backend.tpl and mixin just passes correct props to it and opens it.

Also note that explicit focusing to the last element is removed from the code base, that per my testing works automatically now.

vue-color

Updated from vue-color@2.7.1 to @lk77/vue3-color@3.0.6, which is drop-in replacement with vue3 support. Last updated year ago, but also not having any issues on github. I think we can stick with this one for some time, before moving to some bigger replacement. But opened to suggestions if you know good alternative.

vuedraggable

Updated vuedraggable@2.24.3 to vue-draggable-plus@0.2.4, which is also pretty much drop-in replacement for vue3. Quite well maintained at the moment despite the low version number. Its also based on sortable.js.

Will discuss with @Devika008, whether in long term we want to keep that functionality around, as its additional option for our Orderer, which already has option to change order by clicking on arrows. This is just bonus to be able to drag&drop the items. Maybe it could be opportunity to reduce our dependencies.

Vue3 breaking changes

this.$children does not exist anymore

Components Steps.vue and Tabs.vue were relying on $children to read props from children component Step.vue and Tab.vue respectively. This has been reworked to use provide and inject to exchange the data. Great benefit is that even if the tab is not directly children - it still would connect correctly. Which might be useful in future as we add some options to inject components to various places for extensibility (likely using some wrapper components).

slot-scope is reworked

Syntax for slots and scoped slots has been reworked - thats more in detail here. So thats adjusted accordingly.

invidiual vue instance via createApp

Vue2 had one global instance, which is now changed, so its more flexible to create as many instances as needed with different mixins/components etc. For that reason I had to create pkpCreateVueApp function which adds all the mixins and components for every instance that we create, as we do create multiple vue instances.

Global events handling

Vue2 instance was used to be able to emit and listen to events, that API is gone in vue3 and being replaced with tiny-emmiter.

Vue3 does not like any data starting with _ or $

This is now considered as potential conflict with private API. And until I replaced all translation calls from this.__('') to this.t('') it was complaining and crashing about __ being non-existent.

Vue3 lifecycle methods changes

• The destroyed lifecycle option has been renamed to unmounted
• The beforeDestroy lifecycle option has been renamed to beforeUnmount

Various small changes in behaviour

• vue3 is by default removing spaces between html tags, which resulted in missing spaces in some places - this was adjusted by the whitespace: 'preserve' option
• its more strict about what attributes exist on each html element. As result disabled works differently on element in vue3 as its not valid attribute by html specification.
• vue3 is more strict on stoping executing if there is exception in mount or some other lifecycle methods, which revealed some crashes that was not noticed before

Webpack -> Vite

As Vite is default build tooling I migrated from webpack.

Browser support

Vite has bit confusing documentation on browser support. My understanding is that without polyfills from vitejs/plugin-legacy we should be able to go as low as 'chrome64','edge79', 'firefox67','safari12', as all these support all modules features. Which should be perfectly sufficient.

I did not find very clear explanation why they picked the version they have on browser support page. There is opened issue about it, but not really clear summary.

Rollup is using esbuild, which transpiles most of newer syntaxes (that are not supported in our target) to older syntax. But for example If we use some latest features like BigInt, it would produce error as its not possible to transpile that one. Only thing that is not really guaranteed is potential need for pollyfills. At this point I can't think of anything that we would need thats not supported in the targeted browser above, but there is always risk that some of our dependencies would use something.

vitejs/plugin-legacy claims to be able to detect polyfills based on actual use, which sounds great, but documentation is not clear how to use it in case we don't want to target legacy browsers that don't support modules and just detect whether there is need for polyfills. So at this point I decided to not use it - to not make our build over-complicated, because its most likely not needed. Will create separate issue for testing our targeted browsers when we are closer to end cycle.

raw-loader

Rollup allows to load raw file via ?raw instead of raw-loader, which is handy in ui-library.

Eslint & Prettier

There are two main options how to use eslint and prettier together. Either to use eslint prettier plugin so the code formatting happens as part of eslint --fix process. Or second one is to keep them separate by applying set of rules in eslint to disable formatting specific rules and let eslint just deal with JS specific mistakes, but not to worry about formatting.

Second approach is currently recommended - to keep them separate to avoid conflicts, having good performance and also its nice if your code does not get eslint warnings in VSCode just because it has not been formatted properly yet.

As we are not using vue-cli-services as thats deprecated, I had to adjust setup to use husky to run the eslint and prettier on pre-commit hook on changed files. It works as follows

• "prepare": "husky install" is run on npm install, to setup hooks in .git
• in .husky/pre-commit it triggers lint-staged
• lint-staged runs the commands that are defined in package.json, only on newly staged files

I was trying to avoid any significant formatting changes to be applied to the code, which would make review difficult. There is couple of small things that came through (trailing commas mainly), but hopefully not too distracting. Intention was to keep the formatting as similar to before. Notable formatting changes you can see in the docs folder, as probably prettier was not used on the md files before. I kept these changes, as I did not really change anything important in the docs so I hope its ok.

Tailwindcss

Tailwind is now introduced to the build step - and its being used just for the modals. There is more to configure based on Devika design patterns she has been working on. That will be worked on separately.

ojs: pkp/ojs#4032
ojs-test: pkp/ojs#4043
ops: pkp/ops#571
ops-test: pkp/ops#572
omp: pkp/omp#1463
omp-test: pkp/omp#1464
pkp-lib: #9280
ui-library: pkp/ui-library#286