:question: What is it?
Version of Bootstrap-Vue which works for Vue 2 and Vue 3 (using @vue/compat
)
Helps people with #5196
Demo using Vue 2
Demo using Vue 3
Additionally, it passes all (well, almost all, tiny fraction of tests are disabled because they are irrelevant for vue 3) tests in the test suite (it would be literally impossible to do this migration without a test suite)
This package uses vue 3 by default. If you want to run tests, build, etc. using vue 2 pass USE_VUE2=1
environment variable
:exclamation: How is this possible?
The heart of this PR consists of two parts:
:wrench: How could I run it?
If you want just to play around - you can clone https://github.com/xanf/bootstrap-vue3-demo which has all required setup. If you want to try it on your own project, there is some setup required.
I'm skipping setup of @vue/compat
, it is described in migration guide
You will need to monkey patch your Vue 3 a bit somewhere early in your app:
const originalVModelDynamicCreated = Vue.vModelDynamic.created;
const originalVModelDynamicBeforeUpdate = Vue.vModelDynamic.beforeUpdate;
Vue.vModelDynamic.created = function (el, binding, vnode) {
originalVModelDynamicCreated.call(this, el, binding, vnode);
if (!el._assign) {
el._assign = () => {};
}
};
Vue.vModelDynamic.beforeUpdate = function (el, binding, vnode) {
originalVModelDynamicBeforeUpdate.call(this, el, binding, vnode);
if (!el._assign) {
el._assign = () => {};
}
};
See https://github.com/vuejs/vue-next/pull/4121 for details
If your intention is to run your app in { MODE: 2 }
(default @vue/compat) you're done.
If you want to have { MODE: 3 }
(so all compats are disabled by default), additional setup is needed:
- if https://github.com/vuejs/vue-next/pull/4974 is not yet merged - you need to build
@vue/compat
build with this fix included. https://github.com/xanf/bootstrap-vue3-demo already has patch inside patches
folder for that, installed by patch-package
- Certain compat flags required to be enabled globally ATM and can't be disabled in this release (which maintains Vue 2 and Vue 3 compatibility):
GLOBAL_EXTEND
, GLOBAL_MOUNT
- for using new Vue
inside bootstrap-vue
COMPONENT_FUNCTIONAL
, RENDER_FUNCTION
CUSTOM_DIR
(anywhere where you use bootstrap-vue directive)
If you use portal-vue
(which is still used for tooltips, etc.) you will need:
If you use old (for Vue 2) version of vue-router you will need:
CONFIG_OPTION_MERGE_STRATS
GLOBAL_PRIVATE_UTIL
GLOBAL_PROTOTYPE
INSTANCE_EVENT_HOOKS
OPTIONS_DESTROYED
INSTANCE_EVENT_EMITTER
:bomb: What might not work
- Docs. I've tried to make
Nuxt
run using newer Nuxt 3, bridge, etc. but it was very problematic. So I wrote a script, which extracted demos from docs and generated https://github.com/xanf/bootstrap-vue3-demo with all demos
- Build. It might or might not work, I didn't have an opportunity to test it yet
:arrow_upper_right: What's next?
Let's treat this one as "bridge" version
Based on this branch I will create another one, which will be focused solely on full vue 3 compatibility (without using @vue/compat). While this will definitely take time, right now I do not see any major obstacles in gradual migration
:hugs: That's cool, how could I say "thank you"?
You're welcome, it's all about opensource. However, there are certain things, where your help will be appreciated:
- Help me spread the word about vue-test-utils-compat. You can retweet me or just drop a link to your friend who could be interested
- Check deployed versions of https://github.com/xanf/bootstrap-vue3-demo (links inside) and report about any issues you find out in Vue 3 version (it is very time consuming to test all possible scenarios)
PR checklist
What kind of change does this PR introduce? (check at least one)
- [ ] Bugfix (fixes a boo-boo in the code) -
fix(...)
, requires a patch version update
- [x] Feature (adds a new feature to BootstrapVue) -
feat(...)
, requires a minor version update
- [ ] Enhancement (augments an existing feature) -
feat(...)
, requires a minor version update
- [ ] ARIA accessibility (fixes or improves ARIA accessibility) -
fix(...)
, requires a patch or minor version update
- [ ] Documentation update (improves documentation or typo fixes) -
chore(docs)
, requires a patch version update
- [x] Other: major update
Does this PR introduce a breaking change? (check one)
- [x] No (I know it's hard to believe)
- [ ] Yes (please describe since breaking changes require a minor version update)
The PR fulfills these requirements:
- [x] It's submitted to the
dev
branch, not the master
branch
- [x] When resolving a specific issue, it's referenced in the PR's title (i.e.
[...] (fixes #xxx[,#xxx])
, where "xxx" is the issue number)
- [x] It should address only one issue or feature. If adding multiple features or fixing a bug and adding a new feature, break them into separate PRs if at all possible.
- [x] The title should follow the Conventional Commits naming convention (i.e.
fix(alert): not alerting during SSR render
, docs(badge): update pill examples
, chore(docs): fix typo in README
, etc.). This is very important, as the CHANGELOG
is generated from these messages, and determines the next version type (patch or minor).
If new features/enhancement/fixes are added or changed:
- [ ] Includes documentation updates
- [ ] Includes component package.json meta section updates (prop, slot and event changes/updates)
- [ ] Includes any needed TypeScript declaration file updates
- [ ] New/updated tests are included and passing (required for new features and enhancements)
- [x] Existing test suites are passing
- [x] CodeCov for patch has met target (all changes/updates have been tested)
- [x] The changes have not impacted the functionality of other components or directives
- [ ] ARIA Accessibility has been taken into consideration (Does it affect screen reader users or keyboard only users? Clickable items should be in the tab index, etc.)
If adding a new feature, or changing the functionality of an existing feature, the PR's
description above includes:
- [x] A convincing reason for adding this feature (to avoid wasting your time, it's best to open a suggestion issue first and wait for approval before working on it)