🧪 Insights

Stage: prototyping

Insights allow your application to collect real user usage information to optimize the creation of bundles. By observing real user behavior, the Qwik build system can then do a better job prefetching bundles for your application. There are two benefits of this:

By noticing which symbols are used together, the bundler can colocate the symbols in the same bundle minimizing the waterfall that could occur if there are too many small files needing to be downloaded.
By observing in which order the symbols are used, the prefetcher can then fetch bundles in priority order ensuring that the bundles that are used more often are loaded first.

Architecture

The optimization consists of these parts:

A <Insights> component which collects real user usage data.
A registered application inside the builder.io database.
A qwikInsights Vite Plugin to load and save real user usage data during the build process.

NOTE: To try this new feature please drop a message inside the Qwik Discord server Currently Insights info is hosted in the Builder database. This information is about the execution of symbols/chunks in the application. The implementation of the service is open-source and you have the choice to use ours or host your own. (Please note, that this may become a paid service in the future.)

`<Insights>` component

The <Insights> component should be added to your root.tsx file.

To use it, you need to pass experimental: ['insights'] as an option to the qwikVite plugin as such:

// vite.config.mts
 
export default defineConfig(({ command, mode }): UserConfig => {
  return {
    plugins: [
      // ... other plugins like qwikRouter() etc
      qwikVite({
        experimental: ['insights']
        // ... other options
      }),
 
    ],
    // ... rest of the config
  };
}

// ...
import { Insights } from '@qwik.dev/core';
 
export default component$(() => {
  // ...
  return (
    <QwikRouterProvider>
      <head>
        // ...
        <Insights
          publicApiKey={import.meta.env.PUBLIC_QWIK_INSIGHTS_KEY}
        />
      </head>
      <body lang="en">
        // ...
      </body>
    </QwikRouterProvider>
  );
});

You can get PUBLIC_QWIK_INSIGHTS_KEY by visiting Qwik Insight.

The <Insights> component collects this data:

Timing information of symbols.
The pathname part of the URL.
Random sessionID which identifies which symbol loads came from the same browser session.

NOTE: The <Insights> component does not collect any user-identifiable information.

The information collected is sent to builder.io database for storage.

Vite integration

Once the application is running for a while and it collects sufficient information on symbol usage, the stats can be used to improve the bundles of the future version of the application. This is done by connecting the vite build with Insights like so:

file: vite.config.js

//..
import { defineConfig, loadEnv } from 'vite';
import { qwikInsights } from '@qwik.dev/core/insights/vite';
 
export default defineConfig(async () => {
  return {
    plugins: [
      qwikInsights({
        publicApiKey: loadEnv('', '.', '').PUBLIC_QWIK_INSIGHTS_KEY,
      }),
      //...
    ],
    // ...
  };
});

Contributors

Thanks to all the contributors who have helped make this documentation better!

🧪 Insights

Architecture

<Insights> component

Vite integration

Contributors

`<Insights>` component