QuasarScaffold

HOW TO SETUP A QUASAR-VUE CAPACITOR ANDROID PROJECT

Feb 2025

Introduction

There are a number of steps you need to perform to properly scaffold and configure your Quasar-Capacitor project for creating Android apps using Vue.js.

This guide assumes, You Are:

About This Guide

I have attempted to show Information that has been directly gleaned from the internet and then "cut-n-pasted" incorporated into this guide between sets of lines and "Per research".

This guide is intended for someone who is starting out on their journey (like me). Experienced developers will likely find most of the information, well, superfluous.

QUASAR IS AN AWESOME FRAMEWORK!

Quasar and Capacitor are truly wonderful, but I've found it a bit difficult to get them to behave, so hence this guide. At the end of all this you should behold the following desktop configuration!

Guide Structure

This guide is divided into seven major parts:

  1. Prerequisites for a Quasar / Vue project
    Setting up your development environment

  2. Project Planning link
    What you should consider before starting

  3. Project Setup & Scaffold Steps link
    Detailed configuration steps with thorough explanations
    Launch as SPA web app link

  4. Launching Your Android Application in Dev link
    Getting your development environment running

  5. Installing Capacitor Plugins link
    Installing the geolocation plugin

  6. Creating a Hello World page link

  7. Creating a page that uses the plugin link
    A very basic geolocation plugin page

Oh, and some credits are at the end...

PART 1: Prerequisites for a Quasar Project

Prerequisites Checks

There are 3 steps:
-have Node, nvm and npm installed
-verify Android Studio install
-set android environment variables

Part 1 - Step 1. Check Node.js, npm, and nvm versions:

First, let's verify the development environment

==Important DO NOT IGNORE: ==
As of Feb 2025, default Quasar & Capacitor (v6) required Node v18.
This will probably change, hence why having node version manager (nvm) is essential.

Terminal commands:

node --version  # Should be >=18.0.0
npm --version   # Should be >=6.13.4
nvm --version   # Check if nvm is installed

If nvm is not installed:

# For macOS using brew
brew install nvm

After installation, add these lines to your ~/.zshrc or ~/.bash_profile:

export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"

Reload your terminal configuration:

source ~/.zshrc  # or source ~/.bash_profile

Verify nvm installation:

nvm --version

If Node.js version is not 18:

# Install Node.js 18
nvm install 18

# Use Node.js 18
nvm use 18

# Verify the version
node --version  # Should show v18.x.x (for Capacitor v6)

To use a specific version directly, use the terminal command:

nvm use <version>

Part 1 - Step 2. Verify Android Studio installation:

Open Android Studio and verify the following:

Go to Tools > SDK Manager
Under "SDK Platforms" ensure you have:

Under "SDK Tools" verify you have:

Part 1 - Step 3. Set up android environment variables

Add to ~/.zshrc or ~/.bash_profile:

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools

PART 2: Project Planning

Before you begin scaffolding Quasar, think carefully about the following names:

PART 3: Quasar Project Setup Steps

This section provides detailed instructions for setting up your Quasar project with Capacitor for Android development. Follow these steps in order:

Part 3 Overview

A - Install Quasar CLI

Installation and configuration of the Quasar Command Line Interface link

B. Scaffold Quasar / Vue

Creating the base Quasar & Vue project structure link

C. Add Capacitor to Quasar

Integrating Capacitor framework with your Quasar project link

D. Add Capacitor/android to project

Setting up the Android platform configuration link

E. Create /dist directory

Preparing the distribution directory for your application link

F. Sync the project

Synchronizing Quasar and Capacitor configurations link

Each step will be covered in detail in its own section. Follow the steps sequentially to ensure proper setup of your development environment.

Part 3A - Install Quasar CLI

In your project directory, first check the install of the Quasar CLI:

quasar --version

The above command will return the CLI version if installed, something like:

@quasar/cli 2.4.1

Run the Quasar CLI install command if not already installed:

npm i -g @quasar/cli

Note also that you can run the following command:

quasar info

This will show a complete report of your Quasar project (if the Quasar framework project has been scaffolded).

Part 3B - Scaffold Quasar / Vue

To initialize and scaffold the Quasar and Vue.js project:
-Create Quasar project
-Install and verify
-Test initial build

P3B Step 1: Create new Quasar project

Run this command:

npm init quasar@latest

Or run this command:

npm create quasar

The above command seems to take a long time to run...you just have to wait.

As of Feb 2025, I can't determine definitively which of the above commands is better. Either command will then prompt the same set of selection options: see note below.

P3B Step 2: Install & Verify

Change directories into the project root:

cd <your project folder>

Then run:

npm install

Verify the terminal output resulting from the install

Also run in your project root:

quasar info

P3B Step 3: Test initial build - SPA

You will now want to make sure Quasar (and Vue) are working as a plain SPA web app.

npm run dev    # Should open development server

You should launch a spa web page similar to below...be sure to enable dev tools and look for any problems.

Part 3B Summary of scaffolding Quasar

So, in summary to Part 3B, to initially scaffold the Quasar project, run these 3 commands:

npm i -g @quasar/cli
npm init quasar@latest
npm install

The above 3 commands will:

  1. Allow you to run Quasar CLI commands
  2. Create an initially scaffolded Quasar-Vue project

Part 3C - Add Capacitor to Quasar

There are a couple steps to install capacitor to a Quasar project.
-Add capacitor structures to project using Quasar command
-Add capacitor config to project root using npm commands
-Verify installation

P3C - Step 1: Add Capacitor to Quasar

Run the following Quasar command in your project root folder:

quasar mode add capacitor

The above Quasar command will prompt for:

What is the Capacitor app id? (org.capacitor.quasar.app)

The app id is reverse domain name notation (ref project planning notes)

The folder /src-capcitor will then be created in your project and the app id will go into the capacitor.config.json file.

The newly created src-capacitor structure will also hold the android structures in subsequent steps.

P3C Step 1 Notes

I recommend you review each of the notes below after running quasar mode add capacitor.

P3C - Step 2: Add Capacitor config In Project Root

You MUST manually install the @capacitor/cli and the @capacitor/core modules in the project root! ***Make sure root install matches the version in /src-capacitor

Change directories to your project root.

In your project root directory first run:

npm install @capacitor/cli@6

Then run:

npm install @capacitor/core@6

P3C - Step 3: Verify installation

Check the capacitor CLI version in project root:

npx cap --version

Change directories into the /src-capacitor folder:

cd src-capacitor

Then run to check capacitor in /src-capacitor:

npm list @capacitor/core

The capacitor core version, which should match package.json.

Part 3D - Add Capacitor/android to project

Now we can start configuring things to actually create an Android app. These steps will allow Android Studio to launch.

NOTE: The @capacitor/android is native and only needs installed in the /src-capacitor folder.

The install of capacitor android is a two step process. As an analogy: think about this as repairing your car:

  1. First go to the parts store and get the car parts (install android).
  2. And then you actually bolt the parts to the car (create android).

P3D - Step 1: Install Android Platform Package

The step is like going to the automotive store to get your car parts.

Be sure and change directories into the /src-capacitor directory-folder:

cd src-capacitor

then

npm install @capacitor/android@6.0.0

The package.json file in /src-capacitor folder should then look something like this:

{
  "name": "gmap9",
  "version": "0.0.1",
  "description": "A Quasar Google Map test",
  "author": "abcdefg2 <abcdefg2@icloud.com>",
  "private": true,
  "dependencies": {
    "@capacitor/android": "^6.0.0",   <- android added
    "@capacitor/app": "^6.0.0",
    "@capacitor/cli": "^6.0.0",
    "@capacitor/core": "^6.0.0"
  }
}
P3D Step 1 Notes

P3D - Step 2: Create the Android Project Structure

This step is like actually bolting the car parts to your car.

Run the following in the /src-capacitor folder:

npx cap add android

The above command npx cap add android will actually create the /android folder-directory within the /src-capacitor folder.

When you run npx cap add android, Capacitor is looking at the capacitor.config.json file.

your-project/
├── .quasar
├── node_modules
├── src/
├── src-capacitor/
│   ├── node_modules       
│   ├── www
│   ├── android/               <- location of android
│   ├── capacitor.config.json
│   ├── package-lock.json
│   └── package.json
├── index.html
├── package-lock.json
├── package.json
└── quasar.config.js
P3D Step 2 Android Notes

android/
├── app/
│ ├── src/
│ │ ├── main/
│ │ │ ├── java/com/example/app/
│ │ │ │ ├── MainActivity.kt
│ │ │ ├── AndroidManifest.xml <- update capacitor plugins
│ │ │ ├── res/
│ │ │ │ ├── drawable/
│ │ │ │ ├── layout/
│ │ │ │ ├── mipmap/
│ │ │ │ ├── values/
├── build.gradle
├── settings.gradle

When you install a capacitor plugin you will probably need to manually update permission within the `AndroidManifest.xml` file.
Do not upgrade Gradle

DO NOT upgrade Gradle when prompted
DO NOT upgrade other Android dependencies automatically
Use "File > Invalidate caches and restart" if encountering IDE errors

P3D Step 3 : Verify android installation

Verify installation in the /src-capacitor folder:

npm list @capacitor/android
ls android/  # Should show complete Android project structure

Part 3E - Create Dist/Spa Directory

Additionally, there is yet another step:

To build your Quasar app for production generate the /dist directory with terminal command in the root directory:

quasar build

This will create a new /dist directory:

your-project/
├── .quasar
├── dist/spa             <- new dist directory
├── node_modules
├── src/
├── src-capacitor/
├── index.html
├── package-lock.json
├── package.json
└── quasar.config.js

Then Very Important!
Update the capacitor.config.json file!!!
In your /src-capacitor folder, it must to point to the correct web directory:
"webDir": "../dist/spa"

The capacitor.config.json file should look something like this:
{
"appId": "com.yoururl.gmap",
"appName": "quasargooglemap",
"webDir": "../dist/spa"
}

Part 3F - Sync Your Project

Now sync your project with Capacitor to ensure everything is up-to-date run command in the src-capacitor directory:

cd src-capacitor
npx cap sync

P3F Note 1: Inspect your package.json files

At this point I highly recommend you inspect both package.json file, in project root and in /src-capacitor to insure the plugin is in fact installed.

Conclusion to Part 3: Installing Quasar and Capacitor

And finally, always after installing plugins or making other updates, be sure and remember run in your /src-capacitor folder:

npx cap sync

For notes about the npx cap sync command, reference [[#Part 3F - Sync Your Project]] again for notes on "What npx cap sync does".

Wasn't that a journey! And now, finally you might actually be able to do some actual development.

Part 4: Launch Android App

P4 Step 1 - Launching Your Application in Dev

To finally launch the app in development, run:

quasar dev -m capacitor -T android

The above command translates/parses roughly as follows:

When you run the above command, a session of Android Studio should automagically launch.

You should be able to interact with your app in Android Studio, and on the test Android phone at the same time.

P4 Note A - Important Android phone Setup Notes


When setting up your development environment:

P4 Note B - Chrome Inspect Devices Tool

Also: HIGHLY RECOMMEND: use the chrome inspect devices tool!

Open a browser tab, put in:

chrome://inspect/#devices

When you launch the app you will be able to select your test Android phone and interact with it and show console log and review error messages from the WebView! This feature is so awesome!

But, just a note: the inspect tool can be a bit balky...and it sometimes lags up to a few minutes before it brings up the device list.

===The Chrome Inspect tool is crucial. ===

Part 5 - Install Capacitor Plugins

And finally, now we can start adding Capacitor plugins that can work on a phone!

There are so many cool features that Capacitor has to offer. Here's a link: https://capacitorjs.com/docs/plugins

Each time you add/install a capacitor plugin:

P5 - Step 1: Install Proper Plugin Versions

Example: @capacitor/geolocation

Let's use the geolocation plugin as an example for how to go about installing a plugin into your scaffolded Quasar project (which again in Feb 2025: Quasar defaulted in cli and core at v6).

Capacitor's plugin bypasses this Google Geolocation API by using direct device capabilities.

P5 Step 1 Note 1: Versioning Challenges: read:

P5 Step 2: Add Permissions in AndroidManifest.xml file

Yes folks, yet more manual steps! Who said this would be easy?

For Android, you sometimes, but not always, have to manually update the AndroidManifest.xml file.
Do your own research!

Example:
Per Capacitor Documentation at following link: https://capacitorjs.com/docs/apis/geolocation

Find your AndroidManifest.xml file, which should be way down under:
/src-capacitor
/android
/app
/src
/main

For the geolocation plugin, per capacitor, put the following into the AndroidManifest.xml file:

<!-- Geolocation Plugin -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-feature android:name="android.hardware.location.gps" />

Part 6 - Create a Hello World Page

First let's just get a hello world MapPageGeoLocate.vue wired in,
...we will replace the hello world with code that uses the geolocation plugin in the next step.

Lets create an initial Hello World page under /src/pages folder
...just to make sure the basic page, router and button work first.

P6 step A - Create a CapacitorGeoLocate.vue - Hello World

Below is code for creating the CapacitorGeoLocate.vue in the /src/pages folder...again, we are just getting things wired up.

<script setup>
   // No setup needed for this simple example
</script>
  
<template>
  <div>
     <h1>Hello, World!</h1>
  </div>
</template>
  
<style scoped>
   /* Add styles here if needed */
</style>

P6 step B - Create route in route.js

Add the following to the routes.js under the /src/router folder.

{
  path: '/geolocation',
  name: 'geolocation',
  component: () => import('pages/CapacitorGeoLocate.vue'),
},

P6 step C - Add button to IndexPage.vue

Add following to IndexPage.vue under /src/pages folder

<q-btn
    color="primary"
    label="Go to just Geolocate Page"
    @click="$router.push('/geolocation')"
/>

P6 step D - Test CapacitorGeoLocate.vue page, button & route

Test as both a SPA web page and in Android Studio

SPA - In the root directory run following terminal command.

npm run dev

You should see a web page with the button. The button should take you to the Hello World page.
!spaPage-Button.png

Android Studio - In the root directory run the following terminal command.

quasar dev -m capacitor -T android

You should be able to launch as an Android app in Android Studio. The button should take you to the Hello World page.
!AllScreensHelloWorld.png

Part 7 - Update the Geolocation Page

Now that we have:

The @capacitor/geolocation plugin is fairly basic so it easier to implement than lets say the google-maps plugin (subject of another blog...tbd).

Full disclosure: It's just a hack page created by Claude...don't hate me.

After updating your code (and saving), test as both a SPA web page and in Android Studio

SPA - In the root directory run following terminal command.

npm run dev

You should see a web page with the button,
...clicking the button should take you to the CapacitorGeoLocate.vue page:

Android Studio - In the root directory run the following terminal command.

quasar dev -m capacitor -T android

You should be able to launch as an Android app in Android Studio.
...on Android you may probably see a permissions pop-up screen:

Credits

Let me thanks Vueschool.io (link: https://vueschool.io) for their excellent video tutorials. They have a great product that really helped getting ramped up on Vue.js.

Let me thank Luke Diebold in particular for his excellent video tutorials, as they gave a huge head start. Luke is just an outstanding educator and Quasar evangelist.
https://www.youtube.com/@LukeDiebold

Also a shout out goes to all my AI friends, especially Perplexity (which offer links to it's sources!) and Claude which can produce fairly decent code.

*So, apologies to all the kind people of the internet who selflessly contribute to the technical zeitgeist. * But without these AI's ability to distill their knowledge into specific answers, this project would have been absolutely impossible. Although the AI's are often frustratingly dead wrong, they also often nail the answers, and even the wrong answers sometimes offer important clues. In fact, I fully expect this blog too will be consumed into the AI blackhole.

Oh, but I found Copilot in VS Code kinda useless...just say'n. This is as of Feb 2025, so I'm sure things will improve.

And let's give a thanks to Obsidian!
https://obsidian.md/
I recently discovered this app, and it sure beats any of the other apps I've used over the years for taking notes.

Be sure and install the Obsidian webclipper extension to your browser! Wow...it is sooooo useful. When you find a great web resource, just clip into Obsidian and it's there for you to research and link (tags) into all your other notes. Also, in fact, this blog was produced in Obsidian. Obsidian is so useful, and it's free! Unbelievable.