npm - @coherent.js/integrations - Versions diffs - 1.1.2 → 2.0.0 - Mend

@coherent.js/integrations 1.1.2 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +31 -0
package/package.json +11 -7
package/src/astro/index.js +2 -1
package/src/astro/server.js +12 -0
package/src/express/coherent-express.js +151 -45
package/src/express/index.js +6 -11
package/src/fastify/coherent-fastify.js +45 -23
package/src/koa/coherent-koa.js +37 -9
package/src/nextjs/coherent-nextjs.js +67 -36
package/src/remix/index.js +17 -5
package/src/sveltekit/index.js +40 -16
package/types/astro/index.d.ts +41 -0
package/types/astro/server.d.ts +9 -0
package/types/express/index.d.ts +74 -16
package/types/fastify/index.d.ts +30 -21
package/types/koa/index.d.ts +97 -0
package/types/nextjs/index.d.ts +22 -4
package/types/remix/index.d.ts +68 -0
package/types/sveltekit/index.d.ts +68 -0

package/README.md CHANGED Viewed

@@ -12,6 +12,12 @@ Framework integration adapters for Coherent.js — bridges between your chosen H
 - `@coherent.js/integrations/remix` — Remix adapter (added in 1.0.0)
 - `@coherent.js/integrations/sveltekit` — SvelteKit adapter (added in 1.0.0)
+**Stability:** the Astro, Remix and SvelteKit adapters are young. Their tests run a real
+`astro build`, compile and server-render a component with the Svelte compiler, and server-render
+the Remix wrapper with React, but the adapters have seen little production use. The Express,
+Fastify and Koa adapters are tested over real HTTP requests, and the Next.js adapter with Web
+`Request`/`Response` objects and `react-dom/server`.
 ## Migration from pre-1.0
 Each framework previously shipped as its own package (`@coherent.js/express`, etc.). Migrate by changing import paths:
@@ -32,6 +38,31 @@ pnpm add express   # or fastify / koa / next / etc. — only the ones you use
 Framework peer dependencies are declared optional, so consumers only install the framework(s) they actually use.
+## Rendering components (Express, Fastify, Koa)
+Render explicitly; plain objects are sent as JSON:
+```js
+// Express
+setupCoherent(app, { template: '<!DOCTYPE html>\n{{content}}' });
+app.get('/', (req, res) => res.coherent(HomePage()));
+app.get('/api/users', (req, res) => res.send({ users })); // JSON
+// Fastify
+await fastify.register(setupCoherent, { template });
+fastify.get('/', async (request, reply) => reply.coherent(HomePage()));
+// Koa
+setupCoherent(app, { template });
+router.get('/', (ctx) => ctx.coherent(HomePage()));
+```
+`autoRender: true` restores the earlier behavior of rendering any
+component-shaped object passed to `res.send` / returned from a Fastify handler
+/ assigned to `ctx.body`. It is off by default because "component-shaped"
+means "has exactly one key", which matches JSON such as `{ ok: true }` or
+`{ error: 'Invalid credentials' }` too.
 ## License
 MIT

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@coherent.js/integrations",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "Framework integration adapters for Coherent.js: Express, Fastify, Koa, Next.js, Astro, Remix, SvelteKit.",
   "type": "module",
   "exports": {
@@ -13,6 +13,7 @@
       "default": "./src/fastify/index.js"
     },
     "./koa": {
+      "types": "./types/koa/index.d.ts",
       "default": "./src/koa/index.js"
     },
     "./nextjs": {
@@ -20,12 +21,19 @@
       "default": "./src/nextjs/index.js"
     },
     "./astro": {
+      "types": "./types/astro/index.d.ts",
       "default": "./src/astro/index.js"
     },
+    "./astro/server": {
+      "types": "./types/astro/server.d.ts",
+      "default": "./src/astro/server.js"
+    },
     "./remix": {
+      "types": "./types/remix/index.d.ts",
       "default": "./src/remix/index.js"
     },
     "./sveltekit": {
+      "types": "./types/sveltekit/index.d.ts",
       "default": "./src/sveltekit/index.js"
     }
   },
@@ -51,20 +59,16 @@
     "fastify-plugin": "^6.0.0"
   },
   "peerDependencies": {
-    "@remix-run/server-runtime": ">=2.0.0",
+    "@coherent.js/core": "^2.0.0",
     "@sveltejs/kit": ">=2.0.0",
     "astro": ">=4.0.0",
     "express": ">=4.18.0 < 6.0.0",
     "fastify": ">=4.0.0 < 6.0.0",
     "koa": ">=2.13.0 < 4.0.0",
     "next": ">=13.0.0",
-    "react": ">=18.0.0",
-    "@coherent.js/core": "^1.1.2"
+    "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {
-    "@remix-run/server-runtime": {
-      "optional": true
-    },
     "@sveltejs/kit": {
       "optional": true
     },

package/src/astro/index.js CHANGED Viewed

@@ -30,7 +30,8 @@ export function createAstroIntegration(options = {}) {
       'astro:config:setup': ({ addRenderer, updateConfig }) => {
         addRenderer({
           name: '@coherent.js/integrations/astro',
-          serverEntrypoint: '@coherent.js/integrations/astro',
+          // Astro imports this module's default export as the SSR renderer.
+          serverEntrypoint: '@coherent.js/integrations/astro/server',
         });
         if (options.hydrate) {

package/src/astro/server.js ADDED Viewed

@@ -0,0 +1,12 @@
+// src/astro/server.js
+//
+// Astro server entrypoint for @coherent.js/integrations/astro.
+//
+// `createAstroIntegration()` registers this module with `addRenderer({
+// serverEntrypoint })`. Astro imports its *default export* as the SSR
+// renderer (`{ name, check, renderToStaticMarkup }`), so it must have one —
+// without it `astro build` fails with `"default" is not exported`.
+import { createRenderer } from './index.js';
+export default createRenderer();

package/src/express/coherent-express.js CHANGED Viewed

@@ -3,54 +3,90 @@
  * Provides middleware and utilities for using Coherent.js with Express
  */
+import { pathToFileURL } from 'node:url';
 import {
   render,
   importPeerDependency,
   renderWithTemplate,
-  renderComponentFactory,
   isCoherentComponent
 } from '@coherent.js/core';
+const DEFAULT_TEMPLATE = '<!DOCTYPE html>\n{{content}}';
 /**
- * Coherent.js Express middleware
- * Automatically renders Coherent.js components and handles errors
+ * Coherent.js Express middleware.
+ *
+ * Adds `res.coherent(component, renderOptions?)`, which renders a Coherent.js
+ * component (wrapped in `template`) and sends it as `text/html`. Rendering
+ * errors are forwarded to Express error handling, like `res.render` does.
+ *
+ * With `autoRender: true` it additionally overrides `res.send` so that any
+ * object that looks like a component is rendered to HTML. That detection is
+ * a heuristic -- every single-key object qualifies, so `res.send({ ok: true })`
+ * or `res.json({ users })` routed through `res.send` would be rendered as
+ * `<ok>` / `<users>` instead of serialized as JSON. It is off by default; only
+ * enable it for apps that never send single-key JSON objects.
  *
  * @param {Object} options - Configuration options
- * @param {boolean} options.enablePerformanceMonitoring - Enable performance monitoring
- * @param {string} options.template - HTML template with {{content}} placeholder
+ * @param {boolean} [options.enablePerformanceMonitoring=false] - Enable performance monitoring
+ * @param {string} [options.template] - HTML template with {{content}} placeholder
+ * @param {boolean} [options.autoRender=false] - Render component-shaped objects passed to `res.send`
  * @returns {Function} Express middleware function
  */
 export function coherentMiddleware(options = {}) {
   const {
     enablePerformanceMonitoring = false,
-    template = '<!DOCTYPE html>\n{{content}}'
+    template = DEFAULT_TEMPLATE,
+    autoRender = false
   } = options;
   return (req, res, next) => {
     // Store original send method
     const originalSend = res.send;
-    // Override send method to handle Coherent.js objects
-    res.send = function(data) {
-      // If data is a Coherent.js object (plain object with a single key), render it
-      if (isCoherentComponent(data)) {
-        try {
-          // Use shared rendering utility
-          const finalHtml = renderWithTemplate(data, { enablePerformanceMonitoring, template });
-          // Set content type and send HTML
-          res.set('Content-Type', 'text/html');
-          return originalSend.call(this, finalHtml);
-        } catch (_error) {
-          console.error('Coherent.js rendering _error:', _error);
-          return next(_error);
-        }
+    // Explicit rendering: res.coherent(component, { template?, enablePerformanceMonitoring? })
+    res.coherent = function coherent(component, renderOptions = {}) {
+      let finalHtml;
+      try {
+        finalHtml = renderWithTemplate(component, {
+          enablePerformanceMonitoring: renderOptions.enablePerformanceMonitoring ?? enablePerformanceMonitoring,
+          template: renderOptions.template ?? template
+        });
+      } catch (_error) {
+        // Same contract as res.render(): hand the error to the app's error
+        // middleware. req.next is the router's current `next`, so this works
+        // from sync, async (Express 4 and 5) and callback code alike.
+        (req.next ?? next)(_error);
+        return this;
       }
-      // For non-Coherent.js data, use original send method
-      return originalSend.call(this, data);
+      this.set('Content-Type', 'text/html; charset=utf-8');
+      return originalSend.call(this, finalHtml);
     };
+    if (autoRender) {
+      // Override send method to handle Coherent.js objects
+      res.send = function(data) {
+        // If data looks like a Coherent.js object (plain object with a single key), render it
+        if (isCoherentComponent(data)) {
+          try {
+            // Use shared rendering utility
+            const finalHtml = renderWithTemplate(data, { enablePerformanceMonitoring, template });
+            // Set content type and send HTML
+            res.set('Content-Type', 'text/html');
+            return originalSend.call(this, finalHtml);
+          } catch (_error) {
+            console.error('Coherent.js rendering error:', _error);
+            return next(_error);
+          }
+        }
+        // For non-Coherent.js data, use original send method
+        return originalSend.call(this, data);
+      };
+    }
     next();
   };
 }
@@ -58,6 +94,9 @@ export function coherentMiddleware(options = {}) {
 /**
  * Create an Express route handler for Coherent.js components
  *
+ * The factory receives `(req, res, next)`. If it answers the request itself
+ * (`res.redirect()`, `res.json()`, ...) nothing further is sent.
+ *
  * @param {Function} componentFactory - Function that returns a Coherent.js component
  * @param {Object} options - Handler options
  * @returns {Function} Express route handler
@@ -65,63 +104,130 @@ export function coherentMiddleware(options = {}) {
 export function createCoherentHandler(componentFactory, options = {}) {
   return async (req, res, next) => {
     try {
-      // Use shared rendering utility
-      const finalHtml = await renderComponentFactory(
-        componentFactory,
-        [req, res, next],
-        options
-      );
+      const component = await componentFactory(req, res, next);
+      // The factory already responded: sending again would throw
+      // ERR_HTTP_HEADERS_SENT.
+      if (res.headersSent) return;
+      if (!component) {
+        throw new Error('Component factory returned null/undefined');
+      }
+      const finalHtml = renderWithTemplate(component, options);
       // Send HTML response
       res.set('Content-Type', 'text/html');
       res.send(finalHtml);
     } catch (_error) {
-      console.error('Coherent.js handler _error:', _error);
+      console.error('Coherent.js handler error:', _error);
       next(_error);
     }
   };
 }
+/** Keys Express merges into the view-engine options besides the locals. */
+const EXPRESS_VIEW_OPTION_KEYS = new Set(['settings', '_locals', 'cache']);
+/** View files that are loaded as ES modules rather than used as markers. */
+const VIEW_MODULE_EXTENSION = /\.(?:js|mjs|cjs)$/;
 /**
- * Enhanced Express engine for Coherent.js views
+ * Resolve the component for a view.
  *
- * @param {string} filePath - Path to view file (not used in Coherent.js)
- * @param {Object} options - View options containing Coherent.js component
+ * A JavaScript view module's default export is the component: a function is
+ * called with the render locals, anything else is used as-is. Any other view
+ * file (e.g. an empty `home.coherent`) only satisfies Express's lookup, and
+ * the locals themselves are the component: `res.render('home', { div: ... })`.
+ */
+async function resolveViewComponent(filePath, locals) {
+  if (!VIEW_MODULE_EXTENSION.test(filePath)) {
+    return locals;
+  }
+  const viewModule = await import(pathToFileURL(filePath).href);
+  if (!('default' in viewModule)) {
+    throw new Error(`Coherent.js view "${filePath}" has no default export`);
+  }
+  const view = viewModule.default;
+  return typeof view === 'function' ? view(locals) : view;
+}
+/**
+ * Express view engine for Coherent.js views.
+ *
+ * Register it with `setupCoherent(app, { useEngine: true })`, or directly with
+ * `app.engine('js', enhancedExpressEngine)` to render view modules
+ * (`views/home.js` exporting a component or `(locals) => component` as
+ * default). Express's own `settings`, `_locals` and `cache` keys are removed
+ * before the locals reach the component.
+ *
+ * @param {string} filePath - Absolute path of the view file Express resolved
+ * @param {Object} options - Render locals merged by Express
  * @param {Function} callback - Callback function
  */
 export function enhancedExpressEngine(filePath, options, callback) {
-  try {
-    // Render Coherent.js component from options
-    const html = render(options);
-    callback(null, html);
-  } catch (_error) {
-    callback(_error);
+  const locals = {};
+  for (const [key, value] of Object.entries(options ?? {})) {
+    if (!EXPRESS_VIEW_OPTION_KEYS.has(key)) locals[key] = value;
   }
+  resolveViewComponent(filePath, locals).then(
+    (component) => {
+      let html;
+      try {
+        html = render(component);
+      } catch (_error) {
+        callback(_error);
+        return;
+      }
+      callback(null, html);
+    },
+    (_error) => callback(_error)
+  );
 }
 /**
  * Setup Coherent.js with Express app
  *
+ * Installs {@link coherentMiddleware} (so routes can call `res.coherent()`)
+ * and, when asked to, registers {@link enhancedExpressEngine} as a view
+ * engine. The engine is opt-in so it does not take over an app's existing
+ * `view engine`; it only becomes the default engine when none is set.
+ *
  * @param {Object} app - Express app instance
  * @param {Object} options - Setup options
+ * @param {boolean} [options.useMiddleware=true] - Install coherentMiddleware
+ * @param {boolean} [options.useEngine=false] - Register the view engine
+ * @param {string} [options.engineName='coherent'] - View engine name / file extension
+ *   (use 'js' to render `views/*.js` modules)
+ * @param {boolean} [options.enablePerformanceMonitoring=false] - Enable performance monitoring
+ * @param {string} [options.template] - HTML template with {{content}} placeholder
+ * @param {boolean} [options.autoRender=false] - Render component-shaped objects passed to `res.send`
+ *   (see coherentMiddleware for why this is opt-in)
  */
 export function setupCoherent(app, options = {}) {
   const {
     useMiddleware = true,
-    useEngine = true,
+    useEngine = false,
     engineName = 'coherent',
-    enablePerformanceMonitoring = false
+    enablePerformanceMonitoring = false,
+    template,
+    autoRender = false
   } = options;
-  // Register enhanced engine
+  // Register the view engine (opt-in); never override an existing default engine
   if (useEngine) {
     app.engine(engineName, enhancedExpressEngine);
-    app.set('view engine', engineName);
+    if (!app.get('view engine')) {
+      app.set('view engine', engineName);
+    }
   }
-  // Use middleware for automatic rendering
+  // Install the middleware (res.coherent, plus res.send auto-rendering when opted in)
   if (useMiddleware) {
-    app.use(coherentMiddleware({ enablePerformanceMonitoring }));
+    app.use(coherentMiddleware({ enablePerformanceMonitoring, template, autoRender }));
   }
 }

package/src/express/index.js CHANGED Viewed

@@ -8,7 +8,7 @@
 // compatibility with consumers that imported it from the legacy
 // @coherent.js/express package.
-import { render } from '@coherent.js/core';
+import { enhancedExpressEngine } from './coherent-express.js';
 export {
   coherentMiddleware,
@@ -18,19 +18,14 @@ export {
   createExpressIntegration
 } from './coherent-express.js';
+export { default } from './coherent-express.js';
 /**
- * Factory returning a classic Express view engine that renders a Coherent.js
- * component tree passed via the `options` argument.
+ * Factory returning a classic Express view engine for Coherent.js views
+ * (see `enhancedExpressEngine`): `app.engine('js', expressEngine())`.
  *
  * @returns {(filePath: string, options: unknown, callback: (err: Error | null, html?: string) => void) => void}
  */
 export function expressEngine() {
-  return (filePath, options, callback) => {
-    try {
-      const html = render(options);
-      callback(null, html);
-    } catch (_error) {
-      callback(_error);
-    }
-  };
+  return enhancedExpressEngine;
 }

package/src/fastify/coherent-fastify.js CHANGED Viewed

@@ -24,12 +24,22 @@ import {
  * @param {Object} options - Plugin options
  * @param {boolean} [options.enablePerformanceMonitoring] - Enable performance monitoring
  * @param {string} [options.template] - HTML template with {{content}} placeholder
+ * @param {boolean} [options.autoRender] - Render component-shaped handler return values
+ *   (see the preSerialization hook below for why this is opt-in)
  * @param {Function} done - Callback to signal plugin registration completion
  */
 function coherentFastifyImpl(fastify, options = {}, done) {
+  if (typeof done !== 'function') {
+    throw new TypeError(
+      'coherentFastify/setupCoherent is a Fastify plugin and cannot be called directly: ' +
+      'use `await fastify.register(setupCoherent, options)`.'
+    );
+  }
   const {
     enablePerformanceMonitoring = false,
-    template = '<!DOCTYPE html>\n{{content}}'
+    template = '<!DOCTYPE html>\n{{content}}',
+    autoRender = false
   } = options;
   // Add decorator to check if an object is a Coherent.js component
@@ -48,39 +58,47 @@ function coherentFastifyImpl(fastify, options = {}, done) {
       template: renderTemplate = template
     } = renderOptions;
+    let finalHtml;
     try {
-      const finalHtml = renderWithTemplate(component, {
+      finalHtml = renderWithTemplate(component, {
         enablePerformanceMonitoring: renderPerformanceMonitoring,
         template: renderTemplate
       });
-      this.header('Content-Type', 'text/html; charset=utf-8');
-      this.send(finalHtml);
     } catch (_error) {
-      console.error('Coherent.js rendering _error:', _error);
-      this.status(500).send({
-        _error: 'Internal Server Error',
-        message: _error.message
-      });
+      // Sending an Error runs Fastify's error pipeline (onError hooks, the
+      // app's setErrorHandler, its logger) instead of answering with the raw
+      // message.
+      return this.send(_error);
     }
+    this.header('Content-Type', 'text/html; charset=utf-8');
+    return this.send(finalHtml);
   });
-  // Auto-render: if a handler returns a Coherent.js component object,
-  // intercept before serialization and replace the payload with HTML.
+  // Auto-render (opt-in): if a handler returns a Coherent.js component
+  // object, intercept before serialization and replace the payload with HTML.
+  //
+  // Off by default because detection is a heuristic -- every single-key
+  // object qualifies, so `return { ok: true }` or a 401 `{ error: '...' }`
+  // would be rendered as `<ok>` / `<error>` HTML even with a JSON response
+  // schema. Use `reply.coherent(component)` for explicit rendering instead.
   //
   // - `onSend` runs after JSON serialization (payload is already a string),
   //   so the component object would never be detected there.
   // - `preSerialization` runs before serialization. We render to HTML and
   //   install an identity serializer for this reply, so Fastify doesn't
   //   JSON-stringify the HTML string we just produced.
-  fastify.addHook('preSerialization', async (request, reply, payload) => {
-    if (reply.isCoherentObject?.(payload)) {
-      const finalHtml = renderWithTemplate(payload, { enablePerformanceMonitoring, template });
-      reply.header('Content-Type', 'text/html; charset=utf-8');
-      reply.serializer((p) => p);
-      return finalHtml;
-    }
-    return payload;
-  });
+  if (autoRender) {
+    fastify.addHook('preSerialization', async (request, reply, payload) => {
+      if (reply.isCoherentObject?.(payload)) {
+        const finalHtml = renderWithTemplate(payload, { enablePerformanceMonitoring, template });
+        reply.header('Content-Type', 'text/html; charset=utf-8');
+        reply.serializer((p) => p);
+        return finalHtml;
+      }
+      return payload;
+    });
+  }
   done();
 }
@@ -88,10 +106,14 @@ function coherentFastifyImpl(fastify, options = {}, done) {
 /**
  * Fastify plugin for Coherent.js — wrapped with fastify-plugin so decorators
  * and hooks apply to the parent (root) context. Register at the top of your
- * app, then define routes that return Coherent.js component objects:
+ * app, then render components explicitly with `reply.coherent()`:
  *
  *   await fastify.register(coherentFastify, { template: APP_HTML_TEMPLATE });
- *   fastify.get('/', async () => HomePage({}));
+ *   fastify.get('/', async (request, reply) => reply.coherent(HomePage({})));
+ *
+ * Pass `autoRender: true` to also render component objects returned from
+ * handlers (`fastify.get('/', async () => HomePage({}))`); see the
+ * preSerialization hook above for why that is not the default.
  */
 export const coherentFastify = fp(coherentFastifyImpl, {
   name: 'coherent-fastify',
@@ -123,7 +145,7 @@ export function createHandler(componentFactory, options = {}) {
       reply.header('Content-Type', 'text/html; charset=utf-8');
       return finalHtml;
     } catch (_error) {
-      console.error('Coherent.js handler _error:', _error);
+      console.error('Coherent.js handler error:', _error);
       throw _error;
     }
   };

package/src/koa/coherent-koa.js CHANGED Viewed

@@ -11,25 +11,48 @@ import {
 } from '@coherent.js/core';
 /**
- * Coherent.js Koa middleware
- * Automatically renders Coherent.js components and handles errors
+ * Coherent.js Koa middleware.
+ *
+ * Adds `ctx.coherent(component, renderOptions?)`, which renders a Coherent.js
+ * component (wrapped in `template`) into `ctx.body` as `text/html`. Rendering
+ * errors are thrown, so they reach the app's error-handling middleware.
+ *
+ * With `autoRender: true` it additionally renders any `ctx.body` that looks
+ * like a component once downstream middleware has finished. That detection
+ * is a heuristic -- every single-key object qualifies, so
+ * `ctx.body = { ok: true }` would be rendered as `<ok>` instead of serialized
+ * as JSON. It is off by default; only enable it for apps that never respond
+ * with single-key JSON objects.
  *
  * @param {Object} options - Configuration options
- * @param {boolean} options.enablePerformanceMonitoring - Enable performance monitoring
- * @param {string} options.template - HTML template with {{content}} placeholder
+ * @param {boolean} [options.enablePerformanceMonitoring=false] - Enable performance monitoring
+ * @param {string} [options.template] - HTML template with {{content}} placeholder
+ * @param {boolean} [options.autoRender=false] - Render component-shaped `ctx.body` values
  * @returns {Function} Koa middleware function
  */
 export function coherentKoaMiddleware(options = {}) {
   const {
     enablePerformanceMonitoring = false,
-    template = '<!DOCTYPE html>\n{{content}}'
+    template = '<!DOCTYPE html>\n{{content}}',
+    autoRender = false
   } = options;
   return async (ctx, next) => {
+    // Explicit rendering: ctx.coherent(component, { template?, enablePerformanceMonitoring? })
+    ctx.coherent = (component, renderOptions = {}) => {
+      const finalHtml = renderWithTemplate(component, {
+        enablePerformanceMonitoring: renderOptions.enablePerformanceMonitoring ?? enablePerformanceMonitoring,
+        template: renderOptions.template ?? template
+      });
+      ctx.type = 'html';
+      ctx.body = finalHtml;
+      return finalHtml;
+    };
     await next();
-    // If response body is a Coherent.js object, render it
-    if (isCoherentComponent(ctx.body)) {
+    // Opt-in: if the response body looks like a Coherent.js object, render it
+    if (autoRender && isCoherentComponent(ctx.body)) {
       try {
         // Use shared rendering utility
         const finalHtml = renderWithTemplate(ctx.body, { enablePerformanceMonitoring, template });
@@ -38,7 +61,7 @@ export function coherentKoaMiddleware(options = {}) {
         ctx.type = 'text/html';
         ctx.body = finalHtml;
       } catch (_error) {
-        console.error('Coherent.js rendering _error:', _error);
+        console.error('Coherent.js rendering error:', _error);
         throw _error;
       }
     }
@@ -66,7 +89,7 @@ export function createHandler(componentFactory, options = {}) {
       ctx.type = 'text/html';
       ctx.body = finalHtml;
     } catch (_error) {
-      console.error('Coherent.js handler _error:', _error);
+      console.error('Coherent.js handler error:', _error);
       throw _error;
     }
   };
@@ -75,8 +98,13 @@ export function createHandler(componentFactory, options = {}) {
 /**
  * Setup Coherent.js with Koa app
  *
+ * Installs {@link coherentKoaMiddleware}, so downstream middleware can call
+ * `ctx.coherent(component)`. Every option except `useMiddleware` is forwarded
+ * to the middleware, including `template` and `autoRender`.
+ *
  * @param {Object} app - Koa app instance
  * @param {Object} options - Setup options
+ * @param {boolean} [options.useMiddleware=true] - Install coherentKoaMiddleware
  */
 export function setupCoherent(app, options = {}) {
   const { useMiddleware = true, ...middlewareOptions } = options;