Quasar makes use of some awesome development tools under its hood, like Webpack. One of the great things about Quasar is its handling of most of the complex configuration needed by the underlying tools for you. As a result, you don’t even need to know Webpack or any of the other development tools in order to use Quasar.
So what can you configure through the /quasar.config
file?
- Quasar components, directives and plugins that you’ll be using in your website/app
- Default Quasar Language Pack
- Icon libraries that you wish to use
- Default Quasar Icon Set for Quasar components
- Development server port, HTTPS mode, hostname and so on
- CSS animations that you wish to use
- Boot Files list (that determines order of execution too) – which are files in
/src/boot
that tell how your app is initialized before mounting the root Vue component - Global CSS/Sass/… files to be included in the bundle
- PWA manifest and Workbox options
- Electron Packager and/or Electron Builder
- Extend Webpack config
TIP
You’ll notice that changing any of these settings does not require you to manually reload the dev server. Quasar detects and reloads the necessary processes. You won’t lose your development flow, because you can just sit back while Quasar CLI quickly reloads the changed code, even keeping the current state. This saves tons of your time!
WARNING
The /quasar.config
file is run by the Quasar CLI build system, so this code runs under Node directly, not in the context of your app. This means you can require modules like ‘fs’, ‘path’, ‘webpack’, and so on. Make sure the ES features that you want to use in this file are supported by your Node version (which should be >= 14).
Structure
The basics
You’ll notice that the /quasar.config
file exports a function that takes a ctx
(context) parameter and returns an Object. This allows you to dynamically change your website/app config based on this context:
module.exports = function (ctx) { // can be async too
console.log(ctx)
// Example output on console:
{
dev: true,
prod: false,
mode: { spa: true },
modeName: 'spa',
target: {},
targetName: undefined,
arch: {},
archName: undefined,
debug: undefined
}
// context gets generated based on the parameters
// with which you run "quasar dev" or "quasar build"
}
What this means is that, as an example, you can load a font when building for a certain mode (like PWA), and pick another one for the others:
module.exports = function (ctx) {
extras: [
ctx.mode.pwa // we're adding only if working on a PWA
? 'roboto-font'
: null
]
}
Or you can use a global CSS file for SPA mode and another one for Cordova mode while avoiding loading any such file for the other modes.
module.exports = function (ctx) {
css: [
ctx.mode.spa ? 'app-spa.sass' : null, // looks for /src/css/app-spa.sass
ctx.mode.cordova ? 'app-cordova.sass' : null // looks for /src/css/app-cordova.sass
]
}
Or you can configure the dev server to run on port 8000 for SPA mode, on port 9000 for PWA mode or on port 9090 for the other modes:
module.exports = function (ctx) {
devServer: {
port: ctx.mode.spa
? 8000
: (ctx.mode.pwa ? 9000 : 9090)
}
}
You can also do async work before returning the quasar configuration:
module.exports = async function (ctx) {
const data = await someAsyncFunction()
return {
// ... use "data"
}
}
// or:
module.exports = function (ctx) {
return new Promise(resolve => {
// some async work then:
// resolve() with the quasar config
resolve({
//
})
})
}
The possibilities are endless.
IDE autocompletion
You can wrap the returned function with configure()
helper to get a better IDE autocomplete experience (through Typescript):
const { configure } = require('quasar/wrappers')
module.exports = configure(function (ctx) {
/* configuration options */
})
Options to Configure
Let’s take each option one by one:
Property | Type | Description |
---|---|---|
css | Array | Global CSS/Sass/… files from /src/css/ , except for theme files, which are included by default. |
preFetch | Boolean | Enable PreFetch Feature. |
extras | Array | What to import from @quasar/extras package. Example: [‘material-icons’, ‘roboto-font’, ‘ionicons-v4’] |
vendor | Object | Add/remove files/3rd party libraries to/from vendor chunk: { add: […], remove: […] }. |
supportTS | Boolean/Object | Add support for TypeScript. More info |
htmlVariables | Object | Add variables that you can use in /index.html or /src/index.template.html. |
framework | Object/String | What Quasar components/directives/plugins to import, what Quasar language pack to use, what Quasar icon set to use for Quasar components. |
animations | Object/String | What CSS animations to import. Example: [‘bounceInLeft’, ‘bounceOutRight’] |
devServer | Object | Webpack devServer options. Some properties are overwritten based on the Quasar mode you’re using in order to ensure a correct config. Note: if you’re proxying the development server (i.e. using a cloud IDE), set the public setting to your public application URL. |
build | Object | Build configuration options. |
sourceFiles | Object | Change the default name of parts of your app. |
cordova | Object | Cordova specific config. |
capacitor | Object | Quasar CLI Capacitor specific config. |
pwa | Object | PWA specific config. |
ssr | Object | SSR specific config. |
electron | Object | Electron specific config. |
Property: css
Global CSS/Sass/… files from /src/css/
, except for theme files, which are included by default.
return {
css: [
'app.sass', // referring to /src/css/app.sass
'~some-library/style.css' // referring to node_modules/some-library/style.css
]
}
Property: vendor
By default, everything that comes from node_modules
will be injected into the vendor chunk for performance & caching reasons. However, should you wish to add or remove something from this special chunk, you can do so:
return {
vendor: {
/* optional;
disables vendor chunk: */ disable: true,
add: [ 'src/plugins/my-special-plugin' ],
remove: ['axios', 'vue$']
}
}
Property: framework
Tells the CLI what Quasar components/directives/plugins to import, what Quasar I18n language pack to use, what icon set to use for Quasar components and more.
Filling “components” and “directives” is required only if “all” is set to false
.
return {
// a list with all options (all are optional)
framework: {
// is using "auto" import strategy, you can also configure:
autoImportComponentCase: 'pascal', // or 'kebab' (default) or 'combined'
// For special cases outside of where auto-import can have an impact
// (example: vue components written in .js files instead of .vue),
// you can manually specify Quasar components/directives to be available everywhere:
//
// components: [],
// directives: [],
// Quasar plugins
plugins: ['Notify' /* ... */],
// Quasar config
// You'll see this mentioned for components/directives/plugins which use it
config: { /* ... */ },
iconSet: 'fontawesome-v6', // requires icon library to be specified in "extras" section too,
lang: 'de', // Tell Quasar which language pack to use for its own components
cssAddon: true // Adds the flex responsive++ CSS classes (noticeable bump in footprint)
}
}
More on cssAddon here.
Property: devServer
Webpack devServer options. Take a look at the full list of options. Some are overwritten by Quasar CLI based on “quasar dev” parameters and Quasar mode in order to ensure that everything is setup correctly. Note: if you’re proxying the development server (i.e. using a cloud IDE or local tunnel), set the webSocketURL
setting in the client
section to your public application URL to allow features like Live Reload and Hot Module Replacement to work as described here.
Most used properties are:
Property | Type | Description |
---|---|---|
port | Number | Port of dev server |
host | String | Local IP/Host to use for dev server |
open | Boolean/Object | Unless it’s set to false , Quasar will open up a browser pointing to dev server address automatically. Applies to SPA, PWA and SSR modes. Uses open package params. For more details, please see below. |
proxy | Object/Array | Proxying some URLs can be useful when you have a separate API backend development server and you want to send API requests on the same domain. |
devMiddleware | Object | Configuration supplied to webpack-dev-middleware v4 |
server | Object | Here you can configure HTTPS instead of HTTP (see below) |
onBeforeSetupMiddleware | Function | Configure the dev middlewares before webpack-dev-server applies its own config. |
onAfterSetupMiddleware | Function | Configure the dev middlewares after webpack-dev-server applies its own config. |
Using open
prop to open with a specific browser and not with the default browser of your OS (check supported values). The options
param described in previous link is what you should configure quasar.config file > devSever > open with. Some examples:
// (syntax below requires @quasar/app-webpack v3.3+)
// opens Google Chrome
devServer: {
open: {
app: { name: 'google chrome' }
}
}
// opens Firefox
devServer: {
open: {
app: { name: 'firefox' }
}
}
// opens Google Chrome and automatically deals with cross-platform issues:
const open = require('open')
devServer: {
open: {
app: { name: open.apps.chrome }
}
}
When you set devServer > server > type: 'https'
in your the /quasar.config
file, Quasar will auto-generate a SSL certificate for you. However, if you want to create one yourself for your localhost, then check out this blog post by Filippo. Then your quasar.config file > devServer > server
should look like this:
devServer: {
server: {
type: 'https', // NECESSARY (alternative is type 'http')
options: {
// Use ABSOLUTE paths or path.join(__dirname, 'root/relative/path')
key: "/path/to/server.key",
pfx: "/path/to/server.pfx",
cert: "/path/to/server.crt",
ca: "/path/to/ca.pem",
passphrase: 'webpack-dev-server' // do you need it?
}
}
}
You can also configure automatically opening remote Vue Devtools:
devServer: {
vueDevtools: true
}
Docker and WSL Issues with HMR
If you are using a Docker Container, you may find HMR stops working. HMR relies on the operating system to give notifications about changed files which may not work for your Docker Container.
A stop-gap solution can be achieved by using the polling mode to check for filesystem changes. This can be enabled with:
build: {
// ...
extendWebpack(cfg) {
cfg.watchOptions = {
aggregateTimeout: 200,
poll: 1000,
};
},
// ...
Property: build
Property | Type | Description |
---|---|---|
transpile | Boolean | Enables or disables Babel transpiling. |
transpileDependencies | Array of Regex | Does not applies if “transpile” is set to “false”. Add dependencies for transpiling with Babel (from node_modules, which are by default not transpiled). Example: [ /my-dependency/, ...] |
showProgress | Boolean | Show a progress bar while compiling. |
transformAssetUrls | Object | Add support for also referencing assets for custom tags props. Example: { 'my-img-comp': 'src', 'my-avatar': [ 'src', 'placeholder-src' ]} |
extendWebpack(cfg) | Function | Extend Webpack config generated by Quasar CLI. Equivalent to chainWebpack(), but you have direct access to the Webpack config object. |
chainWebpack(chain) | Function | Extend Webpack config generated by Quasar CLI. Equivalent to extendWebpack(), but using webpack-chain instead. |
beforeDev({ quasarConf }) | Function | Prepare external services before $ quasar dev command runs, like starting some backend or any other service that the app relies on. Can use async/await or directly return a Promise. |
afterDev({ quasarConf }) | Function | Run hook after Quasar dev server is started ($ quasar dev ). At this point, the dev server has been started and is available should you wish to do something with it. Can use async/await or directly return a Promise. |
beforeBuild({ quasarConf }) | Function | Run hook before Quasar builds app for production ($ quasar build ). At this point, the distributables folder hasn’t been created yet. Can use async/await or directly return a Promise. |
afterBuild({ quasarConf }) | Function | Run hook after Quasar built app for production ($ quasar build ). At this point, the distributables folder has been created and is available should you wish to do something with it. Can use async/await or directly return a Promise. |
onPublish(opts) | Function | Run hook if publishing was requested ($ quasar build -P ), after Quasar built app for production and the afterBuild hook (if specified) was executed. Can use async/await or directly return a Promise. opts is Object of form {arg, distDir} , where “arg” is the argument supplied (if any) to -P parameter. |
publicPath | String | Public path of your app. By default, it uses the root. Use it when your public path is something else, like “<protocol>://<domain>/some/nested/folder” – in this case, it means the distributables are in “some/nested/folder” on your webserver. |
appBase | String | Force app base tag with your custom value; configure only if you really know what you are doing, otherwise you can easily break your app. Highly recommended is to leave this computed by @quasar/app-webpack. |
vueRouterBase | String | Force vue router base with your custom value; configure only if you really know what you are doing, otherwise you can easily break your app. Highly recommended is to leave this computed by @quasar/app-webpack. |
vueRouterMode | String | Sets Vue Router mode: ‘hash’ or ‘history’. Pick wisely. History mode requires configuration on your deployment web server too. |
htmlFilename | String | Default is ‘index.html’. |
ssrPwaHtmlFilename | String | Used for SSR+PWA mode. Default is ‘offline.html’. |
productName | String | Default value is taken from package.json > productName field. |
distDir | String | Folder where Quasar CLI should generate the distributables. Relative path to project root directory. Default is ‘dist/{ctx.modeName}’. Applies to all Modes except for Cordova (which is forced to src-cordova/www ). |
ignorePublicFolder | Boolean | Ignores the /public folder. If you depend on a statics folder then you will need to configure it yourself (outside of Quasar or through the extendWebpack/chainWebpack), so make sure that you know what you are doing. |
devtool | String | Source map strategy to use. |
env | Object | Add properties to process.env that you can use in your website/app JS code. |
gzip | Boolean/Object | Gzip the distributables. Useful when the web server with which you are serving the content does not have gzip. If using as Object, it represents the compression-webpack-plugin config Object. |
analyze | Boolean/Object | Show analysis of build bundle with webpack-bundle-analyzer. If using as Object, it represents the webpack-bundle-analyzer config Object. |
vueCompiler | Boolean | Include vue runtime + compiler version, instead of default Vue runtime-only |
uglifyOptions | Object | JS minification options. Full list |
htmlMinifyOptions | Object | (requires @quasar/app-webpack v3.10.2+) Minification options for html-minifier. Full list |
vueLoaderOptions | Object | Options (compilerOptions, compiler, transformAssetUrls, etc) for vue-loader. |
scssLoaderOptions | Object | Options to supply to sass-loader for .scss files. Example: scssLoaderOptions: { additionalData: ‘@import “src/css/abstracts/_mixins.scss”;’} |
sassLoaderOptions | Object | Options to supply to sass-loader for .sass files. |
stylusLoaderOptions | Object | Options to supply to stylus-loader . |
lessLoaderOptions | Object | Options to supply to less-loader . |
The following properties of build
are automatically configured by Quasar CLI depending on dev/build commands and Quasar mode. But if you like to override some (make sure you know what you are doing), you can do so:
Property | Type | Description |
---|---|---|
extractCSS | Boolean | Extract CSS from Vue files |
sourceMap | Boolean | Use source maps |
minify | Boolean | Minify code (html, js, css) |
If, for example, you run “quasar build --debug”, sourceMap and extractCSS will be set to “true” regardless of what you configure.
Property: htmlVariables
You can define and then reference variables in /index.html or /src/index.template.html, like this:
module.exports = function (ctx) {
return {
htmlVariables: {
title: 'test name',
some: {
prop: 'my-prop'
}
}
Then (just an example showing you how to reference a variable defined above, in this case title
):
<%= title %>
<%= some.prop %>
Property: sourceFiles
Use this property to change the default names of some files of your website/app if you have to. All paths must be relative to the root folder of your project.
// default values:
sourceFiles: {
rootComponent: 'src/App.vue',
router: 'src/router',
store: 'src/store',
indexHtmlTemplate: 'src/index.template.html',
registerServiceWorker: 'src-pwa/register-service-worker.js',
serviceWorker: 'src-pwa/custom-service-worker.js',
electronMain: 'src-electron/electron-main.js',
electronPreload: 'src-electron/electron-preload.js'
}
Example setting env for dev/build
Please refer to Adding to process.env section in our docs.
Handling Webpack configuration
In depth analysis on Handling Webpack documentation page.