@arponascension/express-inertia 1.5.1 → 1.6.0

package/README.md

@@ -8,7 +8,7 @@
 
 **@arponascension/express-inertia** is a production-ready **Inertia.js adapter for Express.js**. It brings the official [Inertia.js](https://inertiajs.com) protocol to **Node.js and Express** apps so you can build modern **single-page applications (SPAs)** with **Vue 3**, **React**, or **Svelte** using classic server-side routing and controllers — without the complexity of a REST API or a client-side router.
 
-It ships with a **Blade-style EJS template engine**, **zero-config Vite** integration (HMR in development, hashed `manifest.json` in production), **server-side rendering (SSR)** with circuit-breaker resilience, **security hardening**, **edge-runtime support** (Cloudflare Workers, Vercel Edge, Netlify Edge), and **first-class TypeScript** types — all in a tree-shakeable ~40KB bundle.
+It ships with a **native EJS template engine** with Inertia/Vite helpers, **zero-config Vite** integration (HMR in development, hashed `manifest.json` in production), **server-side rendering (SSR)** with circuit-breaker resilience, **security hardening**, **edge-runtime support** (Cloudflare Workers, Vercel Edge, Netlify Edge), and **first-class TypeScript** types — all in a tree-shakeable ~40KB bundle.
 
 > New to Inertia.js? Read [What is Inertia.js?](#what-is-inertiajs) or the [official documentation](https://inertiajs.com/docs).
 
@@ -22,7 +22,7 @@ It ships with a **Blade-style EJS template engine**, **zero-config Vite** integr
 - [Installation](#installation)
 - [Quick Start: Express + Inertia + Vue 3](#quick-start-express--inertia--vue-3)
 - [Using Inertia.js with React](#using-inertiajs-with-react)
-- [Blade-style EJS Directives for Express](#blade-style-ejs-directives-for-express)
+- [EJS Template Helpers for Express](#ejs-template-helpers-for-express)
 - [Vite Integration for Express](#vite-integration-for-express)
 - [Server-Side Rendering (SSR) for SEO](#server-side-rendering-ssr-for-seo)
 - [Response API: `res.inertia()`](#response-api-resinertia)
@@ -60,7 +60,7 @@ Inertia requests return plain JSON to the client (no full page reloads); real fu
 
 | Feature | What you get |
 |---|---|
-| **Blade-style EJS directives** | Write Laravel Blade syntax (`@inertia`, `@vite`, `@csrf`, `@inertiaHead`) directly inside `.ejs` templates |
+| **Native EJS template helpers** | Call `<%- inertia() %>`, `<%- vite('src/main.ts') %>`, `<%- csrf() %>`, and `<%- inertiaHead() %>` directly inside `.ejs` templates |
 | **Zero-config Vite integration** | Automatic HMR in development; hashed `manifest.json` asset resolution in production |
 | **Server-side rendering (SSR)** | Express + Inertia SSR endpoint proxying with retry/backoff and **circuit breaker** fallback to client rendering |
 | **Security hardening** | Component name validation against path traversal, `viewData` sanitization, SRI hash generation |
@@ -107,7 +107,7 @@ import { inertia, createInertiaEngine } from '@arponascension/express-inertia';
 
 const app = express();
 
-// Blade-compatible EJS view engine for Express
+// EJS view engine with Inertia/Vite helpers for Express
 app.engine('ejs', createInertiaEngine());
 app.set('view engine', 'ejs');
 app.set('views', path.join(__dirname, 'views'));
@@ -147,12 +147,12 @@ app.listen(3000, () => console.log('Server running on http://localhost:3000'));
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title inertia><%= page?.props?.title || 'App' %></title>
 
-    @inertiaHead
-    @vite('src/main.ts')
+    <%- inertiaHead() %>
+    <%- vite('src/main.ts') %>
   </head>
   <body>
-    @inertia
-    @csrf
+    <%- inertia() %>
+    <%- csrf() %>
   </body>
 </html>
 ```
@@ -179,13 +179,13 @@ import vue from '@vitejs/plugin-vue';
 import { inertiaVitePlugin } from '@arponascension/express-inertia/vite';
 
 export default defineConfig({
-  plugins: [vue(), inertiaVitePlugin()],
-  base: '/build/',
-  build: { manifest: true, outDir: 'public/build' },
+  plugins: [vue(), inertiaVitePlugin({ input: 'src/main.ts', refresh: true })],
 });
 ```
 
-Start Express and Vite in separate terminals during development; `inertiaVitePlugin()` writes `public/hot` so the EJS root view automatically uses the Vite dev server. Run `vite build` before production deployment to write `public/build/.vite/manifest.json`.
+Start Express and Vite in separate terminals during development; `inertiaVitePlugin()` writes `public/hot` so the EJS root view automatically uses the Vite dev server.
+
+When an `input` is provided, the plugin **auto-configures the production build**: it sets `build.manifest`, `build.outDir` (default `public/build`), `build.rollupOptions.input`, and a command-aware `base` (root-relative in dev, `/build/` at build time) — so `vite build` emits `public/build/.vite/manifest.json` ready for Express with **zero manual Vite config**. The `refresh: true` option makes the browser full-reload when an EJS view under `views/` changes.
 
 ## Using Inertia.js with React
 
@@ -203,11 +203,11 @@ createInertiaApp({
 });
 ```
 
-For React, use a `.tsx` entrypoint in the root view and include `@viteReactRefresh` before `@vite`:
+For React, use a `.tsx` entrypoint in the root view and include `<%- viteReactRefresh() %>` before `<%- vite('src/main.tsx') %>`:
 
 ```html
-@viteReactRefresh
-@vite('src/main.tsx')
+<%- viteReactRefresh() %>
+<%- vite('src/main.tsx') %>
 ```
 
 Replace the Vue plugin with `@vitejs/plugin-react` in `vite.config.ts` and keep the same `inertiaVitePlugin()`:
@@ -218,47 +218,64 @@ import react from '@vitejs/plugin-react';
 import { inertiaVitePlugin } from '@arponascension/express-inertia/vite';
 
 export default defineConfig({
-  plugins: [react(), inertiaVitePlugin()],
-  base: '/build/',
-  build: { manifest: true, outDir: 'public/build' },
+  plugins: [react(), inertiaVitePlugin({ input: 'src/main.tsx', refresh: true })],
 });
 ```
 
 ---
 
-## Blade-style EJS Directives for Express
+## EJS Template Helpers for Express
 
-Write Laravel Blade-style syntax inside EJS templates, powered by a custom Express view engine:
+Call the Inertia and Vite helpers as normal EJS expressions, powered by a custom Express view engine:
 
-| Directive | Component Tag | Output |
-|---|---|---|
-| `@inertia` | `<x-inertia />` | Renders `<div id="app"></div><script data-page="app" type="application/json">` |
-| `@inertia('root')` | `<x-inertia id="root" />` | Custom root ID |
-| `@inertiaScript` | `<x-inertia-script />` | JSON script only (manual root container) |
-| `@inertiaHead` | `<x-inertia-head />` | Injects SSR `<head>` tags |
-| `@vite('src/main.ts')` | `<x-vite src="src/main.ts" />` | Dev HMR or production manifest |
-| `@viteReactRefresh` | `<x-vite-react-refresh />` | React Fast Refresh preamble |
-| `@csrf` | `<x-csrf />` | CSRF hidden input |
-| `@routes` | `<x-routes />` | Ziggy / route definitions |
-| `@json(myVar)` | — | Safely stringifies a JS object |
-
-### Custom directives
+| EJS helper | Output |
+|---|---|
+| `<%- inertia() %>` | Renders `<div id="app"></div><script data-page="app" type="application/json">` |
+| `<%- inertia('root') %>` | Custom root ID |
+| `<%- inertiaScript() %>` | JSON script only (manual root container) |
+| `<%- inertiaHead() %>` | Injects SSR `<head>` tags |
+| `<%- vite('src/main.ts') %>` | Dev HMR or production manifest |
+| `<%- viteReactRefresh() %>` | React Fast Refresh preamble |
+| `<%- csrf() %>` | CSRF hidden input |
+| `<%- routes() %>` | Ziggy / route definitions |
+| `<%- json(myVar) %>` | Safely stringifies a JS object |
+
+---
+
+## Vite Integration for Express
+
+Auto-detects the Vite dev server via the hot file (`public/hot`) and reads `manifest.json` in production.
+
+### Zero-config: `inertiaVitePlugin({ input, refresh })`
+
+The recommended setup requires nothing but your client entrypoint:
 
 ```ts
-import { registerDirective } from '@arponascension/express-inertia';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { inertiaVitePlugin } from '@arponascension/express-inertia/vite';
 
-registerDirective('uppercase', (args) => `<%= (${args}).toUpperCase() %>`);
+export default defineConfig({
+  plugins: [react(), inertiaVitePlugin({ input: 'src/main.tsx', refresh: true })],
+});
 ```
 
----
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `input` | `string \| string[]` | — | Client entrypoint(s) for the build. When set, the plugin auto-configures the build: enables `build.manifest`, builds into `public/{buildDirectory}`, registers `build.rollupOptions.input`, and uses a command-aware `base` (root in dev, `/{buildDirectory}/` at build time so hashed asset URLs resolve against the Express static mount). |
+| `refresh` | `boolean \| string \| string[]` | `false` | Auto full-page reload when a server-rendered template changes. `true` watches `views/**/*.ejs`; a glob string or array watches custom paths relative to the project root. |
+| `buildDirectory` | `string` | `'build'` | Directory inside `public/` that Vite builds into. |
+| `hotFile` | `string` | `'public/hot'` | Hot file written by the plugin in dev mode. |
+| `devServerUrl` | `string` | resolved dev URL | Override for the URL written to the hot file. |
 
-## Vite Integration for Express
+### Manual asset resolution
 
-Auto-detects the Vite dev server via the hot file (`public/hot`) and reads `manifest.json` in production:
+If you prefer to configure the build or engine yourself, the `vite` option on `createInertiaEngine()` (or the `inertia()` middleware, which is ignored there and only consumed by the engine) still gives you full control:
 
 ```ts
-app.use(
-  inertia({
+app.engine(
+  'ejs',
+  createInertiaEngine({
     vite: {
       publicDir: 'public',
       buildDir: 'build',
@@ -270,6 +287,20 @@ app.use(
 );
 ```
 
+> For that manual route, configure the build yourself — and use a command-aware `base` (a static `base: '/build/'` would make the Vite dev server serve modules under `/build/`, breaking dev HMR):
+>
+> ```ts
+> export default defineConfig(({ command }) => ({
+>   plugins: [react(), inertiaVitePlugin()],
+>   base: command === 'build' ? '/build/' : '/',
+>   build: {
+>     manifest: true,
+>     outDir: 'public/build',
+>     rollupOptions: { input: 'src/main.tsx' },
+>   },
+> }));
+> ```
+
 ### Prefetch and preload helpers
 
 ```ts
@@ -558,7 +589,7 @@ const delay = calculateBackoff(attempt, 200, 2000);
 | `inertia(options?)` | Inertia.js Express middleware factory |
 | `createInertia(options?)` | Same as `inertia`, explicit name |
 | `requestIdMiddleware()` | Assigns `req.id` for log correlation |
-| `createInertiaEngine(options?)` | EJS view engine with Blade support |
+| `createInertiaEngine(options?)` | EJS view engine with Inertia/Vite helpers |
 | `inertiaEngine` | Default engine instance |
 
 ### Prop helpers
@@ -599,7 +630,7 @@ const delay = calculateBackoff(attempt, 200, 2000);
 | Export | Description |
 |---|---|
 | `createViteHelper(config?)` | Vite asset resolver |
-| `inertiaVitePlugin(opts?)` | Auto write/remove the Vite hot file |
+| `inertiaVitePlugin(opts?)` | Vite plugin — hot file + auto build config (`input`, `refresh`, `buildDirectory`) |
 | `createPrefetchHelper(viteHelper)` | Prefetch/preload tag generator |
 
 ---
@@ -624,7 +655,7 @@ Yes. Enable `ssr: { enabled: true }` and point it at the official Inertia SSR se
 
 ### What template engine does express-inertia use?
 
-EJS, extended with Laravel Blade-style directives (`@inertia`, `@vite`, `@csrf`, `@inertiaHead`, and more). A custom `createInertiaEngine()` is provided so templates load through Express's normal view engine mechanism.
+EJS. A custom `createInertiaEngine()` is provided so templates load through Express's normal view engine mechanism, with Inertia and Vite helpers exposed as template locals (`inertia()`, `vite()`, `csrf()`, `inertiaHead()`, and more).
 
 ### Is express-inertia compatible with edge runtimes?
 

package/dist/base.ejs

@@ -4,11 +4,11 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" />
     <title inertia><%= typeof title !== 'undefined' ? title : (page && page.props && page.props.title ? page.props.title : 'App') %></title>
-    @inertiaHead
-    @viteReactRefresh
-    @vite('src/main.js')
+    <%- inertiaHead() %>
+    <%- viteReactRefresh() %>
+    <%- vite('src/main.js') %>
   </head>
   <body class="font-sans antialiased bg-gray-50 text-gray-900">
-    @inertia
+    <%- inertia() %>
   </body>
 </html>

package/dist/engine.d.mts

@@ -1,4 +1,4 @@
-import { c as Page, e as SSRResult, B as BladeEngineOptions } from './types-DgBPobaU.mjs';
+import { b as Page, d as SSRResult, f as InertiaEngineOptions } from './types-BlUoEa9x.mjs';
 import 'express';
 
 interface TemplateLocals extends Record<string, any> {
@@ -9,11 +9,11 @@ interface TemplateLocals extends Record<string, any> {
     routes?: any;
 }
 /**
- * Creates an Express view engine with Blade directive support and built-in Inertia/Vite helpers.
+ * Creates an Express EJS view engine with built-in Inertia/Vite helpers.
  */
-declare function createInertiaEngine(options?: BladeEngineOptions): (filePath: string, rawOptions: Record<string, any>, callback: (err: Error | null, html?: string) => void) => void;
+declare function createInertiaEngine(options?: InertiaEngineOptions): (filePath: string, rawOptions: Record<string, any>, callback: (err: Error | null, html?: string) => void) => void;
 /**
- * Default Inertia Blade EJS engine instance.
+ * Default Inertia EJS engine instance.
  */
 declare const inertiaEngine: (filePath: string, rawOptions: Record<string, any>, callback: (err: Error | null, html?: string) => void) => void;
 /**

package/dist/engine.d.ts

@@ -1,4 +1,4 @@
-import { c as Page, e as SSRResult, B as BladeEngineOptions } from './types-DgBPobaU.js';
+import { b as Page, d as SSRResult, f as InertiaEngineOptions } from './types-BlUoEa9x.js';
 import 'express';
 
 interface TemplateLocals extends Record<string, any> {
@@ -9,11 +9,11 @@ interface TemplateLocals extends Record<string, any> {
     routes?: any;
 }
 /**
- * Creates an Express view engine with Blade directive support and built-in Inertia/Vite helpers.
+ * Creates an Express EJS view engine with built-in Inertia/Vite helpers.
  */
-declare function createInertiaEngine(options?: BladeEngineOptions): (filePath: string, rawOptions: Record<string, any>, callback: (err: Error | null, html?: string) => void) => void;
+declare function createInertiaEngine(options?: InertiaEngineOptions): (filePath: string, rawOptions: Record<string, any>, callback: (err: Error | null, html?: string) => void) => void;
 /**
- * Default Inertia Blade EJS engine instance.
+ * Default Inertia EJS engine instance.
  */
 declare const inertiaEngine: (filePath: string, rawOptions: Record<string, any>, callback: (err: Error | null, html?: string) => void) => void;
 /**

package/dist/engine.js

@@ -12,86 +12,6 @@ var path__default = /*#__PURE__*/_interopDefault(path);
 
 // src/engine.ts
 
-// src/directives.ts
-var customDirectives = {};
-function escapeJsString(str) {
-  return str.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
-}
-function compileBladeDirectives(templateSource, localDirectives) {
-  let compiled = templateSource;
-  compiled = compiled.replace(
-    /<x-inertia(\s[^>]*)?\s*(\/|><\/x-inertia>)/gi,
-    (_match, attrs) => {
-      const idMatch = attrs?.match(/id=(?:"([^"]*)"|'([^']*)')/);
-      const id = idMatch ? idMatch[1] || idMatch[2] : void 0;
-      return id ? `<%- inertia('${escapeJsString(id)}') %>` : `<%- inertia() %>`;
-    }
-  );
-  compiled = compiled.replace(
-    /<x-inertia-(?:script|data)(\s[^>]*)?\s*(\/|><\/x-inertia-(?:script|data)>)/gi,
-    (_match, attrs) => {
-      const idMatch = attrs?.match(/id=(?:"([^"]*)"|'([^']*)')/);
-      const id = idMatch ? idMatch[1] || idMatch[2] : void 0;
-      return id ? `<%- inertiaScript('${escapeJsString(id)}') %>` : `<%- inertiaScript() %>`;
-    }
-  );
-  compiled = compiled.replace(
-    /<x-inertia-head\s*(?:\/>|><\/x-inertia-head>)|<x-inertiaHead\s*(?:\/>|><\/x-inertiaHead>)/gi,
-    "<%- inertiaHead() %>"
-  );
-  compiled = compiled.replace(
-    /<x-vite(\s[^>]*)?\s*(?:\/>|><\/x-vite>)/gi,
-    (_match, attrs) => {
-      const srcMatch = attrs?.match(/(?:src|entries)=(?:"([^"]*)"|'([^']*)')/);
-      const val = srcMatch ? srcMatch[1] || srcMatch[2] : "";
-      if (val.startsWith("[") && val.endsWith("]")) {
-        return `<%- vite(${val}) %>`;
-      }
-      return `<%- vite('${escapeJsString(val)}') %>`;
-    }
-  );
-  compiled = compiled.replace(
-    /<x-vite-react-refresh\s*(?:\/>|><\/x-vite-react-refresh>)|<x-viteReactRefresh\s*(?:\/>|><\/x-viteReactRefresh>)/gi,
-    "<%- viteReactRefresh() %>"
-  );
-  compiled = compiled.replace(/<x-csrf\s*(?:\/>|><\/x-csrf>)/gi, "<%- csrf() %>");
-  compiled = compiled.replace(
-    /<x-routes(\s[^>]*)?\s*(?:\/>|><\/x-routes>)/gi,
-    (_match, attrs) => {
-      const groupMatch = attrs?.match(/group=(?:"([^"]*)"|'([^']*)')/);
-      const group = groupMatch ? groupMatch[1] || groupMatch[2] : void 0;
-      return group ? `<%- routes('${escapeJsString(group)}') %>` : `<%- routes() %>`;
-    }
-  );
-  compiled = compiled.replace(/@inertiaHead\b/g, "<%- inertiaHead() %>");
-  compiled = compiled.replace(/@(inertiaScript|inertiaData)(\([^)]*\))?(?!\w)/g, (_match, _d, args) => {
-    return args ? `<%- inertiaScript${args} %>` : `<%- inertiaScript() %>`;
-  });
-  compiled = compiled.replace(/@inertia(\([^)]*\))?(?!\w)/g, (_match, args) => {
-    return args ? `<%- inertia${args} %>` : `<%- inertia() %>`;
-  });
-  compiled = compiled.replace(/@viteReactRefresh\b/g, "<%- viteReactRefresh() %>");
-  compiled = compiled.replace(/@vite\(([^)]*(?:\([^)]*\)[^)]*)*)\)/g, (_match, args) => {
-    return `<%- vite(${args.trim()}) %>`;
-  });
-  compiled = compiled.replace(/@csrf\b/g, "<%- csrf() %>");
-  compiled = compiled.replace(/@routes(\([^)]*\))?(?!\w)/g, (_match, args) => {
-    return args ? `<%- routes${args} %>` : `<%- routes() %>`;
-  });
-  compiled = compiled.replace(/@json\(([^)]*(?:\([^)]*\)[^)]*)*)\)/g, (_match, args) => {
-    return `<%- json(${args.trim()}) %>`;
-  });
-  const allDirectives = { ...customDirectives, ...localDirectives || {} };
-  for (const [name, handler] of Object.entries(allDirectives)) {
-    const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const pattern = new RegExp(`@${escapedName}(\\([^)]*(?:\\([^)]*\\)[^)]*)*\\))?(?!\\w)`, "g");
-    compiled = compiled.replace(pattern, (_match, args) => {
-      return handler(args ? args.slice(1, -1).trim() : "", {});
-    });
-  }
-  return compiled;
-}
-
 // src/logger.ts
 var DEFAULT_PREFIX = "@arponascension/express-inertia";
 function createConsoleLogger(prefix) {
@@ -398,7 +318,7 @@ function createInertiaEngine(options) {
   const templateTimestamps = /* @__PURE__ */ new Map();
   engineCaches.add(templateCache);
   engineTimestamps.add(templateTimestamps);
-  return function inertiaBladeEngine(filePath, rawOptions, callback) {
+  return function inertiaEjsEngine(filePath, rawOptions, callback) {
     try {
       const template = options?.templateSource;
       const hasTemplateSource = template !== void 0;
@@ -421,7 +341,7 @@ function createInertiaEngine(options) {
       }
       if (!compiledTemplate) {
         const templateSource = template !== void 0 ? template : fs__default.default.readFileSync(filePath, "utf-8");
-        const compiledSource = options?.compileTemplate ? options.compileTemplate(templateSource) : compileBladeDirectives(templateSource, options?.directives);
+        const compiledSource = options?.compileTemplate ? options.compileTemplate(templateSource) : templateSource;
         compiledTemplate = ejs__default.default.compile(compiledSource, {
           filename: filePath,
           cache: false,