Next.js Hydration Parser (JS)

A 99.9% AI-generated (including unit tests & README) JS port of kennyaires/nextjs-hydration-parser for extracting and parsing Next.js hydration data from HTML content.

Installation

bun add nextjs-hydration-parser

Usage

import {
    parse,
    parseAndFind
} from 'nextjs-hydration-parser';

const html = `... fetch your html content ...`;

// Full parsing
const result = parse(html);
console.log(result);

// Lightweight parsing (faster, filters by keywords)
const specificData = parse(html, {
    lightweight: true,
    targetPatterns: ['myImportantData']
});

// Parse and find specific keys in one go
const items = parseAndFind(html, ['productPrice', 'inventory']);

API

parse(htmlContent, options)

Parses Next.js hydration data from script tags containing self.__next_f.push.

• htmlContent (string): The raw HTML string.
• options (object, optional):
  • lightweight (boolean): If true, only processes chunks containing targetPatterns. Defaults to false.
  • targetPatterns (string[]): List of strings to search for in lightweight mode.

Returns an array of processed chunks, each containing:

• chunk_id: The ID of the chunk.
• extracted_data: Array of parsed data structures (JSON objects).
• chunk_count: Number of raw script tags combined for this chunk.

findDataByPattern(parsedChunks, pattern)

Searches for data within parsed chunks where keys match a specific pattern.

• parsedChunks (Array): The output from parse().
• pattern (string): The key substring to search for (case-insensitive).

Returns an array of found items with { path, key, value }.

parseAndFind(htmlContent, patterns)

Convenience method to parse in lightweight mode and immediately find data matching patterns.

• htmlContent (string): Raw HTML.
• patterns (string[]): List of patterns to find.

getAllKeys(parsedChunks, maxDepth)

Analyzes the parsed data to list all unique keys found.

• parsedChunks (Array): Output from parse().
• maxDepth (number): parsing depth limit (default 3).

Returns an object mapping keys to their occurrence counts.