🚀 hbh-deve

A flexible SSR view engine and dynamic file-based route loader for Express.js.
Supports .pug, .html, .md, and .js views — with live reload, layouts, and developer-friendly DX.

---

✨ Features

• 📁 File-based routing — Auto-maps views/pages/ structure to Express routes
• 🧠 Multi-format views — Render .pug, .html, .md, and .js as SSR templates
• 🔁 Live reload — Watches files and reloads connected browsers on changes
• 🧩 Layouts — Optional layout.pug support with layout toggling per-view
• 📦 Frontmatter — In Markdown and .js views for metadata
• 🛠️ Middleware support — Per-view Express middleware via .js exports
• 🔧 Configurable — Customizable via hbh-deve.config.js or use same defaults
• 🧪 Error overlays — In-browser overlays for SSR/runtime errors

---

📦 Installation

          
            1npm install hbh-deve2# or3yarn add hbh-deve
          
        

---

🗂️ Project Structure

          
            1project-root/2├── views/3│   ├── layout.pug            # Optional shared layout4│   └── pages/                # Route-driven views5│       ├── index.pug         # route: /6│       ├── about.html        # route: /about7│       ├── blog/8│       │   └── [slug].md     # dynamic: /blog/:slug9│       └── user/[id].js      # dynamic: /user/:id10├── hbh-deve.config.js        # Optional custom config11└── index.js                  # App entry
          
        

---

⚙️ Configuration (Optional)

          
            1// hbh-deve.config.js2import path from 'path';4const __dirname = process.cwd();5const ViewBase = path.join(__dirname, 'views');7export const directories = {8  __dirname,9  ViewBase,10  PagesBase: path.join(ViewBase, 'pages'),11  Layout: path.join(ViewBase, 'layout.pug')12};
          
        

---

🚀 Quick Start

1. Create Express app

          
            1import express from 'express';2import { Attach } from 'hbh-deve';4const app = express();6await Attach(app); // Loads all views + routes automatically8app.listen(3000, () => {9  console.log('✅ Running at http://localhost:3000');10});
          
        

2. Add views

✅ views/pages/index.pug

          
            1h1 Welcome to my app!2p Current time: {{ new Date().toLocaleTimeString() }}
          
        

✅ views/pages/blog/[slug].md

          
            1---2title: My Blog Post3nolayout: false4---6# Hello {{ params.slug }}8This is a markdown page.
          
        

✅ views/pages/user/[id].js

          
            1export default async ({ params }) => {2  return {3    title: `User: ${params.id}`,4    html: `<p>Hello, <strong>${params.id}</strong></p>`5  };6};8export const middlewares = [9  (req, res, next) => {10    console.log('👋 User route hit');11    next();12  }13];
          
        

---

🔹 Layouts

Supports optional layouts (layout.pug) with automatic injection of default content and live reload. The behavior adapts based on what the user layout already contains.

---

1️⃣ Default Layout Injection

Given a layout like:

          
            1doctype html2html3  head4    title My App5  body6    h1 Header from layout
          
        

The engine automatically injects:

• Live reload script (always)
• Default content block if .page!= page is missing
• Default scripts block if .scripts!= scripts is missing

Rendered final Pug:

          
            1doctype html2html3  head4    title My App5  body6    h1 Header from layout8    // ✅ Injected automatically:9    script.10      const es = new EventSource('/__reload');11      es.onmessage = (e) => {12        if (e.data === 'reload') location.reload();13      };15    if page16      .page!= page18    if scripts19      .scripts!= scripts
          
        

User-defined blocks are respected — duplicates are never injected.

---

2️⃣ Per-View Layout Toggle

You can disable the layout per view if needed:

---

3️⃣ Injection Flow

          
            1        ┌─────────────────────┐2        │ Load user layout.pug │3        └─────────┬───────────┘4                  │5                  ▼6       ┌───────────────────┐7       │ Strip comments     │8       └─────────┬─────────┘9                 │10                 ▼11   ┌─────────────────────────────┐12   │ Build injection string       │13   │ (force reload + default      │14   │ content/scripts if missing)  │15   └─────────┬───────────┬───────┘16             │           │17             │           ▼18             │     ┌───────────────┐19             │     │ Inject into   │20             │     │ <body> tag    │21             │     │ maintain      │22             │     │ indentation   │23             │     └─────┬─────────┘24             ▼           │25   ┌─────────────────────────────┐26   │ Compile final Pug            │27   │ Render with locals           │28   └─────────────────────────────┘
          
        

---

4️⃣ Fallback

If layout.pug does not exist:

• A default layout with all blocks and live reload is used.
• Ensures the page always renders without breaking.

---

5️⃣ Example Usage in a Pug Page

views/pages/index.pug:

          
            1h1 Welcome2p Current time: {{ new Date().toLocaleTimeString() }}
          
        

Behavior:

• If layout.pug exists:

  • h1 Welcome remains intact
  • .page!= page is injected if missing
  • Live reload script is added automatically

• If layout.pug is missing:

  • Page is rendered with the default layout
  • .page!= page and live reload script are included automatically

6️⃣ Automatic Injection Overview

✅ This table helps you quickly see what the engine automatically injects versus what it preserves.

---

🧠 Supported View Types

---

🧩 Routing Patterns

---

🔄 Live Reload

• Automatically watches views/ and reloads browser
• Injects <script> tag automatically in rendered pages
• No browser extension required
• Works with .pug, .html, .md, and .js views

---

🧪 Template Interpolation

You can use {{ variable }} inside .html, .pug, and .md.

          
            1<h1>Hello, {{ query.name }}</h1>2<p>Time: {{ new Date().toLocaleTimeString() }}</p>
          
        

Certain blocks like <script> and comments are excluded from interpolation for safety.

---

❌ Error Overlay

When rendering fails (in dev), a browser overlay will appear:

          
            1⚠️ SSR Rendering Error3File: /views/pages/user/[id].js5Error: Unexpected token export
          
        

---

📄 Disabling Layout

Layout is applied automatically, but you can disable it per view:

---

📚 API Reference

Attach(app: Express, options?)

• Loads routes from views/pages/
• Applies view rendering engine
• Enables live reload via SSE
• Supports optional config overrides

---

📦 Scripts

Add this in your package.json:

          
            1"scripts": {2  "dev": "node index.js"3}
          
        

Then run:

          
            1npm run dev
          
        

---

🔐 Security Notes

• Sandboxed parser for .html and .md
• Blocks unsafe expressions like eval, Function, window, etc.

---

📝 License

ISC

---

✍️ Author

HBH Made with ❤️ for Express.js developers