Skip to content

Proofreading Upgrade Guide #206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 16, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 65 additions & 45 deletions content/docs/en/getting-started/4-upgrade-guide.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,30 @@
---
title: Upgrade Guide
contributors: [rigor789, jlooper]
contributors: [rigor789, jlooper, ikoevska]
outdated: false
---

> Estimated time for the upgrade: **10-20 minutes**.

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 version, 2.0, and this guide will help you do that. The new template has a different folder structure from the older one:
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.

## Upgrade overivew

The new template has a different folder structure:

![New folder structure](/screenshots/old-new-folder-structure.png)

**Step 1**
The simplified upgrade process involves:

1. Creating a new project from the updated template.
1. Copying files from your old app into the new one.
1. Rearranging and adding some files.

## Step 1: Create new app

Start by creating a new app using the Vue-CLI template.
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.

> **TIP:** Make sure you use the same preinstallation commands in this new project that you used when creating the older version; for example, if you installed Vuex in the CLI the first time, do it again now.
Run the following command to create a new project from the Vue-CLI template.

```shell
$ npm install -g @vue/cli @vue/cli-init
Expand All @@ -26,38 +36,49 @@ $ # or
$ tns run ios --bundle
```

The upgrade process involves copying files from your old app into the new project and then rearranging and adding some files.
## Step 2: Replace `App_Resources`

**Step 2: Replace App Resources**
First, copy your old app's `App_Resources` folder from `./template/app/`. Next, paste it into the new app's `app` folder. Make sure that you're replacing the new `App_Resources` folder.

Copy your old app's `App_Resources` folder from `./template/app/` and paste it into the new app's `app` folder, replacing its `App_Resources` folder.
## Step 3: Merge the `src` and `app` folders

**Step 3: Merge `src` and `app` folders**
Copy all the folders in `src` from your old app and paste them into the `app` folder in the new app.

Copy all the folders in `src` from your old app and paste them into the `app` folder in the new app. If you have custom fonts, move the `src/assets/fonts` folder to `app/fonts` in order to let NativeScript to load them automatically.
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.

**Step 4: Edit `main.js`**
## Step 4: Edit `main.js`

NativeScript 4.0 introduced a new Frame element, and introduced a way to change the root element of our applications, allowing for sharing common view elements across pages (navigations).
Edit `main.js`'s Vue initialization block to resemble:

Prior to 4.0 the root element was a Frame, which was implicitly created by NativeScript when our application started.
```js
new Vue({
render: h => h('frame', [h(HelloWorld)]),
}).$start();
```

With these changes, we are no longer able to automatically create a Frame and Page elements, so in 2.0.0 you are required to explicitly add these elements to your template.
NativeScript 4.0 brings two major improvements:

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.
* a new `<Frame>` element
* a new way to change the root element of your app that lets you share common view elements across pages (navigations).

**Example**
Before NativeScript 4.0, the root element was a `<Frame>` element which was implicitly created by NativeScript when the application started.

```js
// in prior versions
With the latest changes, `<Frame>` and `<Page>` elements are longer automatically created. So, in NativeScript-Vue 2.0.0, you need to explicitly add these elements to your template.

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.

**Example: Adding `<Frame>` and `<Page>` to the template**

```JavaScript
// in older versions
// this automatically created a Page
new Vue({
template: `<Label text="Hello world"/>`
}).$start()
```

```js
// in 2.0.0
```JavaScript
// in NativeScript-Vue 2.0.0
// the <Frame> and <Page> must exist in your template
new Vue({
template: `
Expand All @@ -70,7 +91,9 @@ new Vue({
}).$start()
```

This allows us to use a shared SideDrawer across different pages for example:
This lets you use a shared element across different pages.

**Example: Using a shared `<SideDrawer>` element**

```js
new Vue({
Expand All @@ -87,37 +110,31 @@ new Vue({
}).$start()
```

In its simplest form, however, edit `main.js`'s Vue initialization block to resemble:

```js
new Vue({
render: h => h('frame', [h(HelloWorld)]),
}).$start();
```
## Step 5: Edit paths

**Step 5: Edit paths**
Because the folder structure has changed, you need to edit the paths in your new app to point to your styles, fonts, and images.

Since the folder structure has changed, you need to edit the paths in your new app to point to your styles, fonts, and images.
**Example: Changing image references**

In your components, if you have images from your old app referenced like this:
In your old app, you are likely to have referenced images like this.

```HTML
<Image v-if="surprise" src="~/images/NativeScript-Vue.png"/>
```

Change the path:
To ensure that NativeScript loads the images, change the path reference to the following.

```HTML
<Image v-if="surprise" src="~/assets/images/NativeScript-Vue.png"/>
```

**Step 6: Fix Manual Routing Props (if necessary)**
## (If needed) Step 6: Fix manual routing props

If your app uses manual routing, please note that the syntax for passing props has changed.
If your app uses manual routing, the syntax for passing props has changed. Note that this change might not be required in all projects.

Old syntax:
Your old syntax is likely to look like this.

```js
```JavaScript
this.$navigateTo(NewPage, {
transition: {},
transitionIOS: {},
Expand All @@ -132,9 +149,9 @@ this.$navigateTo(NewPage, {
});
```

New syntax:
To preserve the manual routing behavior in your new app, change your syntax to the following:

```js
```JavaScript
this.$navigateTo(NewPage, {
transition: {},
transitionIOS: {},
Expand All @@ -147,14 +164,15 @@ this.$navigateTo(NewPage, {
});
```

## Step 7: Align `package.json`

**Step 7: Align `package.json`**
Copy the relevant values from your old app's root `package.json` file into the new app's root `package.json` file.

Copy the relevant values from your old app's root `package.json` file into the new app's root `package.json` file. This will most likely entail copying the `Dependencies:` block, but you might also need to realign the new app's app version and description at the top of `package.json`.
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`.

**Step 8: Clean and run**
## Step 8: Clean and run

At this point, it's a good idea to clean the new app's folders (if you have run it prior) and reinstall any dependencies.
Run the following command to clean the new app's folders and reinstall any dependencies.

```shell
$ cd <project-name>
Expand All @@ -165,9 +183,11 @@ $ # or
$ tns run ios --bundle
```

**Step 8 (Optional): Try HMR**
## (Optional) Step 8: Try HMR

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.

Just recently nativescript received support for HMR (Hot Module Replacement). The latest version of NativeScript-Vue supports it out of the box, however you will need to install the latest (and greatest) version of the NativeScript CLI.
Run the following command to get HMR support by installing the latest and greatest version of the NativeScript CLI.

```shell
$ npm install -g nativescript@next
Expand All @@ -176,4 +196,4 @@ $ rm -rf platforms
$ tns run android --hmr
$ # or
$ tns run ios --hmr
```
```