Managing App Initialization with Quasar Boot Files

The Initialization Chaos Problem

As a Vue application grows, the main.js file often becomes a dumping ground for plugin registrations, global guards, and third-party library configurations. When you move toward Server-Side Rendering (SSR) or Static Site Generation (SSG), this monolithic setup often breaks because server-side environments lack browser globals like window or document, leading to hydration mismatches or runtime crashes.

The solution in the Quasar Framework is the Boot File. Instead of a single entry point, Quasar uses a convention-based system to execute initialization logic in a predictable sequence before the Vue app mounts. This ensures that your plugins, stores, and routers are configured identically across SPA, PWA, and SSR modes.

How Boot Files Orchestrate Startup

Boot files are JavaScript or TypeScript files located in the src/boot directory. Quasar automatically detects these files and executes them during the app's startup sequence. Each boot file exports a default function that receives the Vue app instance, the router, and the store (if using Pinia or Vuex).

The execution order is determined alphabetically by the filename. If you have 01.auth.js and 02.api.js, Quasar guarantees the authentication logic initializes before the API client. This is critical when your API client needs an auth token that is retrieved or configured during the first boot step.

Practical Example: Integrating an External API Client

Suppose you need to integrate an Axios instance with a global interceptor for error handling. Rather than importing this into every component, you can register it as a global property via a boot file.

Step 1: Create the boot file
Run the following command in your project root to generate the file and add it to the configuration:

quasar new boot axios

Step 2: Configure the logic
Edit src/boot/axios.js (or .ts). Note the use of the app instance to provide the client globally:

import axios from 'axios'

export default ({ app, store }) => {
  const api = axios.create({
    baseURL: 'https://api.example.com'
  })

  // Add a request interceptor to attach tokens from the store
  api.interceptors.request.use(config => {
    const token = store.state.auth.token
    if (token) {
      config.headers.Authorization = `Bearer ${token}`
    }
    return config
  })

  // Make the api instance available throughout the app
  app.config.globalProperties.$api = api
}

Step 3: Verification
To verify the registration, attempt to access this.$api in a component's mounted hook or use getCurrentInstance().appContext.config.globalProperties.$api in the Composition API. If the boot file is correctly listed in quasar.config.js, the instance will be defined.

The SSR Guardrail

One of the most common pitfalls when using boot files is forgetting that they execute on the server during SSR. If your boot file attempts to access localStorage or window.innerWidth directly at the top level, the Node.js server will throw a ReferenceError.

To handle this, use the process.env.SERVER or process.env.CLIENT flags provided by the Quasar CLI to wrap browser-specific logic:

export default ({ app }) => {
  if (process.env.CLIENT) {
    // This code only runs in the browser
    const theme = localStorage.getItem('user-theme')
    console.log('User theme is:', theme)
  }
}


Trade-offs and Performance
While boot files provide a clean separation of concerns, they are synchronous by nature. Heavy computational work or blocking synchronous calls within a boot file will delay the initial evaluation of the app, increasing the time to first paint (TTFP). For non-critical initialization (like analytics or logging), consider moving the logic into a mounted hook of the root component or using an asynchronous function within the boot file if the plugin supports it.

Summary of Constraints

  

    

      
Constraint
      
Behavior
      
Mitigation
    
  
  

    

      
Execution Order
      
Alphabetical by filename
      
Use numeric prefixes (e.g., 01_auth.js)
    
    

      
Environment
      
Runs on both Server and Client
      
Wrap browser APIs in process.env.CLIENT
    
    

      
Performance
      
Blocks app mount
      
Keep boot files lean; defer non-essential logic