Upgrade Guide
Upgrading from v2 to v3
Application Initialization Changes
In Vue 2, the app was initialized like this:
import Vue from "nativescript-vue";
import Home from "./components/Home.vue";
new Vue({
render: (h) => h("frame", [h(Home)]),
}).$start();
In Vue 3, you now use createApp
:
import { createApp } from "nativescript-vue";
import Home from "./components/Home.vue";
const app = createApp(Home);
app.start();
✅ Key Changes:
- Use
createApp(Home)
instead ofnew Vue()
. - The root
<Frame>
component should now be insideHome.vue
(depending on your frame/navigation setup), not in thecreateApp
function.
Navigation Changes in Vue 3
Navigation functions like $navigateTo
, $navigateBack
, and $showModal
must now be imported instead of being accessed from this
.
<script lang="ts" setup>
import { $navigateTo, $navigateBack, $showModal } from "nativescript-vue";
import MyComponent from "./components/MyComponent.vue";
function navigate() {
$navigateTo(MyComponent, {
/* options */
});
}
function goBack() {
$navigateBack();
}
function openModal() {
$showModal(MyComponent, {
/* options */
});
}
</script>
✅ Why the change?
Vue 3 now uses composition API and removes
$navigateTo
from the component instance.
Note Vue3 also supports the options API, where these methods are still available on
this
, however we recommend using the composition API.
Plugin Registration
Plugins are now registered using registerElement
instead of modifying the Vue instance.
Before (Vue 2)
import Vue from "nativescript-vue";
Vue.registerElement(
"Gradient",
() => require("nativescript-gradient").Gradient
);
Now (Vue 3)
import { createApp, registerElement } from "nativescript-vue";
import Home from "./components/Home.vue";
registerElement("Gradient", () => require("nativescript-gradient").Gradient);
// or using import statements
import { Gradient } from "nativescript-gradient";
registerElement("Gradient", () => Gradient);
const app = createApp(Home);
app.start();
✅ Note Some plugins export a Vue3 compatible plugin, that can be used with
.use()
, like@nativescript-community/ui-collectionview/vue3
. Consult the plugin documentation and if it doesn't specify this, useregisterElement
normally.
import { createApp } from "nativescript-vue";
import Home from "./components/Home.vue";
import CollectionView from "@nativescript-community/ui-collectionview/vue3";
const app = createApp(Home);
app.use(CollectionView);
app.start();
ListView Changes
- Instead of
for="item in listOfItems"
, use:items="items"
- Instead of
if="condition"
us:itemTemplateSelector="function"
- Use
#default="{ item, index }"
inside<template>
Before (Vue 2)
<ListView for="item in listOfItems">
<v-template>
<label :text="item.text" />
</v-template>
<v-template if="item.odd">
<label :text="item.text" class="bg-red-500" />
</v-template>
</ListView>
Now (Vue 3)
<script lang="ts" setup>
const items = ref([
/* ... items... */
]);
function itemTemplateSelector(item, index) {
return index % 2 === 0 ? "default" : "odd";
}
</script>
<template>
<ListView :items="items" :itemTemplateSelector="itemTemplateSelector">
<template #default="{ item, index }">
<label :text="item.text" />
</template>
<template #odd="{ item, index }">
<label :text="item.text" class="bg-red-500" />
</template>
</ListView>
</template>
🚀 Bonus: You can now strongly type item
using TypeScript!
<template
#default="{ item, index }: { item: MyType, index: number }"
></template>
Or, using the ListItem
helper type:
<template #default="{ item, index }: ListItem<MyType>"></template>