Package Exports

htflow-cli
htflow-cli/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (htflow-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

HTFlow CLI

Build Webflow-compatible websites with AI assistance

Installation • Quick Start • Documentation • Examples

🚀 What is HTFlow CLI?

HTFlow CLI is a comprehensive development tool that helps you build Webflow-compatible websites with AI assistance. It enforces HTFlow standards, provides real-time validation, and includes a powerful audit system to ensure your code meets Webflow's requirements.

✨ Key Features

🎯 HTFlow Compliance: Built-in validation for HTFlow standards
🔥 Live Development Server: Real-time development with hot reload
🔍 Comprehensive Audit System: Detailed compliance checking
🤖 AI Integration: MCP server for AI-powered development
📦 Template Generation: Quick project setup with best practices
🛡️ Rule Enforcement: Automatic HTFlow rule validation
🌐 Webflow Compatibility: Direct export to Webflow

📦 Installation

Global Installation (Recommended)

npm install -g htflow-cli

Verify Installation

htflow --version
# Output: 2.0.1

🚀 Quick Start

1. Initialize a New Project

# Create a new HTFlow project
htflow init

# This creates:
# ├── .cursor/rules/          # HTFlow rules for AI
# ├── .cursor/mcp.json        # MCP server configuration
# └── index.html              # Sample HTFlow-compliant file

2. Start Development

# Start development server with hot reload
htflow serve dev

# Or start production server
htflow serve start

3. Audit Your Code

# Run comprehensive compliance audit
htflow audit

# Generate HTML audit report
htflow audit --html

# Fast essentials-only audit
htflow audit --essentials

4. Build for Webflow

# Build copyable bundles (default)
htflow build

# Also export plain HTML copies to webflow/
htflow build --webflow

This creates copyable bundles by page:

htflow-copyable/<page>/<page>.{html,css,js} ready to copy/paste
- The <page>.html contains only the <div class="htflow-wrapper">...</div> block (no doctype/head/body)

Optional: add --webflow to also export plain HTML copies to webflow/.

Example:

htflow-copyable/
├── index/
│   ├── index.html
│   ├── index.css
│   └── index.js
└── about/
    ├── about.html
    ├── about.css
    └── about.js

📋 Commands Reference

Core Commands

Command	Description	Options
`htflow init`	Initialize new HTFlow project	-
`htflow serve dev`	Start development server	`--port`, `--host`
`htflow serve start`	Start production server	`--port`, `--host`
`htflow audit`	Run compliance audit	`--html`, `--essentials`
`htflow build`	Build project for Webflow	-
`htflow workflow`	Generate workflow templates	-

Advanced Commands

Command	Description
`htflow --version`	Show version information
`htflow --help`	Show help information

🎯 HTFlow Compliance Standards

HTML Requirements

✅ Mandatory Structure

<body>
  <div class="htflow-wrapper">
    <!-- ALL CONTENT HERE -->
  </div>
</body>

✅ Required Attributes

<style data-ht-styles>
  /* CSS */
</style>
<script data-ht-main-script>
  /* JS */
</script>

✅ Semantic Elements

Use <header>, <main>, <footer>, <section>
Every element MUST have a class name
Use <button> for clicks, <a> for links
Use <img> with alt attributes

CSS Requirements

✅ Vanilla CSS Only

/* ✅ Good: Longhand properties */
.card {
  margin-top: 20px;
  margin-bottom: 20px;
  padding-top: 15px;
  padding-bottom: 15px;
  border-width: 1px;
  border-style: solid;
  border-color: #ccc;
}

/* ✅ Good: Required grid-template-rows */
.grid-container {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
  grid-template-rows: 1fr; /* Required */
  gap: 20px;
}

✅ Responsive Breakpoints

@media (max-width: 991px) {
  /* Tablet */
}
@media (max-width: 767px) {
  /* Mobile Landscape */
}
@media (max-width: 479px) {
  /* Mobile Portrait */
}

❌ Forbidden

CSS frameworks (Tailwind, Bootstrap)
CSS variables (--custom-properties)
background-image property
Shorthand properties (margin: 10px 20px)
Styling .htflow-wrapper class

JavaScript Requirements

✅ Modern ES6+ Only

// ✅ Good: data-ht attribute selection
document.querySelectorAll("[data-ht-button]").forEach((button) => {
  button.addEventListener("click", handleClick);
});

// ✅ Good: Modern JavaScript
const handleClick = (event) => {
  const target = event.target;
  const data = target.dataset.htData;
};

❌ Forbidden

var declarations
Function declarations
Class/ID selectors (.class, #id)
getElementById/getElementsByClassName
External JavaScript libraries

🔍 Audit System

Comprehensive Audit

htflow audit

Output:

🔍 HTFlow Audit Report
📁 Path: /path/to/project
🖥️ System: darwin arm64

📊 Summary:
  • Files audited: 3
  • Total issues: 5

📄 File 1: index.html
  • Issues: 2
    ❌ Missing htflow-wrapper div
    ⚠️ Missing data-ht-styles attribute

📄 File 2: styles.css
  • Issues: 3
    ❌ Using CSS shorthand properties
    ❌ Missing grid-template-rows
    ⚠️ Invalid breakpoint: 768px

HTML Audit Report

htflow audit --html

Generates a detailed HTML report with:

File-by-file analysis
Issue severity levels
Line number references
Fix suggestions
Visual compliance dashboard

Essentials-Only Audit

htflow audit --essentials

Fast audit focusing on critical rules only.

🤖 AI Integration (MCP Server)

HTFlow CLI includes a Model Context Protocol (MCP) server for AI-powered development:

Available AI Tools

htflow_rules: Get HTFlow rules for HTML, CSS, or JavaScript
htflow_audit: Audit HTML files for HTFlow compliance
htflow_validate: Validate HTML/CSS/JS code for HTFlow compliance

MCP Configuration

{
  "mcpServers": {
    "htflow": {
      "command": "htflow",
      "args": ["mcp-server"]
    }
  }
}

📁 Project Structure

my-htflow-project/
├── .cursor/
│   ├── rules/
│   │   ├── htflow-html-essentials.mdc
│   │   ├── htflow-css-essentials.mdc
│   │   ├── htflow-js-essentials.mdc
│   │   └── examples/
│   └── mcp.json
├── index.html              # Main HTFlow file
├── webflow/                # Built HTML copies
├── htflow-copyable/        # Copyable bundles per page
│   ├── index/
│   │   ├── index.html
│   │   ├── index.css
│   │   └── index.js
│   └── about/
│       ├── about.html
│       ├── about.css
│       └── about.js
└── htflow-audit-report.html # Audit report (if generated)

🌐 Webflow Integration

Export to Webflow

Build Project
```
htflow build
```
Copy to Webflow
- Copy files from webflow/ directory
- Paste into Webflow's custom code sections
- Ensure all HTFlow rules are followed

Webflow Compatibility

HTFlow CLI ensures your code is:

✅ Webflow-compatible
✅ Responsive across all devices
✅ Optimized for Webflow's rendering engine
✅ Following Webflow's best practices

🛠️ Development Workflow

1. Development Phase

# Start development server
htflow serve dev

# Make changes to your HTML/CSS/JS
# Server automatically reloads

# Run audits as needed
htflow audit

2. Testing Phase

# Comprehensive audit
htflow audit --html

# Fix any compliance issues
# Re-run audit until clean

3. Production Phase

# Build for Webflow
htflow build

# Copy files to Webflow
# Test in Webflow editor

🔧 Configuration

Development Server Options

# Custom port
htflow serve dev --port 3000

# Custom host
htflow serve dev --host 0.0.0.0

# Production server
htflow serve start --port 8080

Audit Options

# HTML report
htflow audit --html

# Essentials only
htflow audit --essentials

# Specific directory
htflow audit ./src

📚 Examples

Basic HTFlow File

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>HTFlow Example</title>
  </head>
  <body>
    <div class="htflow-wrapper">
      <header class="header">
        <nav class="nav">
          <a href="#" class="nav-link">Home</a>
          <a href="#" class="nav-link">About</a>
        </nav>
      </header>

      <main class="main">
        <section class="hero">
          <h1 class="hero-title">Welcome to HTFlow</h1>
          <p class="hero-description">Build Webflow-compatible websites</p>
          <button class="hero-button" data-ht-button>Get Started</button>
        </section>
      </main>

      <footer class="footer">
        <p class="footer-text">© 2024 HTFlow CLI</p>
      </footer>
    </div>

    <style data-ht-styles>
      .htflow-wrapper {
        max-width: 1200px;
        margin-left: auto;
        margin-right: auto;
        padding-top: 20px;
        padding-bottom: 20px;
      }

      .header {
        margin-bottom: 40px;
      }

      .nav {
        display: flex;
        gap: 20px;
      }

      .nav-link {
        color: #333;
        text-decoration: none;
      }

      .hero {
        text-align: center;
        margin-bottom: 60px;
      }

      .hero-title {
        font-size: 3rem;
        margin-bottom: 20px;
      }

      .hero-description {
        font-size: 1.2rem;
        margin-bottom: 30px;
      }

      .hero-button {
        background-color: #007bff;
        color: white;
        border: none;
        padding-top: 12px;
        padding-bottom: 12px;
        padding-left: 24px;
        padding-right: 24px;
        border-radius: 4px;
        cursor: pointer;
      }

      .footer {
        text-align: center;
        margin-top: 60px;
      }

      @media (max-width: 767px) {
        .hero-title {
          font-size: 2rem;
        }

        .nav {
          flex-direction: column;
        }
      }
    </style>

    <script data-ht-main-script>
      document.querySelectorAll("[data-ht-button]").forEach((button) => {
        button.addEventListener("click", (event) => {
          console.log("Button clicked!");
        });
      });
    </script>
  </body>
</html>

🐛 Troubleshooting

Common Issues

Issue: htflow: command not found Solution: Ensure global installation: npm install -g htflow-cli

Issue: Audit shows 0 files analyzed Solution: Ensure you're in a directory with HTML files

Issue: CSS validation errors Solution: Check for shorthand properties and missing grid-template-rows

Issue: JavaScript validation errors Solution: Replace var with const/let, use arrow functions

Getting Help

Check the HTFlow Rules
Run htflow audit to identify issues
Use htflow audit --html for detailed reports

🤝 Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch
Make your changes
Run htflow audit to ensure compliance
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built for the Webflow community
Inspired by modern web development practices
Powered by Node.js and TypeScript