Convert project to Quasar CLI with Vite

Quasar CLI with Vite - @quasar/app-vite

This page will guide you on how to convert a Quasar CLI with Webpack (@quasar/app-webpack - formerly known as @quasar/app) project into a Quasar CLI with Vite one (@quasar/app-vite).

Step 1: Create a Quasar CLI with Vite project folder:

$ yarn create quasar
# or:
$ npm init quasar
# or:
$ pnpm create quasar # experimental support

# pick "App with Quasar CLI", "Quasar v2", "Quasar App CLI with Vite"

There are significant changes to the root files so it’s easier to generate a new project folder rather than explaining each of the many changes.

Step 2: Copy folders from original folder

From your original project folder, copy these as they are:

/src (with small caveat; see next steps)
/src-cordova
/src-capacitor
/src-electron
/src-pwa (with small caveat; see next steps)
/src-ssr (with small caveat; see next steps)
~~/src-bex~~ Nope. Don’t!

Move /src/index.template.html to /index.html. And make the following change:

<!-- DO NOT touch the following DIV -->
<div id="q-app"></div>

// replace with:

<!-- quasar:entry-point -->

Also, edit /src/router/index.js:

// Change:
history: createHistory(process.env.MODE === 'ssr' ? void 0 : process.env.VUE_ROUTER_BASE)
// Into:
history: createHistory(process.env.VUE_ROUTER_BASE)

Step 3: Explicitly specify extensions on all your import statements

Make sure that all your Vue component files (SFC) are imported with their .vue extension explicitly specified. Omitting the file extension works with Webpack (due to Quasar CLI configured list of extensions for it to try), but not with Vite too.

// BAD! Will not work:
import MyComponent from './MyComponent'

// GOOD:
import MyComponent from './MyComponent.vue'

Step 4: Check the new quasar.config.js

There are property changes in build, devServer, and all Quasar Modes (pwa, ssr, etc). The props are detailed in quasar.config.js page. You will have to manually port your configuration to the Quasar CLI with Vite architecture.

Step 5: Browser compatibility

A Quasar CLI with Webpack project relies on /package.json > browserslist to specify which browsers you are targetting. That property no longer has any meaning. Projects managed by Quasar CLI with Vite work completely different and you might want to check the Browser Compatibility page.

Delete /src-ssr/directives folder (if you have it) – it no longer serves any purpose; check Vue SSR Directives page
Port the /src-ssr/production-export.js file to /src-ssr/server.js; Make sure to read about the SSR Webserver first

More info: Configuring SSR

VERY important: BEFORE porting your files over, run command quasar mode add pwa. Otherwise all the needed packages will not be added, and your build will fail.
The default name of the outputted service worker file has changed from service-worker.js to sw.js. This can break your update process the first time the new app is loaded. So, if your app is in production, to ensure smooth upgrades from the previous Webpack builds, make sure the name matches the name of your previous service worker file. You can set it through quasar.config.js > pwa > swFilename.
Quasar CLI with Webpack relies on quasar.config.js > manifest to specify the manifest, but you will need to use /src-pwa/manifest.json to declare it for Quasar CLI with Vite. After declaring the manifest in /src-pwa/manifest.json, delete quasar.config.js > manifest section.
There were also some props in quasar.config.js that are no longer available. Most notably: metaVariables, metaVariablesFn. Simply edit /index.html and add those tags directly there.

<!-- index.html -->
<head>
  <% if (ctx.mode.pwa) { %>
    <!-- Define your custom PWA-related meta/link tags here. -->
  <% } %>
</head>

More info: PWA - Preparation

The BEX mode differs quite a lot. The PWA mode in a Quasar CLI with Vite project supports PWA manifest v3 and multiple content scripts. You will have to manually port over your BEX files to the new architecture, which should be fairly easy though.

It’s best to $ quasar mode add bex, pick your preferred PWA manifest version (v2 or v3) and port your BEX.

More info: Preparation and folder structure and Configuring BEX.

Step 9: And we’re done

$ quasar dev
$ quasar build

Caught a mistake?Edit this page in browser

1. Introduction

1.1. Step 1: Create a Quasar CLI with Vite project folder:

1.2. Step 2: Copy folders from original folder

1.3. Step 3: Explicitly specify extensions on all your import statements

1.4. Step 4: Check the new quasar.config.js

1.5. Step 5: Browser compatibility

1.9. Step 9: And we’re done

Step 1: Create a Quasar CLI with Vite project folder:

Step 2: Copy folders from original folder

Step 3: Explicitly specify extensions on all your import statements

Step 4: Check the new quasar.config.js

Step 5: Browser compatibility

Step 6: SSR related

Step 7: PWA related

Step 8: BEX related

Step 9: And we’re done