electron-quick-ejs

v1.0.2

Published

a month ago

A modern, secure, and zero-configuration EJS renderer for Electron.

0High
0Medium
0Low

chetanguptaofficial

electron ejs template renderer secure

🚀 electron-quick-ejs

A modern, secure, and zero-configuration EJS Renderer for Electron applications. Built for Electron 40+ and EJS v4, utilizing native protocol.handle for maximum performance and security.

Why use this? Unlike older libraries, this uses Electron's native Custom Protocols (app://) instead of insecure file access or remote modules. It also includes Smart Path Repair to automatically fix broken asset links.

✨ Features

🔒 Secure: Uses native protocol.handle with Path Traversal Protection (prevents access outside views folder).
⚡ Fast: Built-in caching headers for static assets (CSS/Images/JS).
🧠 Smart Path Resolution: Automatically fixes common browser URL issues (e.g., resolving index/assets/style.css).
📂 Asset Support: Seamlessly loads .css, .png, .js, .svg, and more.
🛠 TypeScript Ready: Includes type definitions (index.d.ts) out of the box.

📦 Installation

npm install electron-quick-ejs

🚀 Quick Start

1. Setup in `main.js` (Main Process)

const { app, BrowserWindow } = require('electron');
const path = require('path');
const ElectronQuickEjs = require('electron-quick-ejs');

// 1. Initialize the renderer
const ejs = new ElectronQuickEjs({
  // Point to your views folder (Required)
  viewsDir: path.join(__dirname, 'views'), 
  
  // (Optional) Global data accessible in all templates
  data: { 
    appName: 'My Awesome App',
    year: 2026
  }
});

let mainWindow;

app.whenReady().then(() => {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      nodeIntegration: true, 
      contextIsolation: false
    }
  });

  // 2. Load your file using the 'app://' protocol
  // No need for .ejs extension. 'index' maps to 'views/index.ejs'
  mainWindow.loadURL('app://index');
});

2. Create `views/index.ejs` (Frontend)

⚠️ Important: Always use absolute paths (starting with /) for your assets to ensure they load correctly.

<!DOCTYPE html>
<html>
<head>
    <title><%= appName %></title>
    <link rel="stylesheet" href="/assets/style.css">
</head>
<body style="background-color: #1a1a1a; color: white;">

    <h1>Welcome to <%= appName %></h1>
    <p>Current Year: <%= year %></p>
    
    <img src="/assets/logo.png" alt="Logo" width="150">

    <script src="/assets/script.js"></script>
</body>
</html>

📂 Recommended Folder Structure

To ensure the security logic works correctly, keep all your assets inside the views directory.

my-electron-app/
├── main.js
├── package.json
└── views/              <-- Pass this path to 'viewsDir'
    ├── index.ejs
    ├── about.ejs
    └── assets/         <-- Keep CSS/Images here
        ├── style.css
        ├── script.js
        └── logo.png

📝 API Options

`new ElectronQuickEjs(options)`

| Option | Type | Required | Description | | --- | --- | --- | --- | | viewsDir | string | Yes | Absolute path to your EJS templates folder. | | data | object | No | Global variables available in all templates (e.g. App Name). |

🛡️ Security & Performance

Sandboxing: The renderer prevents access to files outside your viewsDir. E.g., app://../../password.txt will return Access Denied.
Caching: EJS templates are always re-rendered (no-cache) for hot-reloading data, while static assets (images, css) are cached for 1 year for production-level performance.

🤝 License

MIT License. Free for commercial and personal use.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme