Porting Quasar v.17 to v1.2
Tips and Tricks to upgrading to the latest and greatest Quasar version!
At work, I just finished upgrading/porting a 17k+ lines of code Quasar SPA project from v.17 to the latest v1.2. This took just over a week (52 hours logged).
In this article, I will give you information to help you port you your own projects. Hopefully, they are not as big as mine was, so your time to completion will be faster.
First of all, Quasar v1.2 is spectacular. The code in version 1.X has been rewritten since v.17. It is faster and more suitable for development with many more components. And, there still is the added benefit of using the Quasar CLI, where a lot of the difficult grunt work of setting up and building cross-device applications is done for you.
First Steps
Before starting on your conversion journey, you should familiarize yourself with the Quasar Upgrade Guide. This contains valuable information and is a good reference should you get stuck.
The first thing to do, if you haven’t already done it, is to remove the old global Quasar CLI.
$ npm remove -g quasar-cliThe next thing to do is to install the global Quasar CLI (if you haven’t already).
$ npm install -g @quasar/cliThe Quasar team recommends using npm for your global package management and yarn for your local package management. There have been many issues reported with npm and local packages. We’ve noticed, once people start using yarn these issues go away.
If you’ve read the Quasar Upgrade Guide, it recommends doing your port in-place. From personal experience, I do not recommend this route. Instead, we will be creating a new Quasar project and porting all the code from your old project to your new project.
So to begin with, create your new project:
$ quasar create <project-name>Once the project has been created, go ahead and open it up with your favorite editor and start reviewing it. Have a quick look at the scaffolding. We’ll get into how scaffolding has changed and how to deal with those changes in just a moment.
Now add in all of your dependent packages that you had in your previous project. Make sure you use yarn, but if you feel you need to use npm, go ahead. If something goes wrong, you can’t say I didn’t warn you.
Scaffolding
One thing you may have noticed is that the plugins folder is missing and now there is a new boot folder. Aside from that, the folder structure has remained the same. The reason for the renaming of the plugins folder is to avoid confusion with Quasar’s own internal Vue plugins, which is also named plugins.
Boot Files — (from the Quasar docs)
Boot files fulfill one special purpose: they run code before the App’s Vue root component is instantiated while giving you access to certain variables, which is required if you need to initialize a library, interfere with Vue Router, inject Vue prototype or inject the root instance of the Vue app.
If you have any plugins from your previous project, convert them now to boot files. The operation of a boot file is the same as the old plugin files, with the only difference being, they can also be ran asynchronously.
You can create a boot file using the Quasar CLI:
$ quasar new boot <name>Create the equivalent boot files in the new project and port the code over from your old plugins. This will allow you to see how the boot file anatomy has changed, in case you need to take advantage of it.
quasar.conf.js
This file has relatively remained unchanged, except for a few things. The important one of note is that the “plugins: []” property has logically changed to “boot: []” to follow the folder structure change. This is where you put your boot file names, so Quasar can recognize them and add them to the build.
Porting
Before porting, here are a couple of things to look out for:
1. Look at the default layout that was created in the layouts folder. For this file, you may or may not want to drop your old layout file on top of it. If you notice too many changes, you may want to port this file by hand.
2. Look at the files in the routes folder. Again, this is one of those areas that may be better if you cherry-pick your old code and put it into the new code.
For all other files, it’s OK to drop them into their respective locations. I like to use an application called Meld, but if you are on Windows, feel free to use WinMerge. They are very similar.
eslint-plugin-quasar
The eslint-plugin-quasar (an eslint plugin) was created with some rules to help you do the porting. Let’s install the plugin and set up those rules.
$ yarn add -D eslint-plugin-quasar
The following changes need to be made to your .eslintrc.js configuration file.
Modification to the plugins section:
{
“plugins”: [
“quasar”
]
}Modification to the extends section:
{
“extends”: [
“plugin:quasar/legacy”
]
}Modification to the rules section:
{
“rules”: [
‘quasar/no-legacy-components’: ‘warn’,
‘quasar/no-legacy-css’: ‘warn’,
‘quasar/no-legacy-directives’: ‘warn’,
‘quasar/no-legacy-properties’: ‘warn’
]
}Be sure to save the changes. (Note: Medium changes the quotes, so if you copy and paste, be sure to change the quotes properly to avoid errors)
Quasar adds a script command in your package.json file that helps you with the linting, so you can run it now.
$ yarn lint
The Grunt Work
After running the linter, you will see a lot of warning messages. Some will be about components that were renamed, some that don’t exist anymore, etc. The eslint-plugin-quasar will make recommendations. Most of these you can carry out by renaming the component by hand. You should look at each warning and the corresponding component in the Quasar docs and verify this is what you want to do.
Here is an example:
/home/me/my-project/src/pages/About.vue
3:5 error ‘q-window-resize-observable’ has been removed
12:17 error ‘q-resize-observable’ has been replaced with ‘q-resize-observer’
32:17 error ‘q-progress’ has been replaced with ‘q-linear-progress’
261:19 error ‘q-popover’ has been replaced with ‘q-menu’I ran into a situation, where I wasn’t quite sure what I wanted to do. So, I blocked out the code with a comment and tagged it with TODO: port, so I could easily search for it and revisit it at a later time.
Keep running the linter and making the appropriate modifications until there are no more warnings or errors.
Quasar v1.2
Once you have converted all of the legacy code, it’s time to turn on some eslint rules for Quasar v1+.
Once again, open the .eslintrc.js file.
Modification to the `rules` section:
{
“rules”: [
‘quasar/check-valid-props’: ‘warn’,
‘quasar/no-invalid-qfield-usage’: ‘warn’
]
}Again, run the linter:
$ yarn lintYep, a whole new set of warnings to deal with. Most of these will be properties that don’t exist anymore.
However, the second rule that was recently added is for QInput and QSelect being wrapped by QField (and this rule is recursive). The reason for this is that QInput and QSelect use QField as a mix-in and therefore no longer require QField as a parent component. Each of these warnings will need to be looked at closely. Most of the properties that you use for QField can be moved to QInput and QSelect.
Build Time
Once you have dealt with all the warnings and errors, you can now build your project.
$ quasar buildIf there are any build errors, deal with them now. Then, try building again. Repeat until the build completes. I didn’t have any issues in this area, but your mileage may vary, so I thought I should include it.
Other Gotchas
Once you have your project running, there may still be a few issues that the linter can’t help you with.
For instance, on QSelect, you may need to add the following properties to get the same functionality that you had previously:
map-options emit-valueAnother issue you may have is icon usage for QInput has changed. You now use the slots prepend and append to add icons and functionality. This means, if you were using the old QInput with type="password", you used to be able to toggle the eye icon to make the password visible. You can still get that functionality by following the appropriate example that uses the append slot to accomplish the same thing.
Conclusion
The above information is by no means exhaustive. If you need help, here are some things to remember (as per the Quasar Upgrade Guide):
1. Read the documentation before asking questions on our Discord server or forums.
2. Prepare a CodePen so staff can help you.
3. Dig into the Quasar source code (it’ll help you understand the framework as well as teach you best practices for programming with Vue).
4. Don’t use framework components as mixins unless absolutely necessary (wrap them if you need).
5. Don’t target inner component stuff with CSS selectors unless absolutely necessary.
6. We recommend yarn whenever possible because of its speed and efficient use. However, when using globals, we still recommend using NPM, especially if you use nvm (Node Version Manager).
7. Use git for repository management and make regular commits, it is like taking notes on the process and lets you revert to a previous state in case you get stuck.
8. Use Quasar boot files for any pre-mounting app routines.
9. Be very cautious when using other libraries — Quasar can’t ensure they will be fully compatible
10. Finally, become a [backer/sponsor](https://donate.quasar.dev/) and get access to the special Discord support chat room for priority support.
I spent several days on the conversion of my company’s app. Hopefully, your project isn’t as large as mine was. Whether your project is large or small, I hope these tips and tricks for upgrading will help you.
If you have more tips and tricks or experiences from your upgrade to Quasar version 1.X, let us know in the comments below. We’d love to hear about them.
Interested in Quasar? Here are some more tips and information:
More info: https://quasar.dev
GitHub: https://github.com/quasarframework/quasar
Getting Started: https://quasar.dev/start
Chat Server: https://chat.quasar.dev/
Forum: https://forum.quasar.dev/
Twitter: https://twitter.com/quasarframework
Donate: https://donate.quasar.dev
