@hydration-audit/qwik

Qwik adapter for the Hydration Cost Visibility Platform.

Analyzes JavaScript costs in Qwik projects by reading the q-manifest.json produced by the Qwik optimizer.

Installation

npm install @hydration-audit/qwik

Usage

With the CLI

# Qwik auto-detected from package.json
npx @hydration-audit/cli analyze ./dist

# Or specify explicitly
npx @hydration-audit/cli analyze --config '{"framework":"qwik"}'

Programmatic

import { analyze } from '@hydration-audit/core';
import { QwikAdapter } from '@hydration-audit/qwik';

const report = await analyze({
  adapter: new QwikAdapter(),
  cwd: '/path/to/qwik-project',
});

How Qwik Differs

Qwik uses resumability instead of traditional hydration:

| Concept | Traditional (Astro/Fresh) | Qwik | |---|---|---| | Model | Hydration — re-execute JS to make components interactive | Resumability — serialize state, resume without re-execution | | Boundaries | client:load, client:visible | $ suffix (component$, useTask$, onClick$) | | Chunk splitting | Per-component entry chunks | Per-$ boundary (much more granular) | | Manifest | Build HTML + chunk names | q-manifest.json with full symbol graph |

What This Adapter Measures

Instead of "hydration cost," we measure the lazy-load cost — the JavaScript that downloads when a user interacts with a component:

• Each component$ boundary maps to one or more output chunks
• Event handlers (onClick$) are separate chunks loaded on interaction
• useTask$ boundaries are loaded when their dependencies change

How It Works

1. Read q-manifest.json

The Qwik optimizer produces q-manifest.json containing:

• symbols: All $ boundaries with source file, name, and type
• bundles: Output chunks with sizes, imports, and symbol associations
• mapping: Symbol hash → bundle file mapping

2. Extract Component Boundaries

The adapter extracts symbols with ctxKind: "component" or "function" that originate from user source files (not node_modules).

3. Map to Bundles

Each component may span multiple bundles (component$, onClick$, useTask$ each get their own chunk). The adapter aggregates all related bundles.

Exported API

| Export | Description | |---|---| | QwikAdapter | FrameworkAdapter implementation | | readQwikManifest(outDir) | Parse q-manifest.json | | extractComponentsFromManifest(manifest, srcDir) | Extract component boundaries | | mapSymbolsToBundles(manifest) | Map component names to bundle files | | adapter | Pre-instantiated adapter for auto-discovery |

Types

interface QwikManifest {
  manifestHash: string;
  symbols: Record<string, QwikSymbol>;
  mapping: Record<string, string>;
  bundles: Record<string, QwikBundle>;
  version: string;
}

License

MIT