npm package: @indirecttek/essentials-engine
Description: 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.
Latest version: 1.4.0

# @indirecttek/essentials-engine

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.

[![npm version](https://img.shields.io/npm/v/@indirecttek/essentials-engine.svg)](https://www.npmjs.com/package/@indirecttek/essentials-engine)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

---

## ✨ Features

- **Config-Driven Architecture** – One configuration file powers your entire site
- **Zero Client-Side JavaScript** – 100% static output for blazing-fast performance
- **CSS Variable Theming** – Full control over colors with automatic propagation
- **Responsive by Default** – Mobile-first design that looks great on all devices
- **Modern Aesthetics** – Polished shadows, hover effects, and smooth transitions
- **Flexible Layouts** – Multiple hero styles, sticky navigation, and more

---

## 📦 Installation

```bash
npm install @indirecttek/essentials-engine
```

### Peer Dependencies

Ensure your project has Astro and Tailwind CSS installed:

```bash
npm install astro tailwindcss
```

**Compatibility:**
- Astro 4.x or 5.x
- Tailwind CSS 3.x or 4.x

---

## 🚀 Quick Start

### 1. Create Your Site Configuration

Create a configuration file (e.g., `src/config/siteConfig.ts`):

```typescript
import type { SiteConfig } from '@indirecttek/essentials-engine';

export const siteConfig: SiteConfig = {
  businessName: "Raleigh Pro Landscaping",
  
  theme: {
    primary: "#2d5a27",      // Forest green
    secondary: "#e8f5e3",    // Light sage
    accent: "#f4a460",       // Sandy brown
    background: "#ffffff",
    foreground: "#1a1a1a",
  },
  
  contactInfo: {
    phone: "(919) 555-0123",
    email: "hello@raleighprolandscaping.com",
    address: "123 Oak Street, Raleigh, NC 27601",
  },
  
  heroSection: {
    headline: "Transform Your Outdoor Space",
    subheadline: "Professional landscaping services for homes and businesses in the Triangle area.",
    // Supports both local paths (/images/hero.jpg) and external URLs
    imageUrl: "https://images.unsplash.com/photo-1558904541-efa843a96f01?w=1200&h=800&fit=crop",
    imageAlt: "Beautiful landscaped garden with flowers",
    callToActionLabel: "Get a Free Quote",
  },
  
  services: [
    { name: "Lawn Care", description: "Weekly mowing, edging, and seasonal treatments to keep your lawn lush and healthy." },
    { name: "Garden Design", description: "Custom garden layouts with native plants, flowers, and decorative elements." },
    { name: "Hardscaping", description: "Patios, walkways, retaining walls, and outdoor living spaces." },
  ],
  
  seo: {
    title: "Raleigh Pro Landscaping | Professional Lawn & Garden Services",
    description: "Transform your outdoor space with Raleigh's most trusted landscaping company. Lawn care, garden design, and hardscaping.",
  },
  
  analytics: {
    enableTracking: false,
  },
  
  // Optional features
  socialLinks: {
    facebook: "https://facebook.com/raleighprolandscaping",
    instagram: "https://instagram.com/raleighprolandscaping",
  },
  
  layoutOptions: {
    heroLayout: "image-right",  // "image-left" | "image-right" | "full-width"
    stickyNav: true,
  },
};
```

### 2. Use the Layout in Your Page

Create your homepage (`src/pages/index.astro`):

```astro
---
import { EssentialsLayout } from '@indirecttek/essentials-engine';
import { siteConfig } from '../config/siteConfig';
---

<EssentialsLayout config={siteConfig} />
```

That's it! You now have a complete, professional marketing website.

---

## 🧩 Components

Essentials Engine provides both a full-page layout and individual components for flexibility.

### Full-Page Layout

```astro
---
import { EssentialsLayout } from '@indirecttek/essentials-engine';
---

<EssentialsLayout config={siteConfig} />
```

Renders a complete page with: `Navbar` → `Hero` → `ServicesGrid` → `ContactForm` → `Footer`

### Individual Components

Use components individually for custom page structures:

```astro
---
import { Navbar, Hero, ServicesGrid, ContactForm, Footer } from '@indirecttek/essentials-engine';
import { siteConfig } from '../config/siteConfig';
---

<html lang="en">
  <body>
    <Navbar config={siteConfig} />
    <Hero config={siteConfig} />
    
    <!-- Your custom content here -->
    <section class="py-16">
      <h2>Why Choose Us?</h2>
      <!-- ... -->
    </section>
    
    <ServicesGrid config={siteConfig} />
    <ContactForm config={siteConfig} />
    <Footer config={siteConfig} />
  </body>
</html>
```

### Component Reference

| Component | Description |
|-----------|-------------|
| `EssentialsLayout` | Full-page wrapper with HTML head, all sections, and theme injection |
| `Navbar` | Header with business name, click-to-call, and "Contact Us" CTA |
| `Hero` | Above-the-fold section with headline, subheadline, image, and CTA |
| `ServicesGrid` | Responsive grid of service cards with hover effects |
| `ContactForm` | Lead capture form with name, email, phone, and message fields |
| `Footer` | Site footer with contact info, social icons, and copyright |

---

## 🎨 Theming

Colors are defined in the `theme` object and automatically applied throughout the site using CSS variables.

```typescript
theme: {
  primary: "#2d5a27",      // Brand color, used for headings, nav, buttons
  secondary: "#e8f5e3",    // Section backgrounds (e.g., services grid)
  accent: "#f4a460",       // CTA buttons, highlights
  background: "#ffffff",   // Page background
  foreground: "#1a1a1a",   // Body text
}
```

### Using Theme Colors in Custom Components

The theme colors are available as CSS variables:

```css
.my-custom-element {
  background-color: var(--color-primary);
  color: var(--color-background);
}
```

Or with Tailwind's arbitrary value syntax:

```html
<div class="bg-[color:var(--color-accent)] text-[color:var(--color-foreground)]">
  Custom styled element
</div>
```

---

## 🖼️ Hero Layouts

The Hero component supports three layout modes:

### Image Right (Default)
```typescript
layoutOptions: {
  heroLayout: "image-right",
}
```
Text on the left, image on the right – great for text-focused messaging.

### Image Left
```typescript
layoutOptions: {
  heroLayout: "image-left",
}
```
Image on the left, text on the right – ideal for showcasing visuals.

### Full Width
```typescript
layoutOptions: {
  heroLayout: "full-width",
}
```
Full-bleed background image with centered text overlay – high-impact hero style.

---

## 📱 Responsive Design

All components are mobile-first and responsive:

- **Navbar**: Stacks phone number, hides "Contact Us" button on mobile
- **Hero**: Single column on mobile, side-by-side on desktop
- **ServicesGrid**: 1 column → 2 columns → 3 columns as screen grows
- **ContactForm**: Fields stack on mobile
- **Footer**: 3-column layout collapses to single column on mobile

---

## 📋 Configuration Reference

### SiteConfig Interface

```typescript
interface SiteConfig {
  businessName: string;
  theme: Theme;
  contactInfo: ContactInfo;
  heroSection: HeroSection;
  services: Service[];
  analytics: AnalyticsConfig;
  seo: SEOConfig;
  imageSearchHints?: ImageSearchHints;  // Optional
  socialLinks?: SocialLinks;            // Optional
  layoutOptions?: LayoutOptions;        // Optional
}
```

### Theme

| Property | Type | Description |
|----------|------|-------------|
| `primary` | `string` | Brand color for headings, nav, primary buttons |
| `secondary` | `string` | Section backgrounds, subtle accents |
| `accent` | `string` | CTA buttons, highlights |
| `background` | `string` | Page background color |
| `foreground` | `string` | Body text color |

### ContactInfo

| Property | Type | Description |
|----------|------|-------------|
| `phone` | `string` | Phone number (auto-linked as `tel:`) |
| `email` | `string` | Email address (auto-linked as `mailto:`) |
| `address` | `string` | Physical address |

### HeroSection

| Property | Type | Description |
|----------|------|-------------|
| `headline` | `string` | Main headline text |
| `subheadline` | `string` | Supporting text below headline |
| `imageUrl` | `string` | Local path (`/images/hero.jpg`) or external URL (`https://...`) |
| `imageAlt` | `string` | Alt text for hero image |
| `callToActionLabel` | `string` | Text for CTA button |

#### Image URL Examples

**Local image** (stored in your `public/images/` folder):
```typescript
imageUrl: "/images/hero.jpg"
```

**External URL** (recommended for quick setup):
```typescript
imageUrl: "https://images.unsplash.com/photo-1558904541-efa843a96f01?w=1200&h=800&fit=crop"
```

> 💡 **Tip:** Use Unsplash's URL parameters (`?w=1200&h=800&fit=crop`) to optimize image size and aspect ratio.

### Service

| Property | Type | Description |
|----------|------|-------------|
| `name` | `string` | Service name |
| `description` | `string` | Service description |

### SEOConfig

| Property | Type | Description |
|----------|------|-------------|
| `title` | `string` | Page title (appears in browser tab) |
| `description` | `string` | Meta description for search engines |

### AnalyticsConfig

| Property | Type | Description |
|----------|------|-------------|
| `enableTracking` | `boolean` | Enable/disable analytics |
| `mixpanelToken` | `string` | Optional Mixpanel project token |

### SocialLinks (Optional)

| Property | Type | Description |
|----------|------|-------------|
| `facebook` | `string` | Facebook page URL |
| `instagram` | `string` | Instagram profile URL |
| `twitter` | `string` | Twitter/X profile URL |
| `linkedin` | `string` | LinkedIn page URL |
| `youtube` | `string` | YouTube channel URL |
| `tiktok` | `string` | TikTok profile URL |

### LayoutOptions (Optional)

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `heroLayout` | `"image-left"` \| `"image-right"` \| `"full-width"` | `"image-right"` | Hero section layout style |
| `stickyNav` | `boolean` | `false` | Make navbar stick to top on scroll |

---

## 📁 Project Structure

```
@indirecttek/essentials-engine/
├── dist/                    # Built package (published to npm)
│   ├── components/
│   │   ├── ContactForm.astro
│   │   ├── Footer.astro
│   │   ├── Hero.astro
│   │   ├── Navbar.astro
│   │   └── ServicesGrid.astro
│   ├── layouts/
│   │   └── EssentialsLayout.astro
│   ├── index.ts             # Main exports
│   └── types.ts             # TypeScript interfaces
├── src/                     # Source files
├── package.json
└── README.md
```

---

## 🔧 Development

Clone and install:

```bash
git clone https://github.com/indirecttek/essentials-engine.git
cd essentials-engine
npm install
```

Build the package:

```bash
npm run build
```

---

## 📄 License

MIT © [IndirectTek](https://indirecttek.com)

---

## 🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

---

## 💬 Support

- **Issues**: [GitHub Issues](https://github.com/indirecttek/essentials-engine/issues)
- **Email**: support@indirecttek.com