@coherent.js/integrations 1.1.2 → 2.0.0

package/src/nextjs/coherent-nextjs.js

@@ -6,10 +6,44 @@
 import {
   render,
   performanceMonitor,
-  importPeerDependency,
   renderComponentFactory
 } from '@coherent.js/core';
 
+function missingPeer(packageName, integrationName, cause) {
+  const error = new Error(
+    `${integrationName} requires the '${packageName}' package to be installed.\n` +
+    `Please install it with: npm install ${packageName} (or pnpm add / yarn add)`
+  );
+  error.cause = cause;
+  return error;
+}
+
+/**
+ * The React module to build elements with.
+ *
+ * An injected `options.React` wins. Otherwise React is imported from *this*
+ * package: it declares `react` as an optional peer, so package managers link
+ * the app's copy next to it. (core's `importPeerDependency` imports relative
+ * to @coherent.js/core instead, which cannot see the app's `react` under
+ * pnpm's isolated layout.) The literal specifier keeps it bundler-friendly.
+ *
+ * @param {Object} [injected] - A React module or namespace supplied by the app
+ * @param {string} integrationName - Used in the error message
+ * @returns {Promise<Object>} Object exposing createElement / useState / useEffect
+ */
+async function loadReact(injected, integrationName) {
+  let mod = injected;
+  if (!mod) {
+    try {
+      mod = await import('react');
+    } catch (_error) {
+      throw missingPeer('react', integrationName, _error);
+    }
+  }
+  // Namespace imports of CommonJS React carry the API on `default`.
+  return typeof mod.createElement === 'function' ? mod : mod.default;
+}
+
 /**
  * Create a Next.js API route handler for Coherent.js components
  *
@@ -33,8 +67,8 @@ export function createCoherentNextHandler(componentFactory, options = {}) {
       res.setHeader('Content-Type', 'text/html; charset=utf-8');
       res.status(200).send(finalHtml);
     } catch (_error) {
-      console.error('Coherent.js Next.js handler _error:', _error);
-      res.status(500).json({ _error: _error.message });
+      console.error('Coherent.js Next.js handler error:', _error);
+      res.status(500).json({ error: _error.message });
     }
   };
 }
@@ -42,17 +76,21 @@ export function createCoherentNextHandler(componentFactory, options = {}) {
 /**
  * Create a Next.js App Router route handler for Coherent.js components
  *
- * @param {Function} componentFactory - Function that returns a Coherent.js component
+ * The factory receives the same `(request, context)` pair Next.js passes to
+ * route handlers, so dynamic segments are available as `context.params`
+ * (a Promise since Next.js 15).
+ *
+ * @param {Function} componentFactory - `(request, context) => component`
  * @param {Object} options - Handler options
  * @returns {Function} Next.js App Router route handler
  */
 export function createCoherentAppRouterHandler(componentFactory, options = {}) {
-  return async function handler(request) {
+  return async function handler(request, context) {
     try {
       // Use shared rendering utility
       const finalHtml = await renderComponentFactory(
         componentFactory,
-        [request],
+        [request, context],
         options
       );
 
@@ -62,9 +100,9 @@ export function createCoherentAppRouterHandler(componentFactory, options = {}) {
         headers: { 'Content-Type': 'text/html; charset=utf-8' }
       });
     } catch (_error) {
-      console.error('Coherent.js Next.js App Router handler _error:', _error);
+      console.error('Coherent.js Next.js App Router handler error:', _error);
       return new Response(
-        JSON.stringify({ _error: _error.message }),
+        JSON.stringify({ error: _error.message }),
         {
           status: 500,
           headers: { 'Content-Type': 'application/json' }
@@ -79,22 +117,16 @@ export function createCoherentAppRouterHandler(componentFactory, options = {}) {
  *
  * @param {Function} componentFactory - Function that returns a Coherent.js component
  * @param {Object} options - Component options
- * @returns {Function} Next.js Server Component
+ * @param {boolean} [options.enablePerformanceMonitoring=false] - Enable performance monitoring
+ * @param {Object} [options.React] - React module to use instead of importing `react`
+ * @returns {Promise<Function>} Next.js Server Component
  */
 export async function createCoherentServerComponent(componentFactory, options = {}) {
   const {
     enablePerformanceMonitoring = false
   } = options;
 
-  // Import React using dependency utilities
-  let React;
-  try {
-    React = await importPeerDependency('react', 'React');
-  } catch (_error) {
-    throw new Error(
-      `Next.js Server Component integration requires React. ${  _error.message}`
-    );
-  }
+  const React = await loadReact(options.React, 'Next.js Server Component integration');
 
   return async function CoherentServerComponent(props) {
     try {
@@ -104,7 +136,7 @@ export async function createCoherentServerComponent(componentFactory, options =
       );
 
       if (!component) {
-        return React.default.createElement('div', null, 'Error: Component factory returned null/undefined');
+        return React.createElement('div', null, 'Error: Component factory returned null/undefined');
       }
 
       // Render component
@@ -118,12 +150,12 @@ export async function createCoherentServerComponent(componentFactory, options =
       }
 
       // Return dangerouslySetInnerHTML to render HTML
-      return React.default.createElement('div', {
+      return React.createElement('div', {
         dangerouslySetInnerHTML: { __html: html }
       });
     } catch (_error) {
-      console.error('Coherent.js Next.js Server Component _error:', _error);
-      return React.default.createElement('div', null, `Error: ${_error.message}`);
+      console.error('Coherent.js Next.js Server Component error:', _error);
+      return React.createElement('div', null, `Error: ${_error.message}`);
     }
   };
 }
@@ -133,22 +165,16 @@ export async function createCoherentServerComponent(componentFactory, options =
  *
  * @param {Function} componentFactory - Function that returns a Coherent.js component
  * @param {Object} options - Component options
- * @returns {Function} Next.js Client Component
+ * @param {boolean} [options.enablePerformanceMonitoring=false] - Enable performance monitoring
+ * @param {Object} [options.React] - React module to use instead of importing `react`
+ * @returns {Promise<Function>} Next.js Client Component
  */
 export async function createCoherentClientComponent(componentFactory, options = {}) {
   const {
     enablePerformanceMonitoring = false
   } = options;
 
-  // Import React using dependency utilities
-  let React;
-  try {
-    React = await importPeerDependency('react', 'React');
-  } catch (_error) {
-    throw new Error(
-      `Next.js Client Component integration requires React. ${  _error.message}`
-    );
-  }
+  const React = await loadReact(options.React, 'Next.js Client Component integration');
 
   return function CoherentClientComponent(props) {
     const [html, setHtml] = React.useState('');
@@ -178,7 +204,7 @@ export async function createCoherentClientComponent(componentFactory, options =
 
           setHtml(renderedHtml);
         } catch (_error) {
-          console.error('Coherent.js Next.js Client Component _error:', _error);
+          console.error('Coherent.js Next.js Client Component error:', _error);
           setHtml(`Error: ${_error.message}`);
         }
       }
@@ -201,9 +227,14 @@ export async function createCoherentClientComponent(componentFactory, options =
  */
 export async function createNextIntegration(options = {}) {
   try {
-    // Verify Next.js and React are available
-    await importPeerDependency('next', 'Next.js');
-    await importPeerDependency('react', 'React');
+    // Verify Next.js and React are available, resolved from this package
+    // (see loadReact for why not core's importPeerDependency)
+    try {
+      await import('next');
+    } catch (_error) {
+      throw missingPeer('next', 'Next.js integration', _error);
+    }
+    await loadReact(options.React, 'Next.js integration');
 
     return {
       createCoherentNextHandler: (componentFactory, handlerOptions = {}) =>

package/src/remix/index.js

@@ -3,11 +3,13 @@
 // Public entry point for @coherent.js/integrations/remix. Provides SSR
 // integration and loader utilities for Remix projects.
 //
-// Remix must be installed as a peer dependency to use this integration.
+// Remix (and therefore React) must be installed as a peer dependency to use
+// this integration.
 //
 // Usage:
 //   import { createRemixAdapter } from '@coherent.js/integrations/remix';
 
+import { createElement } from 'react';
 import { render } from '@coherent.js/core';
 
 /**
@@ -75,12 +77,22 @@ export function createRemixAdapter(_options = {}) {
 /**
  * HOC: Wrap a Coherent.js component for use in Remix routes
  *
- * @param {Function} Component - Coherent.js component function
- * @returns {Function} Remix-compatible component
+ * Returns a React component that renders the Coherent.js markup inside a
+ * wrapper element via `dangerouslySetInnerHTML`. Returning the HTML string
+ * itself would make React escape it and show the tags as text. The
+ * Coherent.js renderer escapes text and attribute values, so only markup the
+ * component describes (or passes through its explicit `html` field) is raw.
+ *
+ * @param {Function|Object} Component - Coherent.js component function or object
+ * @param {Object} [options] - Wrapper options
+ * @param {string} [options.as='div'] - Tag name of the wrapper element
+ * @returns {Function} Remix-compatible React component
  */
-export function withCoherent(Component) {
+export function withCoherent(Component, options = {}) {
+  const { as = 'div' } = options;
+
   return function CoherentRemixComponent(props) {
     const def = typeof Component === 'function' ? Component(props) : Component;
-    return render(def);
+    return createElement(as, { dangerouslySetInnerHTML: { __html: render(def) } });
   };
 }

package/src/sveltekit/index.js

@@ -61,10 +61,40 @@ export function createSvelteKitAdapter(_options = {}) {
   };
 }
 
+/** Local name the preprocessor imports Coherent.js's `render` under. */
+const RENDER_IDENTIFIER = '__coherentRender';
+const RENDER_IMPORT = `import { render as ${RENDER_IDENTIFIER} } from '@coherent.js/core';`;
+
+/** `<script context="module">` (Svelte 4) or `<script module>` (Svelte 5). */
+function isModuleScript(attributes) {
+  return /\bcontext\s*=\s*["']?module\b/.test(attributes) || /(?:^|\s)module(?:\s|=|$)/.test(attributes);
+}
+
+/**
+ * Make `RENDER_IDENTIFIER` available to the markup: add the import to the
+ * instance `<script>`, or add an instance script if there is none. Inserted
+ * without newlines so the component's line numbers do not move.
+ */
+function injectRenderImport(code) {
+  // Case-insensitive like HTML: an instance script written <SCRIPT> was
+  // missed, and a second instance script was added next to it.
+  for (const match of code.matchAll(/<script\b([^>]*)>/gi)) {
+    if (!isModuleScript(match[1])) {
+      const at = match.index + match[0].length;
+      return `${code.slice(0, at)}${RENDER_IMPORT}${code.slice(at)}`;
+    }
+  }
+  return `<script>${RENDER_IMPORT}</script>${code}`;
+}
+
 /**
  * Create a Svelte preprocessor for Coherent.js templates
  *
- * Transforms inline Coherent.js object syntax within Svelte components.
+ * Replaces each `<coherent>{ ...object literal... }</coherent>` block with
+ * `{@html ...}` of the rendered component, and imports `render` from
+ * `@coherent.js/core` into the component's instance script so the generated
+ * expression resolves. The renderer escapes text content, so `{@html}` only
+ * emits markup the component itself describes.
  *
  * @param {Object} [options] - Preprocessor options
  * @param {string} [options.tag] - Custom tag to process (default: 'coherent')
@@ -76,24 +106,18 @@ export function createPreprocessor(options = {}) {
   return {
     name: 'coherent-preprocessor',
     markup({ content, filename: _filename }) {
-      // Find <coherent> blocks and render them to HTML
+      // Find <coherent> blocks; their content is a JS expression (usually an object literal)
       const regex = new RegExp(`<${tag}>(.*?)</${tag}>`, 'gs');
-      let transformed = content;
-      let match;
-
-      while ((match = regex.exec(content)) !== null) {
-        try {
-          // The content inside <coherent> tags should be a JS object literal
-          // This is a basic transform — production use should handle more cases
-          const objectStr = match[1].trim();
-          transformed = transformed.replace(match[0], `{@html coherentRender(${objectStr})}`);
-        } catch {
-          // Leave unchanged if parsing fails
-        }
-      }
+      let found = false;
+
+      // Replacer function, so `$&`-style sequences in the block stay literal
+      const transformed = content.replace(regex, (_block, expression) => {
+        found = true;
+        return `{@html ${RENDER_IDENTIFIER}(${expression.trim()})}`;
+      });
 
       return {
-        code: transformed,
+        code: found ? injectRenderImport(transformed) : content,
         map: null
       };
     }

package/types/astro/index.d.ts

@@ -0,0 +1,41 @@
+// Type definitions for Coherent.js Astro integration.
+//
+// Aligned with the runtime exports of ../../src/astro/index.js.
+
+import type { AstroIntegration } from 'astro';
+import type { CoherentNode, RenderOptions } from '@coherent.js/core';
+
+export interface CoherentAstroOptions {
+  /** Pre-bundle `@coherent.js/client` for client-side hydration. */
+  hydrate?: boolean;
+  /** Custom hydration script path. */
+  hydrateScript?: string;
+}
+
+/** A Coherent.js component: a node, or a function of props returning one. */
+export type CoherentAstroComponent<Props = Record<string, unknown>> =
+  | CoherentNode
+  | ((props: Props) => CoherentNode);
+
+/** The SSR renderer Astro loads from the integration's server entrypoint. */
+export interface CoherentAstroRenderer {
+  name: string;
+  check(Component: unknown, props?: Record<string, unknown>): boolean;
+  renderToStaticMarkup(Component: unknown, props?: Record<string, unknown>): { html: string };
+}
+
+/**
+ * Astro integration that registers the Coherent.js renderer
+ * (`@coherent.js/integrations/astro/server`).
+ */
+export function createAstroIntegration(options?: CoherentAstroOptions): AstroIntegration;
+
+/** Render a Coherent.js component (or component function) to an HTML string. */
+export function renderComponent<Props = Record<string, unknown>>(
+  Component: CoherentAstroComponent<Props>,
+  props?: Props,
+  renderOptions?: RenderOptions
+): string;
+
+/** Create an Astro SSR renderer for Coherent.js components. */
+export function createRenderer(options?: RenderOptions): CoherentAstroRenderer;

package/types/astro/server.d.ts

@@ -0,0 +1,9 @@
+// Type definitions for the Coherent.js Astro server entrypoint
+// (../../src/astro/server.js): Astro imports its default export as the
+// SSR renderer.
+
+import type { CoherentAstroRenderer } from './index.js';
+
+declare const renderer: CoherentAstroRenderer;
+
+export default renderer;

package/types/express/index.d.ts

@@ -12,7 +12,7 @@ export interface CoherentMiddlewareOptions {
   
   /**
    * HTML template to wrap rendered components
-   * @default '<!DOCTYPE html><html><body>{{content}}</body></html>'
+   * @default '<!DOCTYPE html>\n{{content}}'
    */
   template?: string;
   
@@ -21,6 +21,26 @@ export interface CoherentMiddlewareOptions {
    * @default true
    */
   enableSSR?: boolean;
+
+  /**
+   * Also render component-shaped objects passed to `res.send()`.
+   *
+   * Detection is a heuristic: every single-key object qualifies, so JSON
+   * payloads such as `{ ok: true }` or `{ users: [...] }` would be rendered
+   * as HTML. Use `res.coherent(component)` instead unless the app never
+   * sends single-key JSON objects.
+   * @default false
+   */
+  autoRender?: boolean;
+}
+
+/**
+ * Per-call options for `res.coherent()`; each falls back to the middleware's.
+ */
+export interface CoherentRenderOptions {
+  enablePerformanceMonitoring?: boolean;
+  /** HTML template with a `{{content}}` placeholder. */
+  template?: string;
 }
 
 export interface CoherentHandlerOptions {
@@ -32,7 +52,7 @@ export interface CoherentHandlerOptions {
   
   /**
    * HTML template to wrap rendered components
-   * @default '<!DOCTYPE html><html><body>{{content}}</body></html>'
+   * @default '<!DOCTYPE html>\n{{content}}'
    */
   template?: string;
   
@@ -51,13 +71,15 @@ export interface SetupCoherentExpressOptions {
   useMiddleware?: boolean;
   
   /**
-   * Use Coherent.js view engine
-   * @default true
+   * Register {@link enhancedExpressEngine} as a view engine. It becomes the
+   * app's default `view engine` only if none is set yet.
+   * @default false
    */
   useEngine?: boolean;
-  
+
   /**
-   * Name of the view engine
+   * Name of the view engine, i.e. the view file extension. Use `'js'` to
+   * render `views/*.js` modules whose default export is the component.
    * @default 'coherent'
    */
   engineName?: string;
@@ -67,7 +89,20 @@ export interface SetupCoherentExpressOptions {
    * @default false
    */
   enablePerformanceMonitoring?: boolean;
-  
+
+  /**
+   * HTML template with a `{{content}}` placeholder, used by `res.coherent()`
+   * @default '<!DOCTYPE html>\n{{content}}'
+   */
+  template?: string;
+
+  /**
+   * Also render component-shaped objects passed to `res.send()`.
+   * See {@link CoherentMiddlewareOptions.autoRender} for why this is opt-in.
+   * @default false
+   */
+  autoRender?: boolean;
+
   /**
    * Static file directory for client-side assets
    * @default 'public'
@@ -75,9 +110,23 @@ export interface SetupCoherentExpressOptions {
   staticDir?: string;
 }
 
+declare global {
+  namespace Express {
+    interface Response {
+      /**
+       * Render a Coherent.js component (wrapped in the middleware's template)
+       * and send it as `text/html`. Rendering errors are passed to the app's
+       * error middleware, as `res.render()` does. Added by
+       * `coherentMiddleware()` / `setupCoherent()`.
+       */
+      coherent(component: CoherentNode, options?: CoherentRenderOptions): this;
+    }
+  }
+}
+
 /**
  * Coherent.js Express middleware
- * Adds Coherent.js rendering capabilities to Express
+ * Adds `res.coherent()` (and, with `autoRender`, `res.send` rendering)
  * @param options Configuration options
  * @returns Express middleware function
  */
@@ -89,19 +138,29 @@ export function coherentMiddleware(options?: CoherentMiddlewareOptions): (
 
 /**
  * Create an Express route handler for Coherent.js components
- * @param componentFactory Function that returns a Coherent component
+ * @param componentFactory Function that returns a Coherent component. If it
+ *   responds itself (e.g. `res.redirect()`), its return value is ignored.
  * @param options Configuration options
  * @returns Express route handler
  */
 export function createCoherentHandler(
-  componentFactory: (req: Request, res: Response, next: NextFunction) => CoherentNode | Promise<CoherentNode>,
+  componentFactory: (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ) => CoherentNode | void | Promise<CoherentNode | void>,
   options?: CoherentHandlerOptions
-): (req: Request, res: Response, next: NextFunction) => void;
+): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
 /**
- * Enhanced Express engine for Coherent.js views
+ * Express view engine for Coherent.js views.
+ *
+ * A `.js`/`.mjs`/`.cjs` view module's default export is the component (a
+ * function is called with the render locals). For any other view file the
+ * locals themselves are rendered as the component. Express's `settings`,
+ * `_locals` and `cache` keys are stripped from the locals first.
  * @param filePath Path to the view file
- * @param options Rendering options
+ * @param options Render locals
  * @param callback Callback function
  */
 export function enhancedExpressEngine(
@@ -112,7 +171,7 @@ export function enhancedExpressEngine(
 
 /**
  * Setup Coherent.js with Express app
- * Configures middleware, view engine, and static files
+ * Installs {@link coherentMiddleware} and, with `useEngine`, the view engine
  * @param app Express application instance
  * @param options Configuration options
  */
@@ -135,8 +194,7 @@ export function createExpressIntegration(
 ): Promise<(app: Application) => Application>;
 
 /**
- * A classic Express view engine that renders the component passed as the
- * `options` argument.
+ * Returns {@link enhancedExpressEngine}, for `app.engine('js', expressEngine())`.
  *
  * Kept for consumers migrating from the standalone `@coherent.js/express`
  * package; new code should prefer {@link setupCoherent}.

package/types/fastify/index.d.ts

@@ -4,7 +4,7 @@
 // Wave 2c (integrations consolidation). Declarations are aligned with the
 // runtime exports of ../../src/fastify/coherent-fastify.js.
 
-import { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import type { FastifyPluginCallback, FastifyReply, FastifyRequest } from 'fastify';
 import type { CoherentNode } from '@coherent.js/core';
 
 export interface CoherentFastifyOptions {
@@ -26,6 +26,17 @@ export interface CoherentFastifyOptions {
    */
   enableSSR?: boolean;
 
+  /**
+   * Also render component-shaped objects returned from route handlers.
+   *
+   * Detection is a heuristic: every single-key object qualifies, so JSON
+   * payloads such as `{ ok: true }` or `{ error: '...' }` would be rendered
+   * as HTML, even with a JSON response schema. Use `reply.coherent(component)`
+   * instead unless the app never returns single-key JSON objects.
+   * @default false
+   */
+  autoRender?: boolean;
+
   /**
    * Static file directory for client-side assets
    * @default 'public'
@@ -54,17 +65,17 @@ export interface CoherentFastifyHandlerOptions {
 }
 
 /**
- * Fastify plugin for Coherent.js
- * Adds Coherent.js rendering capabilities to Fastify
- * @param fastify Fastify instance
- * @param options Configuration options
- * @param done Callback to signal plugin registration completion
+ * Fastify plugin for Coherent.js (wrapped with fastify-plugin, so its
+ * decorators apply to the registering scope). Adds `reply.coherent()` and,
+ * with `autoRender`, rendering of returned components.
+ *
+ * Register it; do not call it:
+ *
+ * ```ts
+ * await fastify.register(coherentFastify, { template });
+ * ```
  */
-export function coherentFastify(
-  fastify: FastifyInstance,
-  options: CoherentFastifyOptions,
-  done: () => void
-): void;
+export const coherentFastify: FastifyPluginCallback<CoherentFastifyOptions>;
 
 /**
  * Create a Fastify route handler for Coherent.js components
@@ -81,15 +92,10 @@ export function createHandler(
 ): (request: FastifyRequest, reply: FastifyReply) => Promise<any>;
 
 /**
- * Setup Coherent.js with Fastify instance
- * Configures plugin, static files, and reply extensions
- * @param fastify Fastify instance
- * @param options Configuration options
+ * Alias of {@link coherentFastify}. It is a Fastify plugin: register it with
+ * `await fastify.register(setupCoherent, options)` rather than calling it.
  */
-export function setupCoherent(
-  fastify: FastifyInstance,
-  options?: CoherentFastifyOptions
-): void;
+export const setupCoherent: FastifyPluginCallback<CoherentFastifyOptions>;
 
 /**
  * Fastify reply extensions
@@ -104,14 +110,17 @@ declare module 'fastify' {
     isCoherentObject(obj: any): boolean;
 
     /**
-     * Render and send a Coherent component as HTML response
+     * Render and send a Coherent component as HTML response. A rendering
+     * error is sent through Fastify's error handling (`setErrorHandler`).
+     * Returns the reply, so `return reply.coherent(page)` works in async
+     * handlers.
      * @param component Coherent component to render
      * @param options Rendering options
      */
     coherent(
       component: CoherentNode,
       options?: CoherentFastifyHandlerOptions
-    ): void;
+    ): FastifyReply;
   }
 }