h2ui is a high-efficiency CLI tool that converts static HTML pages into modular, reusable React (TSX/JSX) or Vue 3 (SFC) component trees using pure rule-based analysis.
Powered by AST parsing + semantic analysis, it automatically splits flat HTML into a sensible component hierarchy, extracts and deduplicates CSS styles, and provides a hot-reloading browser preview server out-of-the-box.
Chinese Documentation: README_zh.md
In the workflow of Idea (Text) ➔ Design (HTML) ➔ Development (React/Vue):
- AI models excel at generating single-file high-fidelity HTML designs from text ideas.
- However, letting LLMs directly write modular production component code often fails due to token limits, fragmentation, and styling standards violations.
h2ui serves as the bridging compiler. It takes a single high-fidelity HTML design and compiles it deterministically into production-ready components with clean CSS Modules, ensuring 100% rendering fidelity without the risks of pure-AI code generation.
- Smart Component Splitting: Automatically identifies semantic boundaries in your HTML (like
header,nav,main,footer, and repeated list items), builds a nested component hierarchy, and writes separate component files. - Multi-Framework Output: Supports both React (TSX/JSX) and Vue 3 (Single-File Components with
<template>,<script setup>,<style scoped>). - Batch Processing: Convert multiple HTML files at once using glob patterns with configurable concurrency.
- Zero-Config Style Extraction & Isolation:
- CSS Modules: Generates a
.module.cssfor each component by default and bindsclassName, providing absolute style encapsulation. - Shared Style Deduplication: Identifies identical inline style declarations across components and deduplicates them into
shared.module.css, inherited via CSS Modulescomposesrule. - Global Styles Preservation: Extracts global styles within
<style>tags to a standardglobal.cssand imports it in the root component. - Vue Scoped Styles: For Vue 3 output, generates
<style scoped>blocks with component-specific CSS.
- CSS Modules: Generates a
- External Resource Inclusion: Automatically parses external stylesheets, Web Fonts (e.g., Google Fonts), or icons from original HTML
<head>link tags and restores them in the preview environment. - Hot-Reloading Preview Server: A built-in dev server powered by Vite. When you modify generated component code, the browser preview reloads instantly.
Install globally via npm:
npm install -g h2ui-cliOr run directly without installation using npx:
npx h2ui-cli convert <path-to-html-file>For local development setup, install dependencies and build:
npm install
npm run buildNote
If installed globally or running via npx, use the executable command h2ui. If you are developing locally, replace h2ui with node dist/bin/h2ui.js.
Generates a .h2uirc configuration file to define your default preferences.
h2ui init [--force]Scaffold config template (.h2uirc):
{
"_comment": "h2ui configuration file.",
"out": "./h2ui_output/",
"typescript": true,
"strict": false,
"split": true,
"cssMode": "module"
}Configuration options explained:
| Option | Type | Default | Description |
|---|---|---|---|
out |
string |
./h2ui_output/ |
Output directory for generated components |
typescript |
boolean |
true |
Generate .tsx files (false for .jsx) |
strict |
boolean |
false |
Treat all warnings as errors, halt execution |
split |
boolean |
true |
Split HTML into component tree (false = single file) |
cssMode |
string |
module |
CSS output mode: module, scoped, inline, global |
framework |
string |
react |
Target framework: react or vue3 |
Converts a static HTML file to React TSX/JSX or Vue 3 SFC components:
h2ui convert <path-to-html-file> [options]Available Options:
--out <directory>: Output directory for the generated components (default:./h2ui_output/).--type <tsx|jsx>: Output file extension, eithertsxorjsx(default:tsx). Only applies to React output.--framework <react|vue3>: Target framework (default:react).--no-split: Disable component splitting and generate a single large component file.--strict: Strict mode; treats all warnings as errors and halts execution.
Examples:
# Convert to React TSX
h2ui convert input.html --out ./components
# Convert to Vue 3 SFC
h2ui convert input.html --framework vue3 --out ./components
# Convert as single JSX file without splitting
h2ui convert page.html --type jsx --no-splitConvert multiple HTML files using glob patterns:
h2ui batch "<glob-pattern>" [options]Available Options:
--out <directory>: Output directory (default:./h2ui_output/).--concurrency <number>: Number of files to process in parallel (default:1, max:4).--no-split: Disable component splitting.--strict: Promote all warnings to errors.
Examples:
# Convert all HTML files in a directory
h2ui batch "src/**/*.html"
# Convert with 4-way parallelism
h2ui batch "pages/*.html" --out ./components --concurrency 4Starts the local Vite-powered preview server with live reload:
h2ui preview [options]Available Options:
-o, --out <dir>: Output directory to watch and sync (default:./h2ui_output).-p, --port <port>: Port to run the preview server on (default:5173).
Example:
h2ui preview --out ./components --port 3000Open http://localhost:3000 in your browser to view your converted component tree live.
To ensure production-ready code quality, h2ui outputs styling under the following specifications:
- Global Stylesheets:
Global
<style>tags are written toglobal.cssand imported globally in the root component:import './global.css';
- External CDNs & Web Fonts:
Any external web resource links from the original HTML
<head>are dynamically injected into the head of the previewindex.html. - Shared Styles Inheritance (React):
Shared declarations across components are extracted into
.sharedinshared.module.cssand composed in component-level CSS Module files:.featureCard { composes: shared from './shared.module.css'; /* component-specific non-shared styles */ background: blue; }
- Vue Scoped Styles (Vue 3):
Each Vue SFC component includes a
<style scoped>block with component-specific CSS, ensuring style isolation without CSS Modules.
To run the Vitest unit tests:
npm test