@indirecttek/essentials-engine

v1.4.0

Published

4 months ago

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.

0High
0Medium
0Low

elixium

bereizy

astro astro-component tailwindcss marketing white-label component-library

@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.

✨ 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

npm install @indirecttek/essentials-engine

Peer Dependencies

Ensure your project has Astro and Tailwind CSS installed:

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):

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: "[email protected]",
    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):

---
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

---
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:

---
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.

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:

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

Or with Tailwind's arbitrary value syntax:

<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)

layoutOptions: {
  heroLayout: "image-right",
}

Text on the left, image on the right – great for text-focused messaging.

Image Left

layoutOptions: {
  heroLayout: "image-left",
}

Image on the left, text on the right – ideal for showcasing visuals.

Full Width

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

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):

imageUrl: "/images/hero.jpg"

External URL (recommended for quick setup):

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:

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

Build the package:

npm run build

📄 License

🤝 Contributing

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

💬 Support

Issues: GitHub Issues
Email: [email protected]

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@indirecttek/essentials-engine

✨ Features

📦 Installation

Peer Dependencies

🚀 Quick Start

1. Create Your Site Configuration

2. Use the Layout in Your Page

🧩 Components

Full-Page Layout

Individual Components

Component Reference

🎨 Theming

Using Theme Colors in Custom Components

🖼️ Hero Layouts

Image Right (Default)

Image Left

Full Width

📱 Responsive Design

📋 Configuration Reference

SiteConfig Interface

Theme

ContactInfo

HeroSection

Image URL Examples

Service

SEOConfig

AnalyticsConfig

SocialLinks (Optional)

LayoutOptions (Optional)

📁 Project Structure

🔧 Development

📄 License

🤝 Contributing

💬 Support