html-component-engine 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +247 -0
- package/bin/cli.js +529 -0
- package/package.json +37 -0
- package/src/engine/compiler.js +312 -0
- package/src/engine/utils.js +74 -0
- package/src/index.js +279 -0
package/README.md
ADDED
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# HTML Component Engine
|
|
2
|
+
|
|
3
|
+
A lightweight Vite plugin that enables reusable HTML components for static site generation. Compiles to pure HTML with inlined CSS/JS - no runtime JavaScript required.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- ✅ Reusable HTML components with props
|
|
8
|
+
- ✅ **Slot/children support** - Pass content into components
|
|
9
|
+
- ✅ CSS/JS inlining - No external files in production
|
|
10
|
+
- ✅ Variant system for component styles
|
|
11
|
+
- ✅ Nested components
|
|
12
|
+
- ✅ Hot reload during development
|
|
13
|
+
- ✅ Zero runtime JavaScript
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install html-component-engine
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Requires Vite ^7.0.0
|
|
22
|
+
|
|
23
|
+
## Folder Structure
|
|
24
|
+
|
|
25
|
+
Your project must follow this structure:
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
src/
|
|
29
|
+
pages/ # HTML pages (compiled to dist/*.html)
|
|
30
|
+
index.html
|
|
31
|
+
about.html
|
|
32
|
+
components/ # Reusable components
|
|
33
|
+
Header.html
|
|
34
|
+
Footer.html
|
|
35
|
+
Card.html
|
|
36
|
+
main/
|
|
37
|
+
Button.html
|
|
38
|
+
assets/ # Static assets
|
|
39
|
+
styles/
|
|
40
|
+
styles.css
|
|
41
|
+
images/
|
|
42
|
+
fonts/
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- `src/pages/`: HTML pages - each becomes an output file
|
|
46
|
+
- `src/components/`: Reusable HTML components (supports nested folders and .js files)
|
|
47
|
+
- `src/assets/`: Static assets - images/fonts copied to `dist/assets/`, CSS/JS inlined
|
|
48
|
+
|
|
49
|
+
## Configuration
|
|
50
|
+
|
|
51
|
+
```javascript
|
|
52
|
+
// vite.config.js
|
|
53
|
+
import htmlComponentEngine from 'html-component-engine';
|
|
54
|
+
|
|
55
|
+
export default {
|
|
56
|
+
plugins: [
|
|
57
|
+
htmlComponentEngine({
|
|
58
|
+
pagesDir: 'src/pages', // Pages directory (default)
|
|
59
|
+
componentsDir: 'src/components', // Components directory (default)
|
|
60
|
+
assetsDir: 'src/assets', // Assets directory (default)
|
|
61
|
+
inlineStyles: true, // Inline CSS into HTML (default: true)
|
|
62
|
+
inlineScripts: true, // Inline JS into HTML (default: true)
|
|
63
|
+
})
|
|
64
|
+
],
|
|
65
|
+
build: {
|
|
66
|
+
outDir: 'dist',
|
|
67
|
+
emptyOutDir: true,
|
|
68
|
+
}
|
|
69
|
+
};
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Component Syntax
|
|
73
|
+
|
|
74
|
+
### Self-Closing Components (Props Only)
|
|
75
|
+
|
|
76
|
+
Use `<Component src="...">` for simple components:
|
|
77
|
+
|
|
78
|
+
```html
|
|
79
|
+
<!-- src/pages/index.html -->
|
|
80
|
+
<!DOCTYPE html>
|
|
81
|
+
<html lang="en">
|
|
82
|
+
<head>
|
|
83
|
+
<meta charset="UTF-8">
|
|
84
|
+
<title>My Page</title>
|
|
85
|
+
<link rel="stylesheet" href="/styles/styles.css">
|
|
86
|
+
</head>
|
|
87
|
+
<body>
|
|
88
|
+
<Component src="Header" />
|
|
89
|
+
<h1>Welcome</h1>
|
|
90
|
+
<Component src="main/Button" text="Click Me" variant="primary" />
|
|
91
|
+
<Component src="Footer" />
|
|
92
|
+
</body>
|
|
93
|
+
</html>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Components with Children (Slots)
|
|
97
|
+
|
|
98
|
+
Use `<Component name="...">` for components that accept children:
|
|
99
|
+
|
|
100
|
+
```html
|
|
101
|
+
<Component name="Card" title="My Card">
|
|
102
|
+
<h2>Hello</h2>
|
|
103
|
+
<p>This content is passed to the component's slot</p>
|
|
104
|
+
</Component>
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Component template with `{{ children }}` slot:
|
|
108
|
+
|
|
109
|
+
```html
|
|
110
|
+
<!-- src/components/Card.html -->
|
|
111
|
+
<div class="card">
|
|
112
|
+
<div class="card-header">
|
|
113
|
+
<h4>{{ title }}</h4>
|
|
114
|
+
</div>
|
|
115
|
+
<div class="card-body">
|
|
116
|
+
{{ children }}
|
|
117
|
+
</div>
|
|
118
|
+
</div>
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Output:**
|
|
122
|
+
|
|
123
|
+
```html
|
|
124
|
+
<div class="card">
|
|
125
|
+
<div class="card-header">
|
|
126
|
+
<h4>My Card</h4>
|
|
127
|
+
</div>
|
|
128
|
+
<div class="card-body">
|
|
129
|
+
<h2>Hello</h2>
|
|
130
|
+
<p>This content is passed to the component's slot</p>
|
|
131
|
+
</div>
|
|
132
|
+
</div>
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Props and Variants
|
|
136
|
+
|
|
137
|
+
In component files, use `{{propName}}` placeholders:
|
|
138
|
+
|
|
139
|
+
```html
|
|
140
|
+
<!-- src/components/main/Button.html -->
|
|
141
|
+
<!-- variants: primary=primary-btn, secondary=secondary-btn -->
|
|
142
|
+
<button class="{{variantClasses}}">{{text}}</button>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Usage:
|
|
146
|
+
|
|
147
|
+
```html
|
|
148
|
+
<Component src="main/Button" text="Click Me" variant="primary" />
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### JavaScript Components
|
|
152
|
+
|
|
153
|
+
Components can also be JavaScript files:
|
|
154
|
+
|
|
155
|
+
```javascript
|
|
156
|
+
// src/components/Counter.js
|
|
157
|
+
export default function Counter({ initial = 0 }) {
|
|
158
|
+
return `
|
|
159
|
+
<div class="counter">
|
|
160
|
+
<button onclick="this.nextElementSibling.textContent--">-</button>
|
|
161
|
+
<span>${initial}</span>
|
|
162
|
+
<button onclick="this.previousElementSibling.textContent++">+</button>
|
|
163
|
+
</div>
|
|
164
|
+
`;
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Usage: `<Component src="Counter" initial="5" />`
|
|
169
|
+
|
|
170
|
+
## Development
|
|
171
|
+
|
|
172
|
+
Run the development server:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
npm run dev
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Live reload is enabled - changes to pages, components, or assets automatically refresh the browser.
|
|
179
|
+
|
|
180
|
+
## Build
|
|
181
|
+
|
|
182
|
+
Build for production:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
npm run build
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Build Output
|
|
189
|
+
|
|
190
|
+
The build generates:
|
|
191
|
+
|
|
192
|
+
```
|
|
193
|
+
dist/
|
|
194
|
+
index.html # Compiled HTML with inlined CSS
|
|
195
|
+
about.html # All components resolved
|
|
196
|
+
assets/
|
|
197
|
+
images/ # Copied from src/assets
|
|
198
|
+
fonts/ # Only non-CSS/JS assets
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
**Key features:**
|
|
202
|
+
- ✅ All `<Component>` tags replaced with actual HTML
|
|
203
|
+
- ✅ CSS inlined as `<style>` tags
|
|
204
|
+
- ✅ JS inlined as `<script>` tags
|
|
205
|
+
- ✅ No standalone `.css` or `.js` files
|
|
206
|
+
- ✅ Assets (images, fonts) copied to `dist/assets/`
|
|
207
|
+
- ✅ Valid, production-ready HTML
|
|
208
|
+
|
|
209
|
+
## API
|
|
210
|
+
|
|
211
|
+
### Plugin Options
|
|
212
|
+
|
|
213
|
+
| Option | Type | Default | Description |
|
|
214
|
+
|--------|------|---------|-------------|
|
|
215
|
+
| `pagesDir` | string | `'src/pages'` | Directory containing HTML pages |
|
|
216
|
+
| `componentsDir` | string | `'src/components'` | Directory containing components |
|
|
217
|
+
| `assetsDir` | string | `'src/assets'` | Directory containing assets |
|
|
218
|
+
| `inlineStyles` | boolean | `true` | Inline CSS into HTML |
|
|
219
|
+
| `inlineScripts` | boolean | `true` | Inline JS into HTML |
|
|
220
|
+
|
|
221
|
+
### Component Attributes
|
|
222
|
+
|
|
223
|
+
**Self-closing components (`<Component src="..." />`):**
|
|
224
|
+
- `src` (required): Component path relative to `componentsDir`
|
|
225
|
+
- `variant`: Apply variant classes
|
|
226
|
+
- Any other attribute: Passed as props
|
|
227
|
+
|
|
228
|
+
**Components with children (`<Component name="...">`):**
|
|
229
|
+
- `name` (required): Component name/path
|
|
230
|
+
- Any other attribute: Passed as props
|
|
231
|
+
|
|
232
|
+
### Placeholders
|
|
233
|
+
|
|
234
|
+
- `{{ propName }}`: Replaced with prop value
|
|
235
|
+
- `{{ children }}`: Replaced with component's inner content
|
|
236
|
+
- `{{ variantClasses }}`: Replaced with variant classes
|
|
237
|
+
|
|
238
|
+
## Example
|
|
239
|
+
|
|
240
|
+
See the `example/` directory for a complete working example:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
cd example
|
|
244
|
+
npm install
|
|
245
|
+
npm run dev # Development
|
|
246
|
+
npm run build # Production build
|
|
247
|
+
```
|