Steps Needed for Vue Migration (Vue 2 -> Vue 3)

[gerteck]

Any related issues?

#2084 Vue Migration Investigation

Others:

• Bootstrap 5 #1702 Bootstrap 5
• Change $scopedSlots back to $slots when Vue is upgraded to v3.0 #1536 scopedSlots depreciation

Vue Migration Vue 2 to Vue 3

MarkBind (v5.5.3) is currently using Vue 2. Vue2 has reached EOL, (end-2023) and will not receive any type of support. Packages supporting Vue2 used may not be maintained by extension. This limits the extensibility and maintainability of MarkBind, especially the vue-components package. (UI Library Package).

Vue3 has TypeScript support, noticeable performance improvements and more responsive application. Also has smaller bundle size. Do note that Vue 3 does not support IE13 (internet explorer). Note that the migration is a time intensive process with codebase understanding required. Currently, MarkBind Vue components are authored in the Vue Options API style. While migrating to Vue 3, we should continue to use this API style. Future work can consider cost benefit of switching to using Composition API.

Breaking changes to expect include: breaking Vue framework API changes, different dependencies used for Vue 2 vs Vue 3, SSR.

Intricate understanding of both Vue 2, Vue 3, low-level dependency APIs and MarkBind (in particular with regards to SSR, Hydrating, Bundling) is needed to conduct this. Some relevant links to understanding / reviewing the PR:

• Vue 3 API Reference
• Vue SFC
• Vue Rendering Mechanism
• Vue Migration Build
• @vue/compiler-sfc
• @vue/server-renderer

Additionally, here are some relevant documentation of the codebase I have written and compiled to speed up the understanding process for purpose of peer development/review.

• pageVueServerRenderer
• Core-Web Package
• Vue-Components

Work To-Do

Compilation and SSR of Vue (Core):

Page/PageVueServerRenderer.ts needs to be updated

1. 'vue-template-compiler' has been replaced by '@vue/compiler-sfc', hencecompileVuePageAndCreateScript method which compiles page into Vue Application to get the render function must be updated. For Vue 3, the way the render function is created and consumed is different. Do this without disabling SSR.
2. renderVuePage: Method that Renders Vue page app into html string (Vue SSR). Ensure that it works during migration process. Updated to use @vue/server-render package for Vue3
3. Ensure no regressions, do testing etc.

Webpack bundling (Core-Web)

Core-Web library needs to be updated

1. Update core-web/src/index.js setup() process. Ensure setup functions for mounting Vue apps are not affected. Updated to use new Vue app instance setup API.
2. Update vue-loader package
3. Update webpack configurations if relevant.
4. Ensure bundling no regressions, (to do after refactoring vue components)
5. VueCommonAppFactory.js.The appFactory helps create the Vue app instances needed for each page, to set up the necessary configurations. Configure it if necessary for Vue 3, and adapt if needed for compatibility with Vue3 components

Vue Components SFCs

Vue-Components Library needs to be updated

• Update vue-components SFCs.
• Update dependencies and librarie used
  Note: Vue 2 Options API -> Vue 3 Options API should not have too many changes. Should be the most straightforward process. However, a lot of dependencies have to be updated such as floating vue, etc.
• Ensure no regressions as in Modal content disppearing after reopening #1519

Vue Testing

Update all testing packages and dependencies

• Update testing dependencies for Vue 3
• Update tests (to be done after vue components refactoring)

Plugins:

Update necessary plugins (change in Vue directive API)

1. Ensure usability and non-regression of dataTable plugin as Vue Directive used.
2. Ensure usability and non-regression of Mermaid plugins as Vue Directive used.

Relevant Changelog Vue2 to Vue3: (FYI)

Global Mounting: Vue.js 2: The global Vue instance is used to mount the root component. Vue.js 3: Introduces createApp for creating the application instance and makes the mounting process more explicit.

Feature	Vue 2	Vue 3
Instance Creation	new Vue()	createApp()
Global Configuration	On Vue constructor	On app instance
Global APIs	Attached to Vue	Instance methods on app
Reactivity System	Object.defineProperty	Proxy
Composition API	Not available	Available
Fragments	Single root element required	Multiple root elements allowed
Teleport	Not available	Built-in <teleport> support

• In Vue 2, plugins add global level functionality. In Vue 3, each createApp call creates completely isolated app instance with its own config and global properties. Due to differences, the Vue instance is setup differently.
• Migrating from new Vue to createSSRApp(): case study here on using render function
• In Vue2, static render functions explicitly separated from main render function, but in Vue3, it is not. Hence, only one render function. (compileVuePageAndCreateScript)
• package vue-server-renderer is for Vue 2.0. Corresponding functionality for Vue 3 is in @vue/server-renderer, which is actually a dependency of the main vue package.

Custom Directives: Vue.js 2: Custom directives are registered globally using Vue.directive. Vue.js 3: Custom directives are registered using the app.directive method, making it more modular and scoped to the app instance.

FAQ

• What about considering letting vue2 and vue3 co-exist?
  We can use a migration build (Vue 2.7) that allows both Vue 2 & 3 code in a single codebase. Once done, migrate over to Vue 3. However, I faced some issues with getting @vue/compat to work.

Some other sources:

• Migration QA
• Vue2-Vue3 Differences
• Official Migration Guide

Describe alternatives you've considered

No response

Additional context

No response

[Tim-Siu]

Regarding #2475 and #2446

There seems to be a good documentation on Vue migration guide; custom directives API changes on custom directives.

Based on my understanding, we need to

1. Add instance creation with const app = Vue.createApp({})
2. Migrate from using inserted to mounted.

[gerteck]

Regarding #2475 and #2446

There seems to be a good documentation on Vue migration guide; custom directives API changes on custom directives.

Based on my understanding, we need to

1. Add instance creation with const app = Vue.createApp({})
2. Migrate from using inserted to mounted.

Realized it takes a bit more than that. In Vue 2, custom directives are registered globally using Vue.directive. However, in Vue , custom directives are registered using the app.directive method, making it more modular and scoped to the app instance.

This means that we can't just grab the global Vue instance and install the directive. We would have to register the directive on the current Vue instance we are using to render the page, before rendering or hydrating.

Maybe will consider
#2548 Support Mermaid Diagrams in Offline Mode
#2529 Make Mermaid, Datatables Default
since the overhaul is going to be necessary.

[Tim-Siu]

Regarding #2475 and #2446
There seems to be a good documentation on Vue migration guide; custom directives API changes on custom directives.
Based on my understanding, we need to

1. Add instance creation with const app = Vue.createApp({})
2. Migrate from using inserted to mounted.

Realized it takes a bit more than that. In Vue 2, custom directives are registered globally using Vue.directive. However, in Vue , custom directives are registered using the app.directive method, making it more modular and scoped to the app instance.

This means that we can't just grab the global Vue instance and install the directive. We would have to register the directive on the current Vue instance we are using to render the page, before rendering or hydrating.

Maybe will consider #2548 Support Mermaid Diagrams in Offline Mode #2529 Make Mermaid, Datatables Default since the overhaul is going to be necessary.

Hi @gerteck,

Thank you for your detailed analysis of the Vue 3 migration challenges, particularly around custom directives in the Mermaid and DataTables plugins.

I now understand that migrating these directives isn’t straightforward, as Vue 3 scopes directives to app instances, and plugins can’t access the app instance. This means the migration guide’s suggested changes won’t work here.

As Prof previously suggested, bundling external JS files directly (e.g., for Mermaid offline support (#2548)) aligns well with this migration. Integrating these features into the main app, rather than as plugins, seems beneficial. However, this might mean we can no longer opt out of using the two CSS libraries. Let’s see how Prof weighs this trade-off.

@damithc, could you share your thoughts on whether Mermaid and DataTables can be integrated as default features within the main app instead of optional plugins? This could simplify the migration process.

Thanks again for driving this effort, @gerteck.

[damithc]

@damithc, could you share your thoughts on whether Mermaid and DataTables can be integrated as default features within the main app instead of optional plugins? This could simplify the migration process.

What are the benefits of being able to opt out of these two features? For example, is there a notable difference in size/performance?
I believe there is also the aspect that we can keep it as a plugin (with offline support) and decide whether to enable/disable by default i.e., opt-out vs opt-in

[Tim-Siu]

Thanks Prof for the discussion. Keeping Mermaid and DataTables as plugins with offline support and deciding whether to enable/disable them by default (opt-out vs. opt-in) is an ideal approach.

However, I am not sure if it is feasible during this migration. The original implementation relies on custom directives, which seem no longer compatible with Vue 3 in the plugin environment. But I am not very sure. Maybe there is another implementation of the two plugins that can make it work.

[gerteck]

I think we could consider different implementations to make this work

Alternative Implementations

Mount Multiple Vue instance for each Mermaid Element

This is alternative to attaching the directive to parent app Vue instance. Initializing a new vue instance for each Mermaid diagram, registering the mermaid directive for that specific instance.
Ensures that each diagram has its own scoped configuration and avoids issues with Vue 3's global app instance limitations. However, this could lead to performance overhead if many Mermaid diagrams are rendered on a page. (Unsure)

Direct Mutation of Mermaid Elements

Directly mutate Mermaid elements outside of Vue’s reactive. Could involve simply manipulating the DOM and invoking Mermaid’s rendering functions manually on element. Since the mermaid script runs after html is hydrated by Vue, on client side.

Plugin vs. Default Features

Making it a plugin vs. default feature: I think if we make it default there are definitely size and performance impacts, thank you for pointing it out, overlooked this crucial aspect.

Considering this, I think it definitely makes sense to keep these features as plugins.

Difference in size / performance

A quick test on markbind.org shows
(dev tools -> sources -> plugins/dataTable/datatables.min.js || mermaid-5a5980d4.js or record network )

• mermaid.js file to be at 322kb,
• datatable.js + css file at 192kb
  (actual sizes after compression are 102+62kB)

which is actually quite hefty. E.g. if you load markbind.org, you need to process(~0.5 mb) of just the plugin js scripts even if no datatable or mermaid element on current page.

Potential Fix to complement trade-off of offline support and dynamic loading:
One quick way I can think of is that perhaps we can provide a toggle through plugin context to toggle between offline support (bundling js file) and dynamic online importing - what do you think?