@hydration-audit/astro

Astro integration for the Hydration Cost Visibility Platform.

Automatically analyzes hydration costs after every astro build. Parses .astro files for client:* directives, maps components to their output chunks, and reports issues.

Installation

npm install @hydration-audit/astro

Usage

As an Astro Integration

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import hydrationTax from '@hydration-audit/astro';

export default defineConfig({
  integrations: [
    react(),
    hydrationTax({
      thresholds: {
        islandBudget: 30_000,    // 30KB per island
      },
      rules: {
        'eager-below-fold': 'error',  // Upgrade to error
      },
    }),
  ],
});

After running astro build, you'll see:

[hydration-audit] Found 3 hydration issues across 5 islands

Plus a full terminal report with island sizes, issues, and recommendations.

Programmatic Usage

import { AstroAdapter, extractDirectives } from '@hydration-audit/astro';
import { analyze } from '@hydration-audit/core';

// Use the adapter with the core analyzer
const report = await analyze({
  adapter: new AstroAdapter(),
  cwd: '/path/to/astro-project',
});

// Or extract directives from a single file
const directives = await extractDirectives(
  astroFileContents,
  'src/pages/index.astro',
);

How It Works

1. Directive Parsing

Uses @astrojs/compiler (the same WASM-based parser Astro uses) to parse .astro files and extract client:* directives:

---
import SearchBar from '../components/SearchBar.tsx';
import Footer from '../components/Footer.svelte';
---

<SearchBar client:load />      <!-- Detected: client:load, react -->
<Footer client:visible />      <!-- Detected: client:visible, svelte -->

2. Manifest Reading

Scans built HTML files for <astro-island> elements to map component names to their actual output chunk URLs:

<astro-island component-url="/_astro/SearchBar.abc123.js" renderer-url="/_astro/client.def456.js">

3. Framework Detection

Automatically detects the UI framework from import paths:

• .tsx / .jsx → React
• .svelte → Svelte
• .vue → Vue
• .solid → Solid

Exported API

| Export | Description | |---|---| | default (function) | Astro integration factory: hydrationTax(options?) | | AstroAdapter | FrameworkAdapter implementation for programmatic use | | extractDirectives(source, filePath) | Parse directives from an Astro file | | detectUIFramework(importSource) | Detect UI framework from import path | | readAstroIslands(outDir) | Scan built HTML for <astro-island> elements | | buildChunkAssociations(outDir, islands) | Map component names to chunk files |

License

MIT