Using Quasar Boot Files to Run Initialization Code Before the App Mounts

Quick answer

A Quasar boot file lets you execute code once during application startup, before the root Vue component mounts. You export a function wrapped with boot() from 'quasar/wrappers' and list the file (without the .js extension) in the boot array of quasar.config.js. Quasar calls each boot function with a context object that contains the created app, router, store and other instances.

How boot files work

When the Quasar CLI builds or serves the application, it reads the boot array in quasar.config.js. For each entry it:

1. Resolves the file src/boot/name.js
2. Imports the default export, which must be the result of calling boot(() => { … }) from 'quasar/wrappers'
3. Invokes the wrapped function, passing a context object that varies by installed plugins but always includes app (the Vue application instance) and router when the router plugin is active.

The boot functions run synchronously in the order they appear in the array, and only after Quasar has created the Vue app but before it mounts the root component (<q-layout> or similar). This makes boot files ideal for global setup that must happen before any component renders.

Worked example: adding an HTTP interceptor

Suppose you want to attach a request interceptor to Axios (or $q.http) so that every outgoing request carries an authentication token.

// src/boot/auth.js
import { boot } from 'quasar/wrappers'

// The wrapper ensures the function is called with the app context
export default boot(({ app }) => {
  // Assuming you have installed axios via a plugin and it is bound to $http
  const { $http } = app.config.globalProperties
  $http.interceptors.request.use(config => {
    const token = localStorage.getItem('authToken')
    if (token) {
      config.headers.Authorization = `Bearer ${token}`
    }
    return config
  })
})

Then register the boot file in quasar.config.js:

// quasar.config.js
module.exports = function (/* ctx */) {
  return {
    boot: ['auth']   // order matters if you have multiple boot files
    // … other config
  }
}

When the application starts, Quasar will:

1. Create the Vue app instance.
2. Call the auth boot function, which attaches the interceptor to $http.
3. Mount the root component, so any component that makes an HTTP request will already have the interceptor in place.

Execution order and dependencies

The boot array determines the sequence. If one boot file depends on another (for example, an i18n boot that installs a translation plugin before a boot that uses $t), list the dependency first:

boot: ['i18n', 'auth']

Changing the order changes the log or side‑effect execution order, which you can verify by adding console.log statements in each boot file and observing the console output during startup.

Typical uses

• Installing Vue plugins (app.use(plugin))
• Registering global components, directives, or filters
• Hydrating authentication state from localStorage or cookies
• Attaching HTTP request/response interceptors
• Setting up a global error handler (app.config.errorHandler)
• Configuring third‑party libraries that require a Vue instance (e.g., Vuetify, Pinia)

Limits and common mistakes

Server‑side rendering (SSR) caveats

Under SSR, boot files execute on the server for each request as well as in the browser. Any mutable state created at the module level (e.g., let counter = 0) is shared across requests and can lead to correctness bugs. To avoid this, keep state inside the boot function or reset it per request.

Not a replacement for route guards

Boot files run once per app instance. If you need per‑route authorization logic, place it in router.beforeEach guards or component navigation guards, not in a boot file.

Version sensitivity

• Quasar v2 targets Vue 3 and uses quasar.config.js with the import from 'quasar/wrappers'.
• Quasar v1 targeted Vue 2, used quasar.conf.js, and the wrapper was imported from quasar/framework (different signature).
• Copying a v2 boot file into a v1 project (or vice‑versa) will cause a build error.

Missing or misnamed files

If a name in the boot array does not match a file src/boot/name.js, the CLI fails during the build step with a module‑not‑found error, not a silent runtime warning.

Accessing browser‑only globals

Code that touches window, document, or other browser APIs must be guarded when SSR is enabled, for example:

import { boot } from 'quasar/wrappers'
import { Platform } from 'quasar'

export default boot(({ app }) => {
  if (Platform.is.client) {
    // safe to use window or document here
  }
})

How to verify it works

1. Create a fresh Quasar CLI project (quasar create my-app).
2. Add a boot file src/boot/test.js that logs a message:

export default boot(() => {
  console.log('Boot file executed')
})

3. List it in quasar.config.js (boot: ['test']).
4. Run quasar dev (SSR mode optional) and open the browser console.
5. You should see "Boot file executed" appear before any component’s mounted hook logs.
6. Reorder the boot array or add a second boot file with a different log to confirm execution order.

These steps confirm that the boot mechanism is functioning as described without asserting any specific output beyond the presence of the log.