miki-template 2.0.1 → 2.2.2

package/docs/guide/template-discovery.md

@@ -0,0 +1,170 @@
+# Smart Template Discovery
+
+miki-template includes a Django-inspired template finder that searches your project structure intelligently. You no longer need to manually configure every views directory or worry about `Failed to lookup view` errors when templates live in nested app folders.
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Supported Layouts](#supported-layouts)
+- [Express Integration](#express-integration)
+- [Custom Template Directory Names](#custom-template-directory-names)
+- [Manual Lookup](#manual-lookup)
+- [ESM Import](#esm-import)
+- [Next Steps](#next-steps)
+
+---
+
+## How It Works
+
+When you call `res.render('name')` or `render('name', ctx, { views })`, miki-template:
+
+1. Resolves the view name against the configured views directories.
+2. Searches recursively through subdirectories for matching files.
+3. Recognizes app-style `templates/` directories automatically.
+4. Supports custom directory names via `setAppTemplateDirNames()`.
+
+The search order is:
+
+1. **Direct resolution** — if you pass `nested/path`, it resolves relative to each views root.
+2. **Recursive search** — if you pass a bare name like `home`, the engine walks subdirectories searching for `home.html` or `home.miki`.
+3. **App-style directories** — directories named `templates` (or whatever you configure) are treated as additional view roots at any depth.
+
+## Supported Layouts
+
+```text
+project/
+├── views/
+│   └── home.html
+├── app/
+│   └── templates/
+│       └── dashboard.html
+├── packages/
+│   └── admin/
+│       └── templates/
+│           └── settings.html
+```
+
+All of these are discoverable without extra configuration.
+
+## Express Integration
+
+When you use `setupExpress()`, the engine automatically expands your views roots to include all directories that contain template files:
+
+=== "CommonJS"
+
+    ```javascript
+    const express = require('express');
+    const miki = require('miki-template');
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    // Templates placed deeply in your project are found automatically:
+    app.get('/', (req, res) => res.render('home'));
+    app.get('/admin', (req, res) => res.render('settings'));
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import express from 'express';
+    import miki from 'miki-template';
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    app.get('/', (req, res) => res.render('home'));
+    app.get('/admin', (req, res) => res.render('settings'));
+    ```
+
+You can also pass multiple roots:
+
+```javascript
+miki.setupExpress(app, {
+  extension: 'html',
+  views: ['./views', './app/templates', './packages/*/templates']
+});
+```
+
+## Custom Template Directory Names
+
+If your project uses a different convention than `templates`, configure it globally:
+
+=== "CommonJS"
+
+    ```javascript
+    const { setAppTemplateDirNames } = require('miki-template');
+
+    setAppTemplateDirNames(['templates', 'views', 'pages']);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { setAppTemplateDirNames } from 'miki-template';
+
+    setAppTemplateDirNames(['templates', 'views', 'pages']);
+    ```
+
+This affects both Express integration and manual `render()` / `findTemplateInViews()` calls.
+
+## Manual Lookup
+
+You can use the finder directly:
+
+=== "CommonJS"
+
+    ```javascript
+    const { findTemplateInViews } = require('miki-template');
+
+    const found = findTemplateInViews('home', [
+      './views',
+      './app/templates'
+    ]);
+
+    console.log(found);
+    // Output: /absolute/path/to/home.html
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { findTemplateInViews } from 'miki-template';
+
+    const found = findTemplateInViews('home', [
+      './views',
+      './app/templates'
+    ]);
+
+    console.log(found);
+    // Output: /absolute/path/to/home.html
+    ```
+
+### Finder Behavior
+
+- Searches recursively through subdirectories for bare template names.
+- Tries `.html` and `.miki` extensions when no extension is provided.
+- Also searches app-style `templates/` directories nested inside the views root.
+- Returns the first match found, or `null` if not found.
+
+### ESM Import
+
+=== "ES Modules"
+
+    ```javascript
+    import { findTemplateInViews, setAppTemplateDirNames } from 'miki-template';
+
+    // Set custom directory names
+    setAppTemplateDirNames(['templates', 'app_templates']);
+
+    // Find a template
+    const path = findTemplateInViews('detail', ['./views', './packages']);
+    console.log(path);
+    // → /absolute/path/to/packages/product/templates/detail.html
+    ```
+
+## Next Steps
+
+- [Partial Templates](./partial-templates)
+- [Template Inheritance](./template-inheritance)
+- [Integrations: Express](../integrations/express)

package/docs/guide/template-inheritance.md

@@ -0,0 +1,273 @@
+# Template Inheritance
+
+miki-template supports Django-style template inheritance via `{% extends %}` and `{% block %}`. This lets you build layout hierarchies where child templates override parent blocks.
+
+## Table of Contents
+
+- [Basic Inheritance](#basic-inheritance)
+- [block.super](#blocksuper)
+- [Multi-Level Inheritance](#multi-level-inheritance)
+- [Rendering a Single Block](#rendering-a-single-block)
+- [block Default Behavior](#block-default-behavior)
+- [Path Traversal Protection](#path-traversal-protection)
+- [Smart Template Discovery for Inheritance](#smart-template-discovery-for-inheritance)
+
+---
+
+## Basic Inheritance
+
+### base.html
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>{% block title %}Default Title{% endblock %}</title>
+</head>
+<body>
+  <header>{% block header %}Default Header{% endblock %}</header>
+  <main>{% block content %}Default Content{% endblock %}</main>
+  <footer>{% block footer %}Default Footer{% endblock %}</footer>
+</body>
+</html>
+```
+
+### child.html
+
+```html
+{% extends "base.html" %}
+
+{% block title %}My Page{% endblock %}
+
+{% block content %}
+  <h1>Hello, {{ user.name }}!</h1>
+  {% for item in items %}
+    <p>{{ item }}</p>
+  {% endfor %}
+{% endblock %}
+```
+
+**Key behaviors:**
+
+- The child template's text outside `{% block %}` tags is **ignored** — only the blocks are used to override the parent.
+- Any blocks not overridden in the child use the parent's default content.
+- The parent is located using the `views` option (or Express's `views` directory).
+
+## block.super
+
+Inside a block, `{{ block.super }}` renders the parent template's version of that block. This is useful for augmentation rather than replacement.
+
+=== "Example"
+
+    ```html
+    {% extends "base.html" %}
+
+    {% block content %}
+      <h1>My Content</h1>
+      {{ block.super }}
+    {% endblock %}
+    ```
+
+If `base.html`'s content block is `<p>Original</p>`, the output is:
+
+```html
+<h1>My Content</h1>
+<p>Original</p>
+```
+
+**Real-world sidebar that adds to the parent:**
+
+```html
+<!-- base.html -->
+{% block sidebar %}
+  <ul class="nav">
+    <li><a href="/">Home</a></li>
+  </ul>
+{% endblock %}
+
+<!-- admin.html -->
+{% extends "base.html" %}
+{% block sidebar %}
+  {{ block.super }}
+  <li><a href="/admin">Admin Panel</a></li>
+{% endblock %}
+```
+
+## Multi-Level Inheritance
+
+Inheritance chains can be arbitrarily deep:
+
+```text
+base.html
+  └── child.html
+        └── grandchild.html
+```
+
+Each level can override blocks from its parent, and `{{ block.super }}` traverses the chain correctly.
+
+### Three-level example
+
+**base.html:**
+
+```html
+<html>
+<body>
+  {% block content %}Base content{% endblock %}
+</body>
+</html>
+```
+
+**child.html:**
+
+```html
+{% extends "base.html" %}
+
+{% block content %}
+  <h2>Child content</h2>
+  {{ block.super }}
+{% endblock %}
+```
+
+**grandchild.html:**
+
+```html
+{% extends "child.html" %}
+
+{% block content %}
+  <h1>Grandchild content</h1>
+  {{ block.super }}
+{% endblock %}
+```
+
+Rendering `grandchild.html` produces:
+
+```html
+<html>
+<body>
+  <h1>Grandchild content</h1>
+  <h2>Child content</h2>
+  Base content
+</body>
+</html>
+```
+
+## Rendering a Single Block
+
+Compile a template and render only one block — useful for AJAX or HTMX responses where you only need a portion of the page:
+
+=== "CommonJS"
+
+    ```javascript
+    const { compile } = require('miki-template');
+
+    const compiled = compile(childTemplateStr, { views: './templates' });
+    const partialHtml = compiled.renderBlock('content', context);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import { compile } from 'miki-template';
+
+    const compiled = compile(childTemplateStr, { views: './templates' });
+    const partialHtml = compiled.renderBlock('content', context);
+    ```
+
+### renderBlock behavior
+
+- If the block is not found, throws `Block 'blockName' not found in template`.
+- If the block has no overrides, renders the default body.
+- If the block has overrides, renders the child-most block first, then traverses up for `{{ block.super }}`.
+
+**Real-world HTMX use case:**
+
+```html
+<!-- layout.html -->
+{% block main %}
+  <div id="main-content">
+    <!-- default content -->
+  </div>
+{% endblock %}
+```
+
+```javascript
+// Return only the main block for an AJAX update
+app.get('/ajax/content', (req, res) => {
+  const compiled = miki.compile(template, { views: './views' });
+  res.send(compiled.renderBlock('main', { user: req.user }));
+});
+```
+
+## block Default Behavior
+
+If a child template does not override a block, the parent's default content is rendered:
+
+```html
+<!-- base.html -->
+<html>
+<body>
+  {% block sidebar %}Default sidebar{% endblock %}
+</body>
+</html>
+```
+
+```html
+<!-- child.html -->
+{% extends "base.html" %}
+
+{% block content %}Main content{% endblock %}
+<!-- sidebar block is not overridden, so "Default sidebar" is used -->
+```
+
+## Dynamic extends
+
+You can use expressions in `extends` for device-specific or conditional layouts:
+
+```html
+{% extends device_type|default:"base.html" %}
+```
+
+```html
+{% extends user.theme|default:"default.html" %}
+```
+
+## Path Traversal Protection
+
+`{% extends %}` and `{% include %}` paths are validated to prevent directory traversal attacks:
+
+```html
+{% extends "../../etc/passwd" %}  {# REJECTED #}
+{% include "../../secrets" %}      {# REJECTED #}
+```
+
+The engine checks that resolved paths stay within the allowed views directories. An `Error` with message starting `path traversal` is thrown if a path escapes the views root.
+
+## Smart Template Discovery for Inheritance
+
+When using `setupExpress()`, the engine automatically searches for parent templates in:
+
+- The configured `views` directory
+- Nested `templates/` directories inside the views root
+- Subdirectories of the views root
+- App-style `app/templates/...`, `packages/*/templates/...`, etc.
+
+This means you can organize templates like:
+
+```text
+project/
+├── views/
+│   ├── base.html
+│   └── home.html
+├── app/
+│   └── templates/
+│       └── admin/
+│           └── dashboard.html
+```
+
+And `{% extends "base.html" %}` will be found regardless of where the child template lives.
+
+## Next Steps
+
+- [Partial Templates](./partial-templates)
+- [Tags: extends and block](./tags#inheritance-tags)
+- [Template Discovery](./template-discovery)

package/docs/guide/what-is-miki-template.md

@@ -0,0 +1,28 @@
+# What is miki-template?
+
+miki-template is a **Django-style template engine for Node.js and Express**. It brings Django's beloved template language — variables, filters, tags, inheritance, and partials — to the Node.js ecosystem with first-class Express integration and modern JavaScript support.
+
+## Philosophy
+
+miki-template is designed for developers who love Django's template syntax but want the speed and flexibility of Node.js. It prioritizes:
+
+- **Developer experience**: Familiar Django syntax, excellent error messages, and sensible defaults.
+- **Performance**: Compiled AST rendering that scales to large, real-world templates.
+- **Modern Node.js**: Full ESM and CommonJS support, async rendering, and compatibility with current Express/Koa/Fastify/Hono/Elysia versions.
+- **Security**: Auto-escaping, safe strings, and Django-style security primitives built in.
+
+## Key Concepts
+
+- **Templates** are text files using `{{ variables }}`, `{% tags %}`, and `| filters`.
+- **Partials** let you define reusable components with `{% partialdef %}` and render them by name.
+- **Template inheritance** uses `{% extends %}` and `{% block %}` to build layout hierarchies.
+- **Smart discovery** finds templates across `views/`, `app/templates/`, and nested folders automatically.
+
+## Who is it for?
+
+miki-template is a great fit if you:
+
+- Prefer Django-style templates over JSX or pure string concatenation.
+- Need **partial rendering** for HTMX or AJAX-heavy apps.
+- Want a template engine that **scales** without rewriting templates as your app grows.
+- Value **security** and want XSS protection by default.

package/docs/guide/why-miki-template.md

@@ -0,0 +1,75 @@
+# Why miki-template?
+
+There are plenty of template engines for Node.js. Here is why miki-template stands out.
+
+## Django Syntax You Already Know
+
+If you have used Django, you already know miki-template. The syntax is intentionally aligned:
+
+```html
+{% if user.is_admin %}
+  <p>Welcome, {{ user.name|title }}!</p>
+{% elif user.is_staff %}
+  <p>Staff dashboard</p>
+{% else %}
+  <p>Please log in.</p>
+{% endif %}
+```
+
+No new DSL to learn. No context switching between backend and frontend templating styles.
+
+## Built for HTMX and Partial Responses
+
+Modern web apps increasingly use HTMX, Turbo, or custom AJAX. miki-template makes partial rendering trivial:
+
+```javascript
+app.get('/card/:id', (req, res) =>
+  res.render(`home#card`, { title: 'Hello', body: '...' })
+);
+```
+
+No extra middleware. No manual view resolution. Just `view#partial`.
+
+## Smart Template Discovery
+
+Forget `Failed to lookup view` errors. miki-template searches your project structure intelligently:
+
+- `views/`
+- `app/templates/`
+- `packages/*/templates/`
+- Any custom folder name you configure
+
+This mirrors Django's `APP_DIRS` behavior and means templates can live where they make sense in your codebase.
+
+## Performance That Scales
+
+miki-template's compiled AST approach is especially fast on realistic templates — the ones with loops, conditionals, filters, and partials that make up real pages.
+
+| Template | miki-template | pug | handlebars | ejs |
+|----------|--------------|-----|------------|-----|
+| Small | ~115k rps | 1.7M rps | 417k rps | 182k rps |
+| Medium | ~454k rps | 625k rps | 48k rps | 29k rps |
+| Large | **~476k rps** | 3.1k rps | 661 rps | 290 rps |
+
+On large templates, miki-template is **~150× faster** than pug, handlebars, and ejs.
+
+## Security by Default
+
+- Auto-escaping enabled by default.
+- SafeString wrapper for explicit bypass.
+- CSRF and CSP tags included.
+- No `eval()` or unsafe code execution.
+
+## First-Class Express Integration
+
+One function wires everything:
+
+```javascript
+miki.setupExpress(app, { extension: 'html', views: './views' });
+```
+
+That is it. No `app.engine()` boilerplate. No manual `res.render` patching. Partial responses work out of the box.
+
+## Extensible and Future-Proof
+
+Need a custom tag? A custom filter? The API is clean and well-documented. miki-template is built to grow with your app, not lock you into a fragile abstraction.

package/docs/index.md

@@ -0,0 +1,104 @@
+<div class="md-hero">
+  <h1 class="md-hero__title">miki-template</h1>
+  <p class="md-hero__subtitle">Django-style template magic for Node.js — blazing fast partials, smart template discovery, and zero friction for HTMX.</p>
+  <div class="md-hero__buttons">
+    <a href="guide/quick-start" class="md-button md-button--primary">Get Started</a>
+    <a href="api/" class="md-button">API Reference</a>
+    <a href="https://github.com/alainmiki/miki-template" class="md-button" target="_blank" rel="noopener">
+      <span class="md-icon">&#128190;</span> GitHub
+    </a>
+  </div>
+  <div style="margin-top: 1.5rem; display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap; position: relative; align-items: center;">
+    <img src="assets/banner.png" alt="miki-template banner" style="max-width: 100%; height: auto; border-radius: 0.5rem; box-shadow: 0 4px 12px var(--md-shadow-color); max-height: 200px;">
+  </div>
+  <div style="margin-top: 1rem; display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap; position: relative; align-items: center;">
+    <a href="https://www.npmjs.com/package/miki-template" target="_blank" rel="noopener">
+      <img src="https://img.shields.io/npm/v/miki-template.svg" alt="npm version" style="height: 20px;">
+    </a>
+    <a href="https://www.npmjs.com/package/miki-template" target="_blank" rel="noopener">
+      <img src="https://img.shields.io/npm/dm/miki-template.svg" alt="npm downloads" style="height: 20px;">
+    </a>
+    <a href="https://github.com/alainmiki/miki-template" target="_blank" rel="noopener">
+      <img src="https://img.shields.io/github/actions/workflow/status/alainmiki/miki-template/ci.yml?branch=main" alt="CI status" style="height: 20px;">
+    </a>
+  </div>
+</div>
+
+<div class="md-typeset">
+
+## Why miki-template?
+
+miki-template brings Django's beloved template language to Node.js and Express. Define reusable partials with `{% partialdef %}`, render any slice of a page with `render('home#card')`, and let the engine find templates across your whole project — `templates/`, `app/templates/`, or whatever structure you prefer.
+
+- **Partial-powered templating**: `{% partialdef %}` blocks render by name anywhere — `res.render('home#card')`, `renderPartialFromSource(...)`, or `compiled.renderBlock('block')`. Built for HTMX-style partial responses.
+- **Smart template discovery**: Stop hardcoding view paths. The engine searches `templates/`, nested app directories, and custom folder names automatically — just like Django.
+- **One-line Express integration**: `miki.setupExpress(app, { extension: 'html', views: dir })` wires everything up. No boilerplate, no extra middleware.
+- **Full Django syntax parity**: Variables, dotted lookups, filters (`|`), block tags (`{% %}`), template inheritance with `extends` and `block.super`.
+- **Blazing fast**: Compiled AST rendering dominates on realistic pages — ~150× faster than pug, handlebars, and ejs on large templates.
+- **ESM & CommonJS**: Works seamlessly with both `import` and `require` syntax.
+- **Security by default**: Auto-escaping, `SafeString`, CSRF and CSP tags.
+
+## Quick example
+
+=== "CommonJS"
+
+    ```javascript
+    const express = require('express');
+    const miki = require('miki-template');
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    app.get('/', (req, res) => res.render('home', { user: req.user }));
+    app.get('/partials/:name', (req, res) =>
+      res.render(`home#${req.params.name}`, { user: req.user })
+    );
+
+    app.listen(3000);
+    ```
+
+=== "ES Modules"
+
+    ```javascript
+    import express from 'express';
+    import miki from 'miki-template';
+
+    const app = express();
+    miki.setupExpress(app, { extension: 'html', views: './views' });
+
+    app.get('/', (req, res) => res.render('home', { user: req.user }));
+    app.get('/partials/:name', (req, res) =>
+      res.render(`home#${req.params.name}`, { user: req.user })
+    );
+
+    app.listen(3000);
+    ```
+
+## Installation
+
+```bash
+npm install miki-template
+```
+
+See the [Installation guide](guide/installation) for pnpm, yarn, and Bun instructions.
+
+## Documentation
+
+- [What is miki-template?](guide/what-is-miki-template)
+- [Getting Started](guide/getting-started)
+- [Quick Start](guide/quick-start)
+- [Filters](guide/filters)
+- [Tags](guide/tags)
+- [Partial Templates](guide/partial-templates)
+- [Template Inheritance](guide/template-inheritance)
+- [Template Discovery](guide/template-discovery)
+- [Security](guide/security)
+- [Integrations](integrations/)
+- [API Reference](api/)
+- [Performance](performance)
+
+## License
+
+MIT
+
+</div>