Migration to Vue 3

[ShGKme]

Vue 3 Migration

Vue 2 EOL is 31 Dec 2023. Vue 3 migration is required.

Nextcloud Libraries overview

Repository	Vue 2	Vue 3	Comments
--- 📚 Frontend libraries ---
🟢 @nextcloud/vue	v8 (stable8)	v9-rc (main)	Everything is ready, RC released, final release soon
🟢 @nextcloud/dialogs	v6 (stable6)	v7-rc (main)	RC released
🟡 @nextcloud/upload	v1 (main)	branch:vue3	Outdated...
🟢@nextcloud/password-confirmation	v5 (stable5)	v6-rc (main)	RC released
--- 🛠️ Frontend tools ---
🟢 @nextcloud/eslint-config	v9 (main)	v9 (main)	👯 Demi support
🟢 @nextcloud/vite-config	v1 (stable1)	v2 (main)
🟢 @nextcloud/webpack-vue-config	v6 (master)	v6 (master)	👯 Demi support
🔴 @nextcloud/cypress	v1-beta (main)	-	Required for @nextcloud/upload but deprecated in favor of @nextcloud/e2e-test-server
--- 🪦 Deprecated libraries ---
🟢 nextcloud-vue-collections	v0.13.0 (stable0)	v1.0.0-alpha (main)
🔴 @nextcloud/vue-richtext	v2 (master)	-
🔴 @nextcloud/vue-dashboard	v2 (master)	-

Nextcloud Apps overview

App	Status	Comments
Server and apps	🔴 Not planned yet	Requires bundling change to support Vue 2 and Vue 3 in different apps
Activity	🔴 Not planned yet
Photos	🔴 Not planned yet
Viewer	🔴 Not planned yet
First run wizard	🟢 Migrated	Migrated for Nextcloud 32
Guests	🔴 Not planned yet
Log Reader	🔴 Not planned yet
--- Groupware ---
Calendar	🔴 Not planned yet
Contacts	🔴 Not planned yet
Mail	🔴 Not planned yet
--- Talk ---
Talk	🟡 WIP	Mostly migrated but abandoned
Notifications	🔴 Not planned yet
--- Office ---
Deck	🟡 WIP
Notes	🔴 Not planned yet
Text	🔴 Not planned yet
--- Workflowengine ---
Automated file tagging	🔴 Not planned yet
File access control	🔴 Not planned yet
File retention	🔴 Not planned yet
--- Apps ---
Tasks	🟢 Migrated
Forms	🟡 WIP
Polls	🟡 WIP
.	-- TBC --

Proposal for libraries

Supporting separated versions for Vue 2 and Vue 3 is complicated in the long run.

• Introduce a Vue 3 compatible version for every supported library
• Make a Vue 3 compatible version the default version (main)
• Make the first Vue 3 compatible release with minimal (breaking) changes to reduce migration effort and maintenance
  cost

Option 1: Forward-compatibility

To make migration simple, we may develop new major versions with forward compatibility from the previous version.

Ideally migrating to a new major version should be as simple as changing the version number in the package.json.

To archive this, we need to:

1. Always mark removed API as deprecated in the previous version.
2. When API is changed, provide a compatible

Then migrating to a new version is:

1. Stop using any deprecated API
2. Migrate
3. Bump version in dependencies
4. Migrate all the rest (should be minimal)

Option 2: demi-support

In some cases, the difference between Vue 2 and Vue 3 versions are minimal (mostly dependencies).
In theory, it is possible to build/publish both from the same source via:

• Universal dependencies
  • Example: @nextcloud/eslint-config
• Bundled dependencies at a cost of bundle size
  • Example: [RFC] build: bundle with Vue independent from environment nextcloud-libraries/nextcloud-password-confirmation#915
• Conditional dependencies
  • Example: feat: Vue 2 and Vue 3 compatibility nextcloud-libraries/webpack-vue-config#658

Note about apps public API relying on Vue

Some apps (e.g. viewer, workflowengine) have extension API via Vue components. This means that a Vue component from one
app (with one Vue library) is used in a Vue-component tree in another app (with another Vue library).
In general case, it is not supported by Vue. Even with Vue 2 apps it may not work without Module Federations. It will
not work with Vue 2 + Vue 3 mix at all.

Example: nextcloud-libraries/nextcloud-vue#6360

Explanation

Vue is stateful, and its rendering implementation uses Vue internal state.

workflowengine
├─── Vue_1
└─── <Workflow>
     └── <ConvertToPdf> - A component from ConvertToPdf app
          ├─── Vue_2
          └─── <NcSelect>

In this case, we have Vue.js framework twice in the document. It would be fine if they are used in different, separated
apps, rendering different nodes.

But in the Workflow app, <ConvertToPdf> and <NcSelect> component instances are rendered by Vue_1 module while they
actually include and use Vue_2.

During the rendering:

• Vue_1 creates <NcSelect> component instance and sets it as the currentInstance
• Vue_2 checks getCurrentInstance and has nothing. Vue_2 doesn't render anything.

In the past it worked at chance, because:

• Not very different Vue versions were used
  • e.g. Vue 2.7 workflow plugin may break in Vue 2.6 Workflow app
• Workflow components were simple objects and didn't import anything from Vue

Alternatives:

• Provide API to mount app inside an app
• Web Components

Some for other APIs, like exposing Vue Router instance or store as a public API.

Migration guide for Nextcloud Apps

How to prepare for the migration

TBC

How to migrate

TBC

[susnux]

🚀 Vue 3 🚀

I think this is only a library issue, because as soon as those are available apps can migrate whenever they want.
So it boils down to:

• nextcloud-vue
• nextcloud-upload
• nextcloud-dialogs

The password confirmation should normally not be important as no components are exported, this should be framework agnostic.
This currently can lead to issues because of vue dependency version clash. But if a proper framework agnostic solution is too complex, then we could also provide a bundled version for vue2 apps (vue3 bundled in the library) while vue3 apps can benefit from treeshaking and sharing vue code (we are talking about 150kb for vue2 apps).
➡ So both versions use the same source code.

The same I think is possible for the dialogs library.

I also do not think we need to care too much about keeping changes small, we do not do this when we do other major changes. Especially as there is quite few activity once a new major is release.
I do not mean to make everything breaking but only to directly do it the Vue 3 way if needed, instead of Frankenstein Vue 2 into Vue 3 code (example would be modelValue vs value).

---

Note about apps public API relying on Vue

💯 I agree! This is rather bigger issue as I think those APIs should all be fully framework agnostic.
It is not only the components shared, but also some expectations like that objects will be reactive, when passed through apps and API.

[ShGKme]

The password confirmation should normally not be important as no components are exported, this should be framework agnostic.
This currently can lead to issues because of vue dependency version clash. But if a proper framework agnostic solution is too complex, then we could also provide a bundled version for vue2 apps (vue3 bundled in the library) while vue3 apps can benefit from treeshaking and sharing vue code (we are talking about 150kb for vue2 apps).
➡ So both versions use the same source code.

That is exactly what is implemented in the linked PR.

Caveats: changing bundle size from 29.64 kB to 833.74 kB

[ShGKme]

Ah, or did you mean, that we can do

{
  "dependencies": {
    "@nextcloud/vue": "^8 || ^9",
    "vue": "^2 || ^3"
  }
}

?

Added this to the options.

[susnux]

Caveats: changing bundle size from 29.64 kB to 833.74 kB

For me it ends up with this:

dist/style.css   34.66 kB │ gzip:   4.74 kB
dist/index.mjs  645.54 kB │ gzip: 152.00 kB │ map: 2,026.08 kB

So yes a bigger bundle for vue2 apps in that case.

[ShGKme]

Ah, or did you mean, that we can do

{
  "dependencies": {
    "@nextcloud/vue": "^8 || ^9",
    "vue": "^2 || ^3"
  }
}

?

Added this to the options.

Nope, this requires building in post-install...

[Elrinth]

I thought today, 2025-05-13, I would be safe to convert my nextcloud apps from 2 to 3.

But no :) @nextcloud/dialogs still require vue 2.7. You can probably get similar functionality with some other toast systems.
Even after removing it:
"
Building myNextcloudApp 0.3.6

78% sealing chunk modules optimization ModuleConcatenationPlugin(node:49568) [DEP0180] DeprecationWarning: fs.Stats constructor is deprecated.
(Use node --trace-deprecation ... to show where the warning was created)
assets by status 9.11 MiB [cached] 8 assets

WARNING in ./node_modules/@linusborg/vue-simple-portal/dist/index.esm.js 36:22-32
export 'default' (imported as 'Vue') was not found in 'vue' (possible exports: BaseTransition"

So to anyone else trying, keep your vue 2 apps!

[ShGKme]

@nextcloud/dialogs still require vue 2.7

It is not: https://www.npmjs.com/package/@nextcloud/dialogs/v/7.0.0-rc.0

So to anyone else trying, keep your vue 2 apps!

There are several apps migrated already to Vue 3.