vite-file-include 1.0.3 → 1.1.0

package/README.md

@@ -1,211 +1,228 @@
-# vite-file-include
+# vite-file-include 🔗
 
-`vite-file-include` is an advanced Vite plugin designed to facilitate the inclusion of external HTML files, looping through data, and conditional rendering within your HTML files. It is particularly useful for managing repetitive HTML structures in static sites or templating environments.
+`vite-file-include` is a modern **Vite plugin** for HTML templating that supports **file inclusion**, **looping**, **conditional rendering**, and **live hot-reload** without reloading the full page.  
+It’s ideal for managing repetitive HTML structures in static sites or prototyping environments.
 
-## Features
+---
 
-- File inclusion with support for nested includes
-- Looping through data arrays or JSON files
-- Conditional rendering 
-- Custom function support for advanced templating
-- Evaluate JavaScript expressions directly in your templates.
-- Asynchronous file processing
-- Enhanced error handling and debugging
+## 🚀 Features
 
+- 🧩 **Nested file includes** with variable support  
+- 🔁 **Loop rendering** for data arrays and JSON files  
+- ⚙️ **Conditional blocks** using inline JavaScript  
+- 🧠 **Custom helper functions** for advanced templating  
+- ⚡ **JavaScript expression evaluation** inside templates  
+- 🔄 **Hot reload support** — live updates without full page refresh  
+- 🧵 **Async file processing** and better performance  
+- 🪶 **Enhanced error reporting** with context hints
 
-## Installation
+---
 
-Install the plugin via npm:
+## 📦 Installation
 
 ```bash
-npm install vite-file-include
+npm install vite-file-include --save-dev
 ```
 
-## Configuration
+---
 
-To use the plugin, import and configure it in your `vite.config.js`:
+## ⚙️ Configuration
 
-```javascript
-import fileIncludePlugin from 'vite-file-include';
+Add the plugin to your `vite.config.js`:
 
-export default {
+```js
+import { defineConfig } from 'vite'
+import fileIncludePlugin from 'vite-file-include'
+
+export default defineConfig({
   plugins: [
     fileIncludePlugin({
       includePattern: "@@include",
       loopPattern: "@@loop",
       ifPattern: "@@if",
       baseDir: process.cwd(),
-      context: {}, 
-      customFunctions: {},
-    }),
-  ],
-};
+      context: {
+        siteName: 'My Static Site'
+      },
+      customFunctions: {
+        uppercase: (str) => str.toUpperCase(),
+        currentYear: () => new Date().getFullYear()
+      }
+    })
+  ]
+})
 ```
 
-### Plugin Options
+---
 
-- `includePattern` (default: `@@include`): The pattern used to include external HTML files.
-- `loopPattern` (default: `@@loop`): The pattern used to loop through data arrays.
-- `ifPattern` (default: `@@if`): The pattern used to conditionally render content.
-- `baseDir` (default: `process.cwd()`): The base directory for resolving paths.
-- `context` (default: `{}`): An object containing global variables that can be used in includes, loops, and conditionals.
-- `customFunctions` (default: {}): An object containing custom functions that can be used in your templates.
+## 🧩 Plugin Options
 
-## Directives
+| Option | Type | Default | Description |
+|--------|------|----------|-------------|
+| **`includePattern`** | `string` | `@@include` | Directive for including files |
+| **`loopPattern`** | `string` | `@@loop` | Directive for looping over arrays/JSON |
+| **`ifPattern`** | `string` | `@@if` | Directive for conditional rendering |
+| **`baseDir`** | `string` | `process.cwd()` | Base directory for resolving paths |
+| **`context`** | `object` | `{}` | Global variables accessible in templates |
+| **`customFunctions`** | `object` | `{}` | Custom functions available in templates |
 
-### `@@include`
+---
 
-The `@@include` directive allows you to include the content of another HTML file within your main file.
+## 🧱 Directives
 
-**Syntax:**
+### 🔹 `@@include`
+
+Include another HTML file into your main file.
 
 ```html
-@@include('path/to/file.html');
+@@include('partials/header.html')
 ```
 
-**With Data:**
+With data:
 
 ```html
-@@include('path/to/file.html', { "key": "value" });
+@@include('partials/header.html', { "title": "Home Page" })
 ```
 
-**Example** (`file.html`):
+**Example** (`partials/header.html`):
 
 ```html
-<div>{{ key }}</div>
+<header>
+  <h1>{{ title }}</h1>
+</header>
 ```
 
-### `@@loop`
+---
 
-The `@@loop` directive enables you to repeat a block of HTML for each item in a data array or JSON file.
+### 🔹 `@@loop`
 
-**Syntax:**
+Repeat an HTML block for each item in a data array or JSON file.
 
 ```html
-@@loop('path/to/template.html', 'data.json');
+@@loop('partials/article.html', 'data/articles.json')
 ```
 
-**With Inline Data:**
+Or inline data:
 
 ```html
-@@loop('path/to/template.html', [{ "key": "value" }, { "key": "another value" }]);
+@@loop('partials/article.html', [
+  { "title": "Article 1" },
+  { "title": "Article 2" }
+])
 ```
 
-**Example Template** (`template.html`):
+**Example** (`partials/article.html`):
 
 ```html
 <article>
-  <h2>{{ key }}</h2>
+  <h2>{{ title }}</h2>
 </article>
 ```
 
-### `@@if`
+---
 
-The `@@if` directive allows conditional rendering based on an expression.
+### 🔹 `@@if`
 
-**Syntax:**
+Conditionally render content based on an expression.
 
 ```html
-@@if(condition) {
-  <!-- HTML content -->
-}
+@@if(showFooter) {
+  @@include('partials/footer.html')
+};
 ```
 
 **Example:**
 
 ```html
-@@if(name === 'John') {
-  <p>Welcome, John!</p>
-}
+@@if(user.isLoggedIn) {
+  <p>Welcome, {{ user.name }}</p>
+};
 ```
 
-## Custom Functions
-
-You can define custom functions to use in your templates. These functions are passed to the plugin through the `customFunctions` option:
+---
 
-```javascript
-fileIncludePlugin({
-  customFunctions: {
-    uppercase: (str) => str.toUpperCase(),
-    currentYear: () => new Date().getFullYear()
-  }
-})
-```
+## 🧮 JavaScript Expressions
 
-You can then use these functions in your templates:
+Use JS directly inside templates:
 
 ```html
-<p>{{ uppercase(name) }}</p>
-<footer>&copy; {{ currentYear() }}</footer>
+<p>Year: {{ new Date().getFullYear() }}</p>
+<p>Uppercase: {{ 'vite'.toUpperCase() }}</p>
 ```
 
+---
 
-## JavaScript Expressions
+## 🧰 Custom Functions
 
-You can use JavaScript expressions directly in your templates. For example:
+Define reusable helpers in your config:
 
-```html 
-<p>Current Year: {{ new Date().getFullYear() }}</p>
-<p>Uppercase Text: {{ 'John'.toUpperCase() }}</p>
+```js
+customFunctions: {
+  uppercase: (str) => str.toUpperCase(),
+  currentYear: () => new Date().getFullYear(),
+}
 ```
 
-## Example Usage
-
-Below is an example of how you might structure your HTML files using the plugin's directives:
+Usage:
 
 ```html
-<!-- main.html -->
-<html>
-<body>
-  @@include('header.html', { "title": "My Website" });
+<h1>{{ uppercase(title) }}</h1>
+<footer>&copy; {{ currentYear() }}</footer>
+```
 
-  @@loop('partials/article.html', 'data/articles.json');
+---
 
-  @@if(showFooter) {
-    @@include('footer.html');
-  }
-</body>
-</html>
-```
+## 🔄 Hot Reload
 
-### Example Files
+Unlike static include tools, `vite-file-include` supports **Vite’s HMR (Hot Module Replacement)**.
 
-- `header.html`:
+- Changes to included files update **instantly** in the browser  
+- No full page reload  
+- Works seamlessly with Vite’s dev server  
 
-```html
-<header>
-  <h1>{{ uppercase(title) }}</h1>
-</header>
+💡 Tip: Useful for quickly editing partials like headers, footers, and repeating components.
+
+---
+
+## 🧰 Example Project Structure
+
+```
+project/
+├─ index.html
+├─ partials/
+│  ├─ header.html
+│  ├─ footer.html
+│  └─ article.html
+├─ data/
+│  └─ articles.json
+└─ vite.config.js
 ```
 
-- `partials/article.html`:
+**index.html**
 
 ```html
-<article>
-  <h2>{{ title }}</h2>
-  <p>{{ content }}</p>
-</article>
+<html>
+  <body>
+    @@include('partials/header.html', { "title": "My Site" })
+    @@loop('partials/article.html', 'data/articles.json')
+    @@if(showFooter) { @@include('partials/footer.html') };
+  </body>
+</html>
 ```
 
-- `data/articles.json`:
+---
 
-```json
-[
-  {
-    "title": "Article 1",
-    "content": "Content of the first article."
-  },
-  {
-    "title": "Article 2",
-    "content": "Content of the second article."
-  }
-]
-```
+## ⚠️ Error Handling
+
+The plugin provides detailed error messages for:
+- Missing include files  
+- Invalid JSON syntax  
+- Undefined variables  
 
-## Error Handling
+Each error logs file path and directive line for easier debugging.
 
-If there is an error parsing JSON data or including a file, the plugin will log a detailed error message to the console. This helps in debugging while ensuring that your build process continues without interruption.
+---
 
-## License
+## 📄 License
 
-This project is licensed under the MIT License. See the LICENSE file for more details.
+MIT © 2025

package/package.json

@@ -1,30 +1,29 @@
-{
-  "name": "vite-file-include",
-  "version": "1.0.3",
-  "description": "A Vite plugin for file inclusion, loops, and conditionals in HTML files",
-  "main": "src/index.js",
-  "type": "module",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [
-    "vite",
-    "plugin",
-    "file-include",
-    "html"
-  ],
-  "author": "Ahmed Abdulgid",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/abdulgidcoder/vite-file-includ.git"
-  },
-  "peerDependencies": {
-    "vite": "^4.0.0"
-  },
-  "dependencies": {
-    "fs": "0.0.1-security",
-    "path": "^0.12.7",
-    "vite-file-include": "^1.0.2"
-  }
-}
+{
+  "name": "vite-file-include",
+  "version": "1.1.0",
+  "description": "A Vite plugin for file inclusion, loops, and conditionals in HTML files",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "vite",
+    "plugin",
+    "file-include",
+    "html"
+  ],
+  "author": "Ahmed Abdulgid",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdulgidcoder/vite-file-include.git"
+  },
+  "peerDependencies": {
+    "vite": "^4.0.0"
+  },
+  "dependencies": {
+    "fs": "0.0.1-security",
+    "path": "^0.12.7"
+  }
+}

package/src/index.js

@@ -11,6 +11,16 @@ function fileIncludePlugin(options = {}) {
     customFunctions = {},
   } = options;
 
+  // Cache for file reads
+  const fileCache = new Map();
+
+  const readFileCached = (filePath) => {
+    if (!fileCache.has(filePath)) {
+      fileCache.set(filePath, fs.readFileSync(filePath, "utf-8"));
+    }
+    return fileCache.get(filePath);
+  };
+
   return {
     name: "vite-plugin-file-include",
 
@@ -22,35 +32,64 @@ function fileIncludePlugin(options = {}) {
         loopPattern,
         ifPattern,
         context,
-        customFunctions
+        customFunctions,
+        new Set(),
+        readFileCached
       );
     },
 
     transform(code, id) {
       if (id.endsWith(".html")) {
-        return processIncludes(
-          code,
-          path.dirname(id),
-          includePattern,
-          loopPattern,
-          ifPattern,
-          context,
-          customFunctions
-        );
+        return {
+          code: processIncludes(
+            code,
+            baseDir,
+            includePattern,
+            loopPattern,
+            ifPattern,
+            context,
+            customFunctions,
+            new Set(),
+            readFileCached
+          ),
+        };
       }
-      return code;
+      return { code };
     },
 
-    handleHotUpdate({ file, server }) {
+    handleHotUpdate({ file, server, modules }) {
       if (file.endsWith(".html")) {
-        server.ws.send({
-          type: "full-reload",
-        });
+        const mod = modules.find((m) => m.file && m.file.endsWith(".html"));
+
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          server.ws.send({
+            type: "update",
+            updates: [
+              {
+                type: "js-update",
+                path: mod.url,
+                acceptedPath: mod.url,
+                timestamp: Date.now(),
+              },
+            ],
+          });
+        } else {
+          server.ws.send({
+            type: "custom",
+            event: "vite-file-include:update",
+            data: { file },
+          });
+        }
+
+        return [];
       }
     },
   };
 }
 
+/* ---------------- Core Processing ---------------- */
+
 function processIncludes(
   content,
   dir,
@@ -58,27 +97,47 @@ function processIncludes(
   loopPattern,
   ifPattern,
   context,
-  customFunctions
+  customFunctions,
+  visited,
+  readFileCached
 ) {
-  content = processIncludesWithPattern(
-    content,
-    dir,
-    includePattern,
-    loopPattern,
-    ifPattern,
-    context,
-    customFunctions
-  );
-  content = processLoops(content, dir, loopPattern, context, customFunctions);
-  content = processConditionals(
-    content,
-    dir,
-    ifPattern,
-    includePattern,
-    loopPattern,
-    context,
-    customFunctions
-  );
+  let lastContent;
+  do {
+    lastContent = content;
+    content = processIncludesWithPattern(
+      content,
+      dir,
+      includePattern,
+      loopPattern,
+      ifPattern,
+      context,
+      customFunctions,
+      visited,
+      readFileCached
+    );
+    content = processLoops(
+      content,
+      dir,
+      loopPattern,
+      context,
+      customFunctions,
+      includePattern,
+      ifPattern,
+      visited,
+      readFileCached
+    );
+    content = processConditionals(
+      content,
+      dir,
+      ifPattern,
+      includePattern,
+      loopPattern,
+      context,
+      customFunctions,
+      visited,
+      readFileCached
+    );
+  } while (content !== lastContent);
 
   return content;
 }
@@ -90,27 +149,34 @@ function processIncludesWithPattern(
   loopPattern,
   ifPattern,
   context,
-  customFunctions
+  customFunctions,
+  visited,
+  readFileCached
 ) {
   const regex = new RegExp(
-    `${includePattern}\\(\\s*['"](.+?)['"]\\s*,?\\s*({[\\s\\S]*?})?\\s*\\);`,
+    `${includePattern}\\(\\s*['"]([^'"]+)['"]\\s*(?:,\\s*({[\\s\\S]*?}))?\\s*\\)\\s*;?`,
     "g"
   );
 
   return content.replace(regex, (match, filePath, jsonData) => {
     const includePath = path.resolve(dir, filePath);
-    let data = {};
+    if (visited.has(includePath)) {
+      console.warn(`⚠️ Circular include detected: ${includePath}`);
+      return "";
+    }
+    visited.add(includePath);
 
+    let data = {};
     if (jsonData) {
       try {
         data = JSON.parse(jsonData);
-      } catch (error) {
+      } catch {
         console.error(`Failed to parse JSON data: ${jsonData}`);
       }
     }
 
     try {
-      let includedContent = fs.readFileSync(includePath, "utf-8");
+      let includedContent = readFileCached(includePath);
       includedContent = injectData(
         includedContent,
         { ...context, ...data },
@@ -122,19 +188,31 @@ function processIncludesWithPattern(
         includePattern,
         loopPattern,
         ifPattern,
-        context,
-        customFunctions
+        { ...context, ...data },
+        customFunctions,
+        visited,
+        readFileCached
       );
-    } catch (error) {
+    } catch (err) {
       console.error(`Failed to include file: ${includePath}`);
       return "";
     }
   });
 }
 
-function processLoops(content, dir, loopPattern, context, customFunctions) {
+function processLoops(
+  content,
+  dir,
+  loopPattern,
+  context,
+  customFunctions,
+  includePattern,
+  ifPattern,
+  visited,
+  readFileCached
+) {
   const regex = new RegExp(
-    `${loopPattern}\\(\\s*['"](.+?)['"]\\s*,\\s*(\\[[\\s\\S]*?\\]|['"](.+?)['"])\\s*\\);`,
+    `${loopPattern}\\(\\s*['"]([^'"]+)['"]\\s*,\\s*(\\[[\\s\\S]*?\\]|['"][^'"]+['"])\\s*\\)\\s*;?`,
     "g"
   );
 
@@ -143,31 +221,46 @@ function processLoops(content, dir, loopPattern, context, customFunctions) {
     let dataArray = [];
 
     try {
-      if (
-        jsonArrayOrFilePath.startsWith("[") ||
-        jsonArrayOrFilePath.startsWith("{")
-      ) {
+      if (jsonArrayOrFilePath.trim().startsWith("[")) {
         dataArray = JSON.parse(jsonArrayOrFilePath);
       } else {
         const jsonFilePath = path.resolve(
           dir,
           jsonArrayOrFilePath.replace(/['"]/g, "")
         );
-        const jsonData = fs.readFileSync(jsonFilePath, "utf-8");
+        const jsonData = readFileCached(jsonFilePath);
         dataArray = JSON.parse(jsonData);
       }
     } catch (error) {
-      console.error(`Failed to parse JSON: ${jsonArrayOrFilePath}`);
-      console.error(error);
+      console.error(`Failed to parse loop JSON: ${jsonArrayOrFilePath}`);
+      return "";
     }
 
     try {
-      let loopTemplate = fs.readFileSync(loopPath, "utf-8");
+      let loopTemplate = readFileCached(loopPath);
       return dataArray
-        .map((data) => injectData(loopTemplate, data, customFunctions))
+        .map((data) => {
+          const mergedContext = { ...context, ...data };
+          const loopContent = injectData(
+            loopTemplate,
+            mergedContext,
+            customFunctions
+          );
+          return processIncludes(
+            loopContent,
+            dir,
+            includePattern,
+            loopPattern,
+            ifPattern,
+            mergedContext,
+            customFunctions,
+            visited,
+            readFileCached
+          );
+        })
         .join("");
     } catch (error) {
-      console.error(`Failed to include file: ${loopPath}`);
+      console.error(`Failed to include loop file: ${loopPath}`);
       return "";
     }
   });
@@ -180,10 +273,12 @@ function processConditionals(
   includePattern,
   loopPattern,
   context,
-  customFunctions
+  customFunctions,
+  visited,
+  readFileCached
 ) {
   const regex = new RegExp(
-    `${ifPattern}\\s*\\(([^)]+)\\)\\s*{([\\s\\S]*?)};\\s*`,
+    `${ifPattern}\\s*\\(([^)]+)\\)\\s*{([\\s\\S]*?)};?`,
     "g"
   );
 
@@ -192,21 +287,45 @@ function processConditionals(
       const result = evaluateCondition(condition, context, customFunctions);
 
       if (result) {
-        return processIncludesWithPattern(
+        let processed = processIncludesWithPattern(
           body.trim(),
           dir,
           includePattern,
           loopPattern,
           ifPattern,
           context,
-          customFunctions
+          customFunctions,
+          visited,
+          readFileCached
+        );
+        processed = processLoops(
+          processed,
+          dir,
+          loopPattern,
+          context,
+          customFunctions,
+          includePattern,
+          ifPattern,
+          visited,
+          readFileCached
+        );
+        processed = processConditionals(
+          processed,
+          dir,
+          ifPattern,
+          includePattern,
+          loopPattern,
+          context,
+          customFunctions,
+          visited,
+          readFileCached
         );
+        return processed;
       }
 
       return "";
     } catch (error) {
       console.error(`Failed to evaluate condition: ${condition}`);
-      console.error(error);
       return "";
     }
   });
@@ -217,30 +336,22 @@ function injectData(content, data, customFunctions = {}) {
     try {
       const result = evaluateExpression(expression, data, customFunctions);
       return result !== undefined ? result : match;
-    } catch (error) {
-      console.error(`Failed to evaluate expression: ${expression}`);
-      console.error(error);
+    } catch {
       return match;
     }
   });
 }
 
 function evaluateExpression(expression, data, customFunctions) {
-  // Bind custom functions to the evaluation context
   const context = { ...data, ...customFunctions };
-  return new Function(
-    "context",
-    "with (context) { return " + expression + "; }"
-  )(context);
+  return new Function("context", `with (context) { return ${expression}; }`)(
+    context
+  );
 }
 
 function evaluateCondition(condition, context, customFunctions) {
-  // Bind custom functions to the evaluation context
-  const contextWithFunctions = { ...context, ...customFunctions };
-  return new Function(
-    "context",
-    "with (context) { return " + condition + "; }"
-  )(contextWithFunctions);
+  const ctx = { ...context, ...customFunctions };
+  return new Function("context", `with (context) { return ${condition}; }`)(ctx);
 }
 
 export default fileIncludePlugin;