@indirecttek/essentials-engine 1.1.0 → 1.1.2
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 +412 -0
- package/dist/components/Hero.astro +4 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,412 @@
|
|
|
1
|
+
# @indirecttek/essentials-engine
|
|
2
|
+
|
|
3
|
+
A **white-label, config-driven Astro component library** for rapidly building beautiful marketing websites for small businesses. Define your content and branding in a single configuration file, and Essentials Engine handles the rest.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@indirecttek/essentials-engine)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## ✨ Features
|
|
11
|
+
|
|
12
|
+
- **Config-Driven Architecture** – One configuration file powers your entire site
|
|
13
|
+
- **Zero Client-Side JavaScript** – 100% static output for blazing-fast performance
|
|
14
|
+
- **CSS Variable Theming** – Full control over colors with automatic propagation
|
|
15
|
+
- **Responsive by Default** – Mobile-first design that looks great on all devices
|
|
16
|
+
- **Modern Aesthetics** – Polished shadows, hover effects, and smooth transitions
|
|
17
|
+
- **Flexible Layouts** – Multiple hero styles, sticky navigation, and more
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 📦 Installation
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install @indirecttek/essentials-engine
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Peer Dependencies
|
|
28
|
+
|
|
29
|
+
Ensure your project has Astro and Tailwind CSS installed:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install astro tailwindcss
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Compatibility:**
|
|
36
|
+
- Astro 4.x or 5.x
|
|
37
|
+
- Tailwind CSS 3.x or 4.x
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 🚀 Quick Start
|
|
42
|
+
|
|
43
|
+
### 1. Create Your Site Configuration
|
|
44
|
+
|
|
45
|
+
Create a configuration file (e.g., `src/config/siteConfig.ts`):
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
import type { SiteConfig } from '@indirecttek/essentials-engine';
|
|
49
|
+
|
|
50
|
+
export const siteConfig: SiteConfig = {
|
|
51
|
+
businessName: "Raleigh Pro Landscaping",
|
|
52
|
+
|
|
53
|
+
theme: {
|
|
54
|
+
primary: "#2d5a27", // Forest green
|
|
55
|
+
secondary: "#e8f5e3", // Light sage
|
|
56
|
+
accent: "#f4a460", // Sandy brown
|
|
57
|
+
background: "#ffffff",
|
|
58
|
+
foreground: "#1a1a1a",
|
|
59
|
+
},
|
|
60
|
+
|
|
61
|
+
contactInfo: {
|
|
62
|
+
phone: "(919) 555-0123",
|
|
63
|
+
email: "hello@raleighprolandscaping.com",
|
|
64
|
+
address: "123 Oak Street, Raleigh, NC 27601",
|
|
65
|
+
},
|
|
66
|
+
|
|
67
|
+
heroSection: {
|
|
68
|
+
headline: "Transform Your Outdoor Space",
|
|
69
|
+
subheadline: "Professional landscaping services for homes and businesses in the Triangle area.",
|
|
70
|
+
// Supports both local paths (/images/hero.jpg) and external URLs
|
|
71
|
+
imageUrl: "https://images.unsplash.com/photo-1558904541-efa843a96f01?w=1200&h=800&fit=crop",
|
|
72
|
+
imageAlt: "Beautiful landscaped garden with flowers",
|
|
73
|
+
callToActionLabel: "Get a Free Quote",
|
|
74
|
+
},
|
|
75
|
+
|
|
76
|
+
services: [
|
|
77
|
+
{ name: "Lawn Care", description: "Weekly mowing, edging, and seasonal treatments to keep your lawn lush and healthy." },
|
|
78
|
+
{ name: "Garden Design", description: "Custom garden layouts with native plants, flowers, and decorative elements." },
|
|
79
|
+
{ name: "Hardscaping", description: "Patios, walkways, retaining walls, and outdoor living spaces." },
|
|
80
|
+
],
|
|
81
|
+
|
|
82
|
+
seo: {
|
|
83
|
+
title: "Raleigh Pro Landscaping | Professional Lawn & Garden Services",
|
|
84
|
+
description: "Transform your outdoor space with Raleigh's most trusted landscaping company. Lawn care, garden design, and hardscaping.",
|
|
85
|
+
},
|
|
86
|
+
|
|
87
|
+
analytics: {
|
|
88
|
+
enableTracking: false,
|
|
89
|
+
},
|
|
90
|
+
|
|
91
|
+
// Optional features
|
|
92
|
+
socialLinks: {
|
|
93
|
+
facebook: "https://facebook.com/raleighprolandscaping",
|
|
94
|
+
instagram: "https://instagram.com/raleighprolandscaping",
|
|
95
|
+
},
|
|
96
|
+
|
|
97
|
+
layoutOptions: {
|
|
98
|
+
heroLayout: "image-right", // "image-left" | "image-right" | "full-width"
|
|
99
|
+
stickyNav: true,
|
|
100
|
+
},
|
|
101
|
+
};
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### 2. Use the Layout in Your Page
|
|
105
|
+
|
|
106
|
+
Create your homepage (`src/pages/index.astro`):
|
|
107
|
+
|
|
108
|
+
```astro
|
|
109
|
+
---
|
|
110
|
+
import { EssentialsLayout } from '@indirecttek/essentials-engine';
|
|
111
|
+
import { siteConfig } from '../config/siteConfig';
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
<EssentialsLayout config={siteConfig} />
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
That's it! You now have a complete, professional marketing website.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## 🧩 Components
|
|
122
|
+
|
|
123
|
+
Essentials Engine provides both a full-page layout and individual components for flexibility.
|
|
124
|
+
|
|
125
|
+
### Full-Page Layout
|
|
126
|
+
|
|
127
|
+
```astro
|
|
128
|
+
---
|
|
129
|
+
import { EssentialsLayout } from '@indirecttek/essentials-engine';
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
<EssentialsLayout config={siteConfig} />
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Renders a complete page with: `Navbar` → `Hero` → `ServicesGrid` → `ContactForm` → `Footer`
|
|
136
|
+
|
|
137
|
+
### Individual Components
|
|
138
|
+
|
|
139
|
+
Use components individually for custom page structures:
|
|
140
|
+
|
|
141
|
+
```astro
|
|
142
|
+
---
|
|
143
|
+
import { Navbar, Hero, ServicesGrid, ContactForm, Footer } from '@indirecttek/essentials-engine';
|
|
144
|
+
import { siteConfig } from '../config/siteConfig';
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
<html lang="en">
|
|
148
|
+
<body>
|
|
149
|
+
<Navbar config={siteConfig} />
|
|
150
|
+
<Hero config={siteConfig} />
|
|
151
|
+
|
|
152
|
+
<!-- Your custom content here -->
|
|
153
|
+
<section class="py-16">
|
|
154
|
+
<h2>Why Choose Us?</h2>
|
|
155
|
+
<!-- ... -->
|
|
156
|
+
</section>
|
|
157
|
+
|
|
158
|
+
<ServicesGrid config={siteConfig} />
|
|
159
|
+
<ContactForm config={siteConfig} />
|
|
160
|
+
<Footer config={siteConfig} />
|
|
161
|
+
</body>
|
|
162
|
+
</html>
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Component Reference
|
|
166
|
+
|
|
167
|
+
| Component | Description |
|
|
168
|
+
|-----------|-------------|
|
|
169
|
+
| `EssentialsLayout` | Full-page wrapper with HTML head, all sections, and theme injection |
|
|
170
|
+
| `Navbar` | Header with business name, click-to-call, and "Contact Us" CTA |
|
|
171
|
+
| `Hero` | Above-the-fold section with headline, subheadline, image, and CTA |
|
|
172
|
+
| `ServicesGrid` | Responsive grid of service cards with hover effects |
|
|
173
|
+
| `ContactForm` | Lead capture form with name, email, phone, and message fields |
|
|
174
|
+
| `Footer` | Site footer with contact info, social icons, and copyright |
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## 🎨 Theming
|
|
179
|
+
|
|
180
|
+
Colors are defined in the `theme` object and automatically applied throughout the site using CSS variables.
|
|
181
|
+
|
|
182
|
+
```typescript
|
|
183
|
+
theme: {
|
|
184
|
+
primary: "#2d5a27", // Brand color, used for headings, nav, buttons
|
|
185
|
+
secondary: "#e8f5e3", // Section backgrounds (e.g., services grid)
|
|
186
|
+
accent: "#f4a460", // CTA buttons, highlights
|
|
187
|
+
background: "#ffffff", // Page background
|
|
188
|
+
foreground: "#1a1a1a", // Body text
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Using Theme Colors in Custom Components
|
|
193
|
+
|
|
194
|
+
The theme colors are available as CSS variables:
|
|
195
|
+
|
|
196
|
+
```css
|
|
197
|
+
.my-custom-element {
|
|
198
|
+
background-color: var(--color-primary);
|
|
199
|
+
color: var(--color-background);
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Or with Tailwind's arbitrary value syntax:
|
|
204
|
+
|
|
205
|
+
```html
|
|
206
|
+
<div class="bg-[color:var(--color-accent)] text-[color:var(--color-foreground)]">
|
|
207
|
+
Custom styled element
|
|
208
|
+
</div>
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 🖼️ Hero Layouts
|
|
214
|
+
|
|
215
|
+
The Hero component supports three layout modes:
|
|
216
|
+
|
|
217
|
+
### Image Right (Default)
|
|
218
|
+
```typescript
|
|
219
|
+
layoutOptions: {
|
|
220
|
+
heroLayout: "image-right",
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
Text on the left, image on the right – great for text-focused messaging.
|
|
224
|
+
|
|
225
|
+
### Image Left
|
|
226
|
+
```typescript
|
|
227
|
+
layoutOptions: {
|
|
228
|
+
heroLayout: "image-left",
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
Image on the left, text on the right – ideal for showcasing visuals.
|
|
232
|
+
|
|
233
|
+
### Full Width
|
|
234
|
+
```typescript
|
|
235
|
+
layoutOptions: {
|
|
236
|
+
heroLayout: "full-width",
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
Full-bleed background image with centered text overlay – high-impact hero style.
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## 📱 Responsive Design
|
|
244
|
+
|
|
245
|
+
All components are mobile-first and responsive:
|
|
246
|
+
|
|
247
|
+
- **Navbar**: Stacks phone number, hides "Contact Us" button on mobile
|
|
248
|
+
- **Hero**: Single column on mobile, side-by-side on desktop
|
|
249
|
+
- **ServicesGrid**: 1 column → 2 columns → 3 columns as screen grows
|
|
250
|
+
- **ContactForm**: Fields stack on mobile
|
|
251
|
+
- **Footer**: 3-column layout collapses to single column on mobile
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## 📋 Configuration Reference
|
|
256
|
+
|
|
257
|
+
### SiteConfig Interface
|
|
258
|
+
|
|
259
|
+
```typescript
|
|
260
|
+
interface SiteConfig {
|
|
261
|
+
businessName: string;
|
|
262
|
+
theme: Theme;
|
|
263
|
+
contactInfo: ContactInfo;
|
|
264
|
+
heroSection: HeroSection;
|
|
265
|
+
services: Service[];
|
|
266
|
+
analytics: AnalyticsConfig;
|
|
267
|
+
seo: SEOConfig;
|
|
268
|
+
imageSearchHints?: ImageSearchHints; // Optional
|
|
269
|
+
socialLinks?: SocialLinks; // Optional
|
|
270
|
+
layoutOptions?: LayoutOptions; // Optional
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### Theme
|
|
275
|
+
|
|
276
|
+
| Property | Type | Description |
|
|
277
|
+
|----------|------|-------------|
|
|
278
|
+
| `primary` | `string` | Brand color for headings, nav, primary buttons |
|
|
279
|
+
| `secondary` | `string` | Section backgrounds, subtle accents |
|
|
280
|
+
| `accent` | `string` | CTA buttons, highlights |
|
|
281
|
+
| `background` | `string` | Page background color |
|
|
282
|
+
| `foreground` | `string` | Body text color |
|
|
283
|
+
|
|
284
|
+
### ContactInfo
|
|
285
|
+
|
|
286
|
+
| Property | Type | Description |
|
|
287
|
+
|----------|------|-------------|
|
|
288
|
+
| `phone` | `string` | Phone number (auto-linked as `tel:`) |
|
|
289
|
+
| `email` | `string` | Email address (auto-linked as `mailto:`) |
|
|
290
|
+
| `address` | `string` | Physical address |
|
|
291
|
+
|
|
292
|
+
### HeroSection
|
|
293
|
+
|
|
294
|
+
| Property | Type | Description |
|
|
295
|
+
|----------|------|-------------|
|
|
296
|
+
| `headline` | `string` | Main headline text |
|
|
297
|
+
| `subheadline` | `string` | Supporting text below headline |
|
|
298
|
+
| `imageUrl` | `string` | Local path (`/images/hero.jpg`) or external URL (`https://...`) |
|
|
299
|
+
| `imageAlt` | `string` | Alt text for hero image |
|
|
300
|
+
| `callToActionLabel` | `string` | Text for CTA button |
|
|
301
|
+
|
|
302
|
+
#### Image URL Examples
|
|
303
|
+
|
|
304
|
+
**Local image** (stored in your `public/images/` folder):
|
|
305
|
+
```typescript
|
|
306
|
+
imageUrl: "/images/hero.jpg"
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
**External URL** (recommended for quick setup):
|
|
310
|
+
```typescript
|
|
311
|
+
imageUrl: "https://images.unsplash.com/photo-1558904541-efa843a96f01?w=1200&h=800&fit=crop"
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
> 💡 **Tip:** Use Unsplash's URL parameters (`?w=1200&h=800&fit=crop`) to optimize image size and aspect ratio.
|
|
315
|
+
|
|
316
|
+
### Service
|
|
317
|
+
|
|
318
|
+
| Property | Type | Description |
|
|
319
|
+
|----------|------|-------------|
|
|
320
|
+
| `name` | `string` | Service name |
|
|
321
|
+
| `description` | `string` | Service description |
|
|
322
|
+
|
|
323
|
+
### SEOConfig
|
|
324
|
+
|
|
325
|
+
| Property | Type | Description |
|
|
326
|
+
|----------|------|-------------|
|
|
327
|
+
| `title` | `string` | Page title (appears in browser tab) |
|
|
328
|
+
| `description` | `string` | Meta description for search engines |
|
|
329
|
+
|
|
330
|
+
### AnalyticsConfig
|
|
331
|
+
|
|
332
|
+
| Property | Type | Description |
|
|
333
|
+
|----------|------|-------------|
|
|
334
|
+
| `enableTracking` | `boolean` | Enable/disable analytics |
|
|
335
|
+
| `mixpanelToken` | `string` | Optional Mixpanel project token |
|
|
336
|
+
|
|
337
|
+
### SocialLinks (Optional)
|
|
338
|
+
|
|
339
|
+
| Property | Type | Description |
|
|
340
|
+
|----------|------|-------------|
|
|
341
|
+
| `facebook` | `string` | Facebook page URL |
|
|
342
|
+
| `instagram` | `string` | Instagram profile URL |
|
|
343
|
+
| `twitter` | `string` | Twitter/X profile URL |
|
|
344
|
+
| `linkedin` | `string` | LinkedIn page URL |
|
|
345
|
+
| `youtube` | `string` | YouTube channel URL |
|
|
346
|
+
| `tiktok` | `string` | TikTok profile URL |
|
|
347
|
+
|
|
348
|
+
### LayoutOptions (Optional)
|
|
349
|
+
|
|
350
|
+
| Property | Type | Default | Description |
|
|
351
|
+
|----------|------|---------|-------------|
|
|
352
|
+
| `heroLayout` | `"image-left"` \| `"image-right"` \| `"full-width"` | `"image-right"` | Hero section layout style |
|
|
353
|
+
| `stickyNav` | `boolean` | `false` | Make navbar stick to top on scroll |
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
## 📁 Project Structure
|
|
358
|
+
|
|
359
|
+
```
|
|
360
|
+
@indirecttek/essentials-engine/
|
|
361
|
+
├── dist/ # Built package (published to npm)
|
|
362
|
+
│ ├── components/
|
|
363
|
+
│ │ ├── ContactForm.astro
|
|
364
|
+
│ │ ├── Footer.astro
|
|
365
|
+
│ │ ├── Hero.astro
|
|
366
|
+
│ │ ├── Navbar.astro
|
|
367
|
+
│ │ └── ServicesGrid.astro
|
|
368
|
+
│ ├── layouts/
|
|
369
|
+
│ │ └── EssentialsLayout.astro
|
|
370
|
+
│ ├── index.ts # Main exports
|
|
371
|
+
│ └── types.ts # TypeScript interfaces
|
|
372
|
+
├── src/ # Source files
|
|
373
|
+
├── package.json
|
|
374
|
+
└── README.md
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## 🔧 Development
|
|
380
|
+
|
|
381
|
+
Clone and install:
|
|
382
|
+
|
|
383
|
+
```bash
|
|
384
|
+
git clone https://github.com/indirecttek/essentials-engine.git
|
|
385
|
+
cd essentials-engine
|
|
386
|
+
npm install
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
Build the package:
|
|
390
|
+
|
|
391
|
+
```bash
|
|
392
|
+
npm run build
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
---
|
|
396
|
+
|
|
397
|
+
## 📄 License
|
|
398
|
+
|
|
399
|
+
MIT © [IndirectTek](https://indirecttek.com)
|
|
400
|
+
|
|
401
|
+
---
|
|
402
|
+
|
|
403
|
+
## 🤝 Contributing
|
|
404
|
+
|
|
405
|
+
Contributions are welcome! Please open an issue or submit a pull request.
|
|
406
|
+
|
|
407
|
+
---
|
|
408
|
+
|
|
409
|
+
## 💬 Support
|
|
410
|
+
|
|
411
|
+
- **Issues**: [GitHub Issues](https://github.com/indirecttek/essentials-engine/issues)
|
|
412
|
+
- **Email**: support@indirecttek.com
|
|
@@ -8,6 +8,10 @@ export interface Props {
|
|
|
8
8
|
const { config } = Astro.props;
|
|
9
9
|
const { heroSection } = config;
|
|
10
10
|
const layout = config.layoutOptions?.heroLayout || "image-right";
|
|
11
|
+
|
|
12
|
+
// imageUrl supports both local paths (/images/hero.jpg) and external URLs (https://...)
|
|
13
|
+
// For external images, use services like Unsplash with size parameters:
|
|
14
|
+
// Example: "https://images.unsplash.com/photo-xxx?w=1200&h=800&fit=crop"
|
|
11
15
|
---
|
|
12
16
|
|
|
13
17
|
{layout === "full-width" ? (
|