htflow-cli
Version:
Webflow-compatible HTML/CSS/JS development tool. Install globally with 'npm install -g htflow-cli' for web development.
576 lines (422 loc) • 11.7 kB
Markdown
# HTFlow CLI
<div align="center">
**Build Webflow-compatible websites with AI assistance**
[Installation](#installation) • [Quick Start](#quick-start) • [Documentation](#documentation) • [Examples](#examples)
</div>
## 🚀 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)
```bash
npm install -g htflow-cli
```
### Verify Installation
```bash
htflow --version
# Output: 1.9.6
```
## 🚀 Quick Start
### 1. Initialize a New Project
```bash
# 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
```bash
# Start development server with hot reload
htflow serve dev
# Or start production server
htflow serve start
```
### 3. Audit Your Code
```bash
# Run comprehensive compliance audit
htflow audit
# Generate HTML audit report
htflow audit --html
# Fast essentials-only audit
htflow audit --essentials
```
### 4. Build for Webflow
```bash
# Build project for Webflow export
htflow build
```
## 📋 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**
```html
<body>
<div class="htflow-wrapper">
<!-- ALL CONTENT HERE -->
</div>
</body>
```
✅ **Required Attributes**
```html
<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**
```css
/* ✅ 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**
```css
@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**
```javascript
// ✅ 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
```bash
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
```bash
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
```bash
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
```json
{
"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 files for Webflow
└── htflow-audit-report.html # Audit report (if generated)
```
## 🌐 Webflow Integration
### Export to Webflow
1. **Build Project**
```bash
htflow build
```
2. **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
```bash
# 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
```bash
# Comprehensive audit
htflow audit --html
# Fix any compliance issues
# Re-run audit until clean
```
### 3. Production Phase
```bash
# Build for Webflow
htflow build
# Copy files to Webflow
# Test in Webflow editor
```
## 🔧 Configuration
### Development Server Options
```bash
# 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
```bash
# HTML report
htflow audit --html
# Essentials only
htflow audit --essentials
# Specific directory
htflow audit ./src
```
## 📚 Examples
### Basic HTFlow File
```html
<!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](#htflow-compliance-standards)
- Run `htflow audit` to identify issues
- Use `htflow audit --html` for detailed reports
## 🤝 Contributing
We welcome contributions! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `htflow audit` to ensure compliance
5. Submit a pull request
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built for the Webflow community
- Inspired by modern web development practices
- Powered by Node.js and TypeScript