Skip to content

Commit a5068b3

Browse files
rigor789rigor789
authored
Update 4-upgrade-guide.md
1 parent d172ee4 commit a5068b3

File tree

1 file changed

+15
-176
lines changed

1 file changed

+15
-176
lines changed

‎content/docs/en/getting-started/4-upgrade-guide.md

Lines changed: 15 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -6,193 +6,32 @@ outdated: false
66

77
> Estimated time for the upgrade: **10-20 minutes**.
88
9-
If you scaffolded a NativeScript-Vue app using the 1.3.1 version of the Vue-CLI template, it's time to upgrade to the newest 2.0 version. This guide will help you do that.
9+
To upgrade to NativeScript 8.0, start with a clean branch.
1010

11-
## Upgrade overview
11+
Install latest NativeScript CLI:
1212

13-
The new template has a different folder structure:
14-
15-
![New folder structure](/screenshots/old-new-folder-structure.png)
16-
17-
The simplified upgrade process involves:
18-
19-
1. Creating a new project from the updated template.
20-
1. Copying files from your old app into the new one.
21-
1. Rearranging and adding some files.
22-
23-
## Step 1: Create new app
24-
25-
Use the Vue-CLI template to create a new app. Make sure to run the same preinstallation commands that you used for the old version. For example, if you installed Vuex in the CLI the first time, do it again now.
26-
27-
Run the following command to create a new project from the Vue-CLI template.
28-
29-
```shell
30-
$ npm install -g @vue/cli @vue/cli-init
31-
$ vue init nativescript-vue/vue-cli-template <project-name>
32-
$ cd <project-name>
33-
$ npm install
34-
$ tns preview
35-
$ # or
36-
$ tns run
37-
```
38-
39-
## Step 2: Replace `App_Resources`
40-
41-
*iOS*: Copy your old app's `./template/app/App_Resources/iOS` folder. Then, paste it into the new app's `app/App_Resources` folder. Make sure that you're replacing the new `App_Resources/iOS` folder.
42-
43-
*Android*: Copy all the contents of your old app's `./template/app/App_Resources/Android` folder. Next, paste it into the new app's `app/App_Resources/Android/src/main/res` folder.
44-
45-
46-
## Step 3: Merge the `src` and `app` folders
47-
48-
Copy all the folders in `src` from your old app and paste them into the `app` folder in the new app.
49-
50-
If you have custom fonts, move the contents of the `src/assets/fonts` folder to `app/fonts`. This ensures that NativeScript will load your custom fonts automatically.
51-
52-
## Step 4: Edit `main.js`
53-
54-
Edit `main.js`'s Vue initialization block to resemble:
55-
56-
```js
57-
new Vue({
58-
render: h => h('frame', [h(HelloWorld)]),
59-
}).$start();
60-
```
61-
62-
NativeScript 4.0 brings two major improvements:
63-
64-
* a new `<Frame>` element
65-
* a new way to change the root element of your app that lets you share common view elements across pages (navigations).
66-
67-
Before NativeScript 4.0, the root element was a `<Frame>` element which was implicitly created by NativeScript when the application started.
68-
69-
With the latest changes, `<Frame>` and `<Page>` elements are no longer automatically created. So, in NativeScript-Vue 2.0.0, you need to explicitly add these elements to your template.
70-
71-
To keep the previous behavior of having a single root `<Frame>`, you can change your root Vue instance to have a `<Frame>` and a `<Page>` element.
72-
73-
**Example: Adding `<Frame>` and `<Page>` to the template**
74-
75-
```JavaScript
76-
// in older versions
77-
// this automatically created a Page
78-
new Vue({
79-
template: `<Label text="Hello world"/>`
80-
}).$start()
13+
```bash
14+
$ npm install -g nativescript
8115
```
8216

83-
```JavaScript
84-
// in NativeScript-Vue 2.0.0
85-
// the <Frame> and <Page> must exist in your template
86-
new Vue({
87-
template: `
88-
<Frame>
89-
<Page>
90-
<Label text="Hello world"/>
91-
</Page>
92-
</Frame>
93-
`
94-
}).$start()
95-
```
96-
97-
This lets you use a shared element across different pages.
98-
99-
**Example: Using a shared `<SideDrawer>` element**
100-
101-
```js
102-
new Vue({
103-
template: `
104-
<RadSideDrawer>
105-
<StackLayout ~drawerContent>...</StackLayout>
106-
<Frame ~mainContent>
107-
<Page>
108-
<Label text="Hello world"/>
109-
</Page>
110-
</Frame>
111-
</RadSideDrawer>
112-
`
113-
}).$start()
114-
```
115-
116-
## Step 5: Edit paths
117-
118-
Because the folder structure has changed, you need to edit the paths in your new app to point to your styles, fonts, and images.
119-
120-
**Example: Changing image references**
121-
122-
In your old app, you are likely to have referenced images like this.
123-
124-
```HTML
125-
<Image v-if="surprise" src="~/images/NativeScript-Vue.png"/>
126-
```
127-
128-
To ensure that NativeScript loads the images, change the path reference to the following.
129-
130-
```HTML
131-
<Image v-if="surprise" src="~/assets/images/NativeScript-Vue.png"/>
132-
```
133-
134-
## (If needed) Step 6: Fix manual routing props
135-
136-
If your app uses manual routing, the syntax for passing props has changed. Note that this change might not be required in all projects.
137-
138-
Your old syntax is likely to look like this.
17+
Verify you are on the latest version by running `ns -v`.
13918

140-
```JavaScript
141-
this.$navigateTo(NewPage, {
142-
transition: {},
143-
transitioniOS: {},
144-
transitionAndroid: {},
19+
In your project run
14520

146-
context: {
147-
propsData: {
148-
name: this.name,
149-
value: this.value
150-
}
151-
}
152-
});
21+
```bash
22+
$ ns migrate
15323
```
15424

155-
To preserve the manual routing behavior in your new app, change your syntax to the following:
156-
157-
```JavaScript
158-
this.$navigateTo(NewPage, {
159-
transition: {},
160-
transitioniOS: {},
161-
transitionAndroid: {},
162-
163-
props: {
164-
name: this.name,
165-
value: this.value
166-
}
167-
});
168-
```
25+
This should get your project up-to-date with the latest dependencies. Some other things you may need to change:
16926

170-
## Step 7: Align `package.json`
171-
172-
Copy the relevant values from your old app's root `package.json` file into the new app's root `package.json` file.
173-
174-
You will likely need to copy the `Dependencies:` block and, in some cases, realign the new app's app version and description at the top of `package.json`.
175-
176-
## Step 8: Clean and run
177-
178-
Run the following command to clean the new app's folders and reinstall any dependencies.
179-
180-
```shell
181-
$ cd <project-name>
182-
$ rm -rf platforms
183-
$ npm install
184-
$ tns run
185-
```
27+
If you still have imports from `tns-core-modules`, you will have to update them to use `@nativescript/core`, see the import reference guid in the NativeScript blog: https://blog.nativescript.org/nativescript-7-import-reference/index.html/
18628

187-
## (Optional) Step 9: Try HMR
29+
In your css, if you have imports that start with `~` you need to remove the tildes:
18830

189-
NativeScript now provides support for HMR (Hot Module Replacement). The latest version of NativeScript-Vue provides out-of-the-box HMR support as well but requires the NativeScript CLI.
31+
```css
32+
@import "~@nativescript/theme/..."
19033

191-
Run the following command to get HMR support by installing the latest and greatest version of the NativeScript CLI.
34+
/* becomes */
19235

193-
```shell
194-
$ npm install -g nativescript@next
195-
$ cd <project-name>
196-
$ rm -rf platforms
197-
$ tns run
36+
@import "@nativescript/theme/..."
19837
```

0 commit comments

Comments
 (0)