Why donate
API Explorer
Upgrade guide
NEW!
The quasar.config file
Convert project to CLI with Vite
Browser Compatibility
Supporting TypeScript
Directory Structure
Commands List
CSS Preprocessors
Routing
Lazy Loading - Code Splitting
Handling Assets
Boot Files
Prefetch Feature
API Proxying
Handling Vite
Handling process.env
State Management with Pinia
State Management with Vuex
Linter
Testing & Auditing
Developing Mobile Apps
Ajax Requests
Opening Dev Server To Public
Quasar CLI with Vite - @quasar/app-vite
Convert project to Quasar CLI with 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
# then 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>
+ <!-- quasar:entry-point -->

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

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

// new way
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 file

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

TypeScript Aliases

If you are using TypeScript and defined custom path aliases in tsconfig.json > compilerOptions > paths, they will no longer be processed automatically. See Folder aliases | Handling Vite for available ways to handle this.

Step 5: Browser compatibility

A Quasar CLI with Webpack project relies on /package.json > browserslist to specify which browsers you are targeting. 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 file > pwa > swFilename.
  • Quasar CLI with Webpack relies on quasar.config file > 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 file > manifest section.
  • There were also some props in the quasar.config file 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