miki-template 1.3.7 → 2.0.0

package/.github/release-notes/v1.3.7.md

@@ -0,0 +1,20 @@
+## v1.3.7 — Template discovery improvements
+
+- Add recursive/app-style template discovery so projects can place
+  templates in nested `templates/` folders (Django-style) and have
+  them discovered automatically.
+- `setupExpress` now expands `app.get('views')` to include nested
+  directories that contain template files so `res.render('name')`
+  works for templates located in project-level or package-level
+  `templates/` directories.
+- Expose `findTemplateInViews(name, roots)` helper and
+  `setAppTemplateDirNames()/getAppTemplateDirNames()` to configure
+  app-style template folder names.
+- Improve `res.render` fallback to use the recursive finder before
+  throwing Express's "Failed to lookup view" error.
+- Update docs and API reference with usage examples and migration
+  notes.
+
+CI: runs lint + tests (all passing locally). If you'd like a more
+comprehensive changelog, I can expand this with links to issues and
+code snippets.

package/API_REFERENCE.md

@@ -107,6 +107,33 @@ app.get('/', (req, res) => {
 });
 ```
 
+### Template discovery helpers
+
+`miki-template` exposes helpers to discover templates across multiple
+`views` roots and to configure what directory names are considered
+app-style template folders (e.g. `templates` or `app_templates`). These
+are useful for projects that place templates in nested app folders or
+package-level `templates/` directories.
+
+#### `findTemplateInViews(name, viewsDirs)`
+
+Search for a template by `name` across the provided `viewsDirs` array
+or single string. Performs direct resolution first, then a recursive
+search for bare filenames. Returns the absolute file path or `null`.
+
+Example:
+```js
+const found = require('miki-template').findTemplateInViews('detail', ['./views', './templates']);
+```
+
+#### `setAppTemplateDirNames(names)` / `getAppTemplateDirNames()`
+
+Configure and retrieve the directory names treated as app-style
+template folders when scanning the project tree. The default is
+`['templates']`. Use `setAppTemplateDirNames(['templates','app_templates'])`
+to include additional conventions.
+
+
 ---
 
 ### `registerTag(name, parserFn)`

package/README.md

@@ -132,6 +132,16 @@ app.listen(3000);
 
 > `setupExpress` calls `app.engine()`, `app.set('views')`, and `app.set('view engine')` for you, and patches `res.render` so `view#partial` is dispatched to the partial renderer (not the file system). It works equally well for `.miki` files — just pass `extension: 'miki'`.
 
+Note on template discovery: `setupExpress` now expands the `app.get('views')`
+value to include nested directories that contain template files. This
+means templates placed in project-level `templates/`, package-level
+`packages/*/templates/...`, or app-specific folders (e.g. `app_templates/`)
+will be discovered automatically when calling `res.render('name')`.
+
+If your project uses a different convention than `templates`, call
+`setAppTemplateDirNames()` to customize the names that the engine
+recognizes when scanning for app-style template folders.
+
 **The classic, fully manual setup still works** if you prefer it:
 
 ```javascript

package/benchmarks/report.json

@@ -1,17 +1,17 @@
 [
   {
     "name": "small",
-    "syncAvgMs": "0.04",
+    "syncAvgMs": "0.01",
     "asyncAvgMs": "0.03"
   },
   {
     "name": "medium",
-    "syncAvgMs": "0.00",
+    "syncAvgMs": "0.01",
     "asyncAvgMs": "0.01"
   },
   {
     "name": "large",
-    "syncAvgMs": "0.00",
+    "syncAvgMs": "0.01",
     "asyncAvgMs": "0.01"
   }
 ]

package/docs/api.md

@@ -12,6 +12,9 @@ This document lists the public API exported by **miki-template** for developers
 | `express(options?)` | `express(object?) → function` | Factory that returns a view-engine function suitable for `app.engine(...)`. Honors `view#partial` selectors. | `app.engine('html', miki.express());` |
 | `setupExpress(app, opts?)` | `setupExpress(expressApp, object?) → void` | **One-line Express integration.** Wires `app.engine(...)`, `app.set('views')`, and patches `res.render` so `res.render('view#partial', ...)` returns just that partial. Options: `{ extension?, views?, async? }`. | `miki.setupExpress(app, { extension: 'html', views: './views' });` |
 | `expressPartialRenderer()` | `expressPartialRenderer() → function` | Express middleware that adds `res.renderPartial(view, locals)`. Useful as a drop-in HTMX helper without the full `setupExpress` shim. | `app.use(miki.expressPartialRenderer());` |
+| `findTemplateInViews(name, viewsDirs)` | `findTemplateInViews(string, string[]|string) → string|null` | Search for a template by name across one or more `views` roots. Performs direct resolution first (supports explicit paths and extensions), then a recursive search for bare filenames in subdirectories. Returns the absolute file path or `null` if not found. | `miki.findTemplateInViews('detail', ['./views', './templates'])` |
+| `setAppTemplateDirNames(names)` | `setAppTemplateDirNames(string[]|string) → void` | Configure which directory names are treated as app-style template folders when scanning (default: `['templates']`). Useful when projects use a different convention. | `miki.setAppTemplateDirNames(['templates','app_templates'])` |
+| `getAppTemplateDirNames()` | `getAppTemplateDirNames() → string[]` | Retrieve the current configured app-template directory names. | `const names = miki.getAppTemplateDirNames()` |
 | `renderPartialFromFile(filePath, partialName, context?, options?)` | `renderPartialFromFile(string, string, object?, object?) → string` | Load a file from disk and render only the named `{% partialdef %}`. | `miki.renderPartialFromFile('views/home.html', 'card', { user });` |
 | `renderPartialFromSource(source, partialName, context?, options?)` | `renderPartialFromSource(string, string, object?, object?) → string` | Render a single named partial directly from a template string. Walks the AST (and `extends` chain) to discover partials nested inside blocks. | `miki.renderPartialFromSource(src, 'card', ctx, { views });` |
 | `stripExpressContext(options)` | `stripExpressContext(object) → object` | Remove Express framework keys (`_locals`, `settings`, `cache`) from an options object. | `const ctx = stripExpressContext(res.locals);` |

package/ex.mjs

@@ -26,10 +26,11 @@ const dir=path.join(process.cwd(),"dir")
       {name:"miki", email:"jack@miki.com",address:"kumba"},
       {name:"luis",email:"luis@miki.com",address:"kumba"}
     ]
-    res.render("index",{name:"miki-template context", users:users, data:data})
+    res.render("index#card",{name:"miki-template context", users:users, data:data})
     // res.send(content)
   })
 
+
 app.listen(3000, () => {
     console.log('Server is running on port 3000 click: http://localhost:3000')
 }  )

package/live-test/package-lock.json

@@ -9,7 +9,7 @@
       "version": "1.0.0",
       "dependencies": {
         "express": "^5.2.1",
-        "miki-template": "1.3.6"
+        "miki-template": "file:../miki-template-2.0.0.tgz"
       }
     },
     "node_modules/accepts": {
@@ -515,9 +515,9 @@
       }
     },
     "node_modules/miki-template": {
-      "version": "1.3.6",
-      "resolved": "https://registry.npmjs.org/miki-template/-/miki-template-1.3.6.tgz",
-      "integrity": "sha512-xB658VrwCMAg8abpMzKF8ZKlnYgMaX7eimpxSx/GR35sor5kW/bhqiYr54HXpNux3d0Qgv7uUPszid3MFYcpSA==",
+      "version": "1.3.7",
+      "resolved": "file:../miki-template-2.0.0.tgz",
+      "integrity": "sha512-FGTWjPS3CTm3X4+dnRKqHwqQUKgqtz/0VNTjN1BQjBcgwhXnEbVYg06VZmBtZ8SYr6z12JIX3LGj2pQog3h84Q==",
       "license": "MIT",
       "dependencies": {
         "date-fns": "^3.6.0",

package/live-test/package.json

@@ -4,6 +4,6 @@
   "private": true,
   "dependencies": {
     "express": "^5.2.1",
-    "miki-template": "1.3.6"
+    "miki-template": "file:../miki-template-2.0.0.tgz"
   }
 }

package/live-test/packages/product/templates/product/detail.html

@@ -0,0 +1,7 @@
+<html>
+<head><title>Product Detail</title></head>
+<body>
+  <h1>Product: {{ name }}</h1>
+  <p>Price: {{ price }}</p>
+</body>
+</html>

package/live-test/server.js

@@ -4,11 +4,35 @@ const miki = require('miki-template');
 
 const app = express();
 const views = path.join(__dirname, 'views');
+const templatesRoot = path.join(__dirname, 'templates');
 
-miki.setupExpress(app, { extension: 'html', views });
+// Demonstrate multiple discovery roots: explicit views dir,
+// plus a top-level `templates/` (Django-style) and app-style nested folders
+// discovered anywhere under the project root.
+miki.setupExpress(app, { extension: 'html', views: [views, templatesRoot, __dirname] });
+
+// Note: `miki.setupExpress` may expand `app.get('views')` to include
+// nested template directories (project-level `templates/`,
+// app-style `packages/*/templates/...`, etc.). The live-test app
+// intentionally passed multiple roots to demonstrate discovery.
 
 app.get('/', (req, res) => {
   res.render('index', { name: 'Live NPM' });
 });
 
+// Render a nested child template that extends base.html located in views/
+app.get('/child', (req, res) => {
+  res.render('child', { title: 'From Live', message: 'Hello from child' });
+});
+
+// Render a template located under templates/app_templates/detail.html
+
+app.get('/app-detail', (req, res) => {
+  res.render('detail', { item: 'Widget 42' });
+});
+
+app.get('/product', (req, res) => {
+  res.render('product/detail', { name: 'Gizmo', price: '$19.99' });
+});
+
 app.listen(3002, () => console.log('Live test app listening on 3002'));

package/live-test/templates/app_templates/detail.html

@@ -0,0 +1,6 @@
+<html>
+<head><title>App Template</title></head>
+<body>
+  <h1>App-level template: {{ item }}</h1>
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miki-template",
-  "version": "1.3.7",
+  "version": "2.0.0",
   "description": "Django-Style template engine for Node.js and Express",
   "main": "src/index.js",
   "exports": {

package/src/index.js

@@ -894,11 +894,80 @@ function setupExpress(app, opts = {}) {
   // Install the raw engine so Express can use it
   app.engine(ext, async ? __expressAsync : __express);
 
+  // Expand configured view roots to include nested directories that
+  // actually contain template files. Express will only check the
+  // directories returned by `app.get('views')`, so if templates live
+  // inside nested app folders (e.g. `packages/*/templates/...`), we
+  // must include those directories explicitly so `res.render('name')`
+  // succeeds without additional work by users.
+  function expandViewsForExpress(viewsInput, maxDepth = 6) {
+    const seen = new Set();
+    const results = [];
+    const roots = normalizeViews(viewsInput || (app.get && app.get('views')) || ['.']);
+    const isTemplateFile = name => /\.(html|miki)$/i.test(name);
+
+    for (const r of roots) {
+      let rootPath;
+      try { rootPath = path.resolve(r); } catch { continue; }
+      if (seen.has(rootPath)) continue;
+      seen.add(rootPath);
+      // BFS/DFS limited traversal
+      const stack = [{ dir: rootPath, depth: 0 }];
+      while (stack.length) {
+        const cur = stack.pop();
+        let entries;
+        try { entries = fs.readdirSync(cur.dir, { withFileTypes: true }); } catch { continue; }
+        let hasTemplate = false;
+        for (const ent of entries) {
+          if (ent.isFile() && isTemplateFile(ent.name)) {
+            hasTemplate = true;
+            break;
+          }
+        }
+        if (hasTemplate) {
+          if (!seen.has(cur.dir)) {
+            seen.add(cur.dir);
+            results.push(cur.dir);
+          }
+        }
+        if (cur.depth < maxDepth) {
+          for (const ent of entries) {
+            if (!ent.isDirectory()) continue;
+            const name = ent.name;
+            if (name === 'node_modules' || name === '.git' || name === 'dist' || name === 'build') continue;
+            const child = path.join(cur.dir, name);
+            if (!seen.has(child)) stack.push({ dir: child, depth: cur.depth + 1 });
+          }
+        }
+      }
+      // Always include the root itself so existing layouts still work
+      if (!results.includes(rootPath)) results.unshift(rootPath);
+    }
+    return results;
+  }
+
   // Capture config in a closure so patchedRender can use it even
   // when called before the request handler runs.
   const configExt = ext;
   const configViews = opts.views;
 
+  // Expand and set the app 'views' so Express's resolver can find
+  // templates placed in nested directories. Only do this when a
+  // non-empty views value exists (we don't want to change defaults
+  // if user intentionally left it unset).
+  try {
+    const currentViews = app.get && app.get('views') ? app.get('views') : configViews || app.get && app.get('views');
+    if (currentViews) {
+      const expanded = expandViewsForExpress(currentViews);
+      if (expanded && expanded.length) {
+        app.set('views', expanded);
+      }
+    }
+  } catch (e) {
+    // Don't crash setupExpress if view expansion fails; fallback to
+    // whatever the app already had configured.
+  }
+
   // Capture the original res.render so we can dispatch on #partial
   const originalRender = app.response.render;
   app.response.render = function patchedRender(view, locals, callback) {
@@ -951,9 +1020,19 @@ function setupExpress(app, opts = {}) {
           break;
         }
       }
-      // Fallback: recursive search for templates in subfolders
+      // Fallback: recursive search for templates in subfolders. If
+      // the configured views is an array, search all normalized
+      // entries rather than only the first directory so app-style
+      // templates under other roots are discovered.
       if (!filePath) {
-        const found = findTemplateInViews(fileName, [viewsDir]);
+        let searchDirs = [viewsDir];
+        if (Array.isArray(viewsDir)) {
+          searchDirs = normalizeViews(viewsDir);
+        } else if (Array.isArray(configViews)) {
+          // If setupExpress was given an array, include its normalized form
+          searchDirs = normalizeViews(configViews);
+        }
+        const found = findTemplateInViews(fileName, searchDirs);
         if (found) filePath = found;
       }
       if (!filePath) {
@@ -984,11 +1063,55 @@ function setupExpress(app, opts = {}) {
       }
     }
 
-    // No partial selector: behave exactly like the original res.render
-    if (cb) {
-      return originalRender.call(this, view, opts, cb);
+    // No partial selector: behave exactly like the original res.render.
+    // If Express fails to locate the view (no recursive lookup),
+    // fall back to our recursive/app-style finder and invoke the
+    // engine directly with the resolved file path.
+    try {
+      if (cb) {
+        return originalRender.call(this, view, opts, cb);
+      }
+      return originalRender.call(this, view, opts);
+    } catch (err) {
+      // Detect Express view-not-found error and attempt fallback
+      if (err && typeof err.message === 'string' && err.message.includes('Failed to lookup view')) {
+        // Determine normalized view roots to search. Prefer arrays
+        // returned by app.get('views') (Express supports arrays).
+        let roots = [];
+        try {
+          const appViews = this.req && this.req.app ? this.req.app.get('views') : null;
+          if (appViews) roots = roots.concat(Array.isArray(appViews) ? normalizeViews(appViews) : [appViews]);
+        } catch (e) {}
+        if (configViews) roots = roots.concat(Array.isArray(configViews) ? normalizeViews(configViews) : [configViews]);
+        // If expandViewsForExpress was used earlier, app.get('views')
+        // may already be an expanded array of candidate dirs. Ensure
+        // uniqueness and absolute resolution.
+        roots = roots.filter(Boolean).map(r => path.resolve(r));
+        roots = Array.from(new Set(roots));
+
+        // Try to find the template file using our recursive finder.
+        const searchRoots = roots.length ? roots : [process.cwd()];
+        const found = findTemplateInViews(view, searchRoots);
+        if (found) {
+          // Invoke the engine directly with the resolved file path.
+          try {
+            if (cb) return (__express)(found, opts, cb);
+            return __express(found, opts, (err2, html) => {
+              if (err2) {
+                if (cb) return cb(err2);
+                throw err2;
+              }
+              this.send(html);
+            });
+          } catch (e2) {
+            if (cb) return cb(e2);
+            throw e2;
+          }
+        }
+      }
+      // Not our error or fallback failed — rethrow
+      throw err;
     }
-    return originalRender.call(this, view, opts);
   };
 }
 
@@ -1039,9 +1162,20 @@ function expressPartialRenderer() {
           filePath = null;
         } catch { filePath = null; }
       }
-      // Fallback: recursive search for templates in subfolders
+      // Fallback: recursive search for templates in subfolders. Prefer
+      // searching all normalized view roots so templates in sibling
+      // folders (project-level `templates/`, packages/*/templates, etc.)
+      // are found.
       if (!filePath) {
-        const found = findTemplateInViews(fileName, Array.isArray(viewsDir) ? viewsDir : [viewsDir]);
+        let searchDirs = Array.isArray(viewsDir) ? normalizeViews(viewsDir) : [viewsDir];
+        // Also include the app-level configured views array if present
+        try {
+          const appViews = req.app.get('views');
+          if (Array.isArray(appViews)) {
+            searchDirs = searchDirs.concat(normalizeViews(appViews));
+          }
+        } catch (e) {}
+        const found = findTemplateInViews(fileName, searchDirs);
         if (found) filePath = found;
       }
       if (!filePath) {