@coherent.js/integrations 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Drouvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @coherent.js/integrations
+
+Framework integration adapters for Coherent.js — bridges between your chosen HTTP/SSG framework and the Coherent.js rendering engine.
+
+## Subpath exports
+
+- `@coherent.js/integrations/express` — Express.js adapter
+- `@coherent.js/integrations/fastify` — Fastify adapter (added in 1.0.0)
+- `@coherent.js/integrations/koa` — Koa adapter (added in 1.0.0)
+- `@coherent.js/integrations/nextjs` — Next.js adapter (added in 1.0.0)
+- `@coherent.js/integrations/astro` — Astro adapter (added in 1.0.0)
+- `@coherent.js/integrations/remix` — Remix adapter (added in 1.0.0)
+- `@coherent.js/integrations/sveltekit` — SvelteKit adapter (added in 1.0.0)
+
+## Migration from pre-1.0
+
+Each framework previously shipped as its own package (`@coherent.js/express`, etc.). Migrate by changing import paths:
+
+```diff
+- import { setupCoherent } from '@coherent.js/express';
++ import { setupCoherent } from '@coherent.js/integrations/express';
+```
+
+Public API is unchanged — only the import path moves.
+
+## Install
+
+```bash
+pnpm add @coherent.js/core @coherent.js/integrations
+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.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@coherent.js/integrations",
+  "version": "1.0.0-rc.1",
+  "description": "Framework integration adapters for Coherent.js: Express, Fastify, Koa, Next.js, Astro, Remix, SvelteKit.",
+  "type": "module",
+  "exports": {
+    "./express": {
+      "types": "./types/express/index.d.ts",
+      "import": "./src/express/index.js"
+    },
+    "./fastify": {
+      "types": "./types/fastify/index.d.ts",
+      "import": "./src/fastify/index.js"
+    },
+    "./koa": {
+      "import": "./src/koa/index.js"
+    },
+    "./nextjs": {
+      "types": "./types/nextjs/index.d.ts",
+      "import": "./src/nextjs/index.js"
+    },
+    "./astro": {
+      "import": "./src/astro/index.js"
+    },
+    "./remix": {
+      "import": "./src/remix/index.js"
+    },
+    "./sveltekit": {
+      "import": "./src/sveltekit/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "types/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tomdrouv1/coherent.js.git"
+  },
+  "homepage": "https://github.com/Tomdrouv1/coherent.js",
+  "bugs": {
+    "url": "https://github.com/Tomdrouv1/coherent.js/issues"
+  },
+  "peerDependencies": {
+    "@remix-run/server-runtime": ">=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.0.0-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "@remix-run/server-runtime": {
+      "optional": true
+    },
+    "@sveltejs/kit": {
+      "optional": true
+    },
+    "astro": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "koa": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "node build.mjs",
+    "clean": "rm -rf dist/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/astro/index.js

@@ -0,0 +1,88 @@
+// src/astro/index.js
+//
+// Public entry point for @coherent.js/integrations/astro. Provides
+// server-side rendering of Coherent.js components within Astro projects.
+//
+// Astro must be installed as a peer dependency to use this integration.
+//
+// Usage:
+//   import { createAstroIntegration } from '@coherent.js/integrations/astro';
+
+import { render } from '@coherent.js/core';
+
+/**
+ * Create an Astro integration for Coherent.js
+ *
+ * @param {Object} [options] - Integration options
+ * @param {boolean} [options.hydrate] - Enable client-side hydration
+ * @param {string} [options.hydrateScript] - Custom hydration script path
+ * @returns {Object} Astro integration configuration
+ *
+ * @example
+ * // astro.config.mjs
+ * import { createAstroIntegration } from '@coherent.js/integrations/astro';
+ * export default { integrations: [createAstroIntegration()] };
+ */
+export function createAstroIntegration(options = {}) {
+  return {
+    name: 'coherent',
+    hooks: {
+      'astro:config:setup': ({ addRenderer, updateConfig }) => {
+        addRenderer({
+          name: '@coherent.js/integrations/astro',
+          serverEntrypoint: '@coherent.js/integrations/astro',
+        });
+
+        if (options.hydrate) {
+          updateConfig({
+            vite: {
+              optimizeDeps: {
+                include: ['@coherent.js/client']
+              }
+            }
+          });
+        }
+      },
+      'astro:build:done': ({ logger }) => {
+        logger?.info('Coherent.js components built successfully');
+      }
+    }
+  };
+}
+
+/**
+ * Render a Coherent.js component to HTML string
+ *
+ * @param {Function|Object} Component - Coherent.js component
+ * @param {Object} [props] - Component props
+ * @param {Object} [renderOptions] - Rendering options
+ * @returns {string} Rendered HTML
+ */
+export function renderComponent(Component, props = {}, renderOptions = {}) {
+  const componentDef = typeof Component === 'function'
+    ? Component(props)
+    : Component;
+
+  return render(componentDef, renderOptions);
+}
+
+/**
+ * Create a server-side component renderer for Astro
+ *
+ * @param {Object} [options] - Renderer options
+ * @returns {Object} Astro renderer configuration
+ */
+export function createRenderer(options = {}) {
+  return {
+    name: '@coherent.js/astro-renderer',
+    check(Component) {
+      // Check if this looks like a Coherent.js component (function or plain object with tag keys)
+      return typeof Component === 'function' ||
+        (typeof Component === 'object' && Component !== null && !Array.isArray(Component));
+    },
+    renderToStaticMarkup(Component, props) {
+      const html = renderComponent(Component, props, options);
+      return { html };
+    }
+  };
+}

package/src/express/coherent-express.js

@@ -0,0 +1,160 @@
+/**
+ * Enhanced Express.js integration for Coherent.js
+ * Provides middleware and utilities for using Coherent.js with Express
+ */
+
+import {
+  render,
+  importPeerDependency,
+  renderWithTemplate,
+  renderComponentFactory,
+  isCoherentComponent
+} from '@coherent.js/core';
+
+/**
+ * Coherent.js Express middleware
+ * Automatically renders Coherent.js components and handles errors
+ *
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.enablePerformanceMonitoring - Enable performance monitoring
+ * @param {string} options.template - HTML template with {{content}} placeholder
+ * @returns {Function} Express middleware function
+ */
+export function coherentMiddleware(options = {}) {
+  const {
+    enablePerformanceMonitoring = false,
+    template = '<!DOCTYPE html>\n{{content}}'
+  } = 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);
+        }
+      }
+
+      // For non-Coherent.js data, use original send method
+      return originalSend.call(this, data);
+    };
+
+    next();
+  };
+}
+
+/**
+ * Create an Express route handler for Coherent.js components
+ *
+ * @param {Function} componentFactory - Function that returns a Coherent.js component
+ * @param {Object} options - Handler options
+ * @returns {Function} Express route handler
+ */
+export function createCoherentHandler(componentFactory, options = {}) {
+  return async (req, res, next) => {
+    try {
+      // Use shared rendering utility
+      const finalHtml = await renderComponentFactory(
+        componentFactory,
+        [req, res, next],
+        options
+      );
+
+      // Send HTML response
+      res.set('Content-Type', 'text/html');
+      res.send(finalHtml);
+    } catch (_error) {
+      console.error('Coherent.js handler _error:', _error);
+      next(_error);
+    }
+  };
+}
+
+/**
+ * Enhanced Express engine for Coherent.js views
+ *
+ * @param {string} filePath - Path to view file (not used in Coherent.js)
+ * @param {Object} options - View options containing Coherent.js component
+ * @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);
+  }
+}
+
+/**
+ * Setup Coherent.js with Express app
+ *
+ * @param {Object} app - Express app instance
+ * @param {Object} options - Setup options
+ */
+export function setupCoherent(app, options = {}) {
+  const {
+    useMiddleware = true,
+    useEngine = true,
+    engineName = 'coherent',
+    enablePerformanceMonitoring = false
+  } = options;
+
+  // Register enhanced engine
+  if (useEngine) {
+    app.engine(engineName, enhancedExpressEngine);
+    app.set('view engine', engineName);
+  }
+
+  // Use middleware for automatic rendering
+  if (useMiddleware) {
+    app.use(coherentMiddleware({ enablePerformanceMonitoring }));
+  }
+}
+
+/**
+ * Create Express integration with dependency checking
+ * This function ensures Express is available before setting up the integration
+ *
+ * @param {Object} options - Setup options
+ * @returns {Promise<Function>} - Function to setup Express integration
+ */
+export async function createExpressIntegration(options = {}) {
+  try {
+    // Verify Express is available
+    await importPeerDependency('express', 'Express.js');
+
+    return function(app) {
+      if (!app || typeof app.use !== 'function') {
+        throw new Error('Invalid Express app instance provided');
+      }
+
+      setupCoherent(app, options);
+      return app;
+    };
+  } catch (_error) {
+    throw _error;
+  }
+}
+
+// Export all utilities
+export default {
+  coherentMiddleware,
+  createCoherentHandler,
+  enhancedExpressEngine,
+  setupCoherent,
+  createExpressIntegration
+};

package/src/express/index.js

@@ -0,0 +1,36 @@
+// src/express/index.js
+//
+// Public entry point for @coherent.js/integrations/express. Re-exports the
+// full runtime surface from coherent-express.js so the runtime matches the
+// TypeScript declarations in ../../types/express/index.d.ts.
+//
+// `expressEngine` is preserved as a thin factory wrapper for backwards
+// compatibility with consumers that imported it from the legacy
+// @coherent.js/express package.
+
+import { render } from '@coherent.js/core';
+
+export {
+  coherentMiddleware,
+  createCoherentHandler,
+  enhancedExpressEngine,
+  setupCoherent,
+  createExpressIntegration
+} from './coherent-express.js';
+
+/**
+ * Factory returning a classic Express view engine that renders a Coherent.js
+ * component tree passed via the `options` argument.
+ *
+ * @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);
+    }
+  };
+}

package/src/fastify/coherent-fastify.js

@@ -0,0 +1,125 @@
+/**
+ * Fastify integration for Coherent.js
+ * Provides plugins and utilities for using Coherent.js with Fastify
+ */
+
+import {
+  renderWithTemplate,
+  renderComponentFactory
+} from '@coherent.js/core';
+
+/**
+ * Fastify plugin for Coherent.js
+ * Automatically renders Coherent.js components and handles errors
+ *
+ * @param {Object} fastify - Fastify instance
+ * @param {Object} options - Plugin options
+ * @param {boolean} options.enablePerformanceMonitoring - Enable performance monitoring
+ * @param {string} options.template - HTML template with {{content}} placeholder
+ * @param {Function} done - Callback to signal plugin registration completion
+ */
+export function coherentFastify(fastify, options, done) {
+  const {
+    enablePerformanceMonitoring = false,
+    template = '<!DOCTYPE html>\n{{content}}'
+  } = options;
+
+  // Add decorator to check if an object is a Coherent.js component
+  fastify.decorateReply('isCoherentObject', (obj) => {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+      return false;
+    }
+
+    const keys = Object.keys(obj);
+    return keys.length === 1;
+  });
+
+  // Add decorator for rendering Coherent.js components
+  fastify.decorateReply('coherent', function(component, renderOptions = {}) {
+    const {
+      enablePerformanceMonitoring: renderPerformanceMonitoring = enablePerformanceMonitoring,
+      template: renderTemplate = template
+    } = renderOptions;
+
+    try {
+      // Use shared rendering utility
+      const finalHtml = renderWithTemplate(component, {
+        enablePerformanceMonitoring: renderPerformanceMonitoring,
+        template: renderTemplate
+      });
+
+      // Set content type and send HTML
+      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
+      });
+    }
+  });
+
+  // Hook to automatically render Coherent.js objects
+  fastify.addHook('onSend', async (request, reply, payload) => {
+    // If payload is a Coherent.js object, render it
+    if (reply.isCoherentObject(payload)) {
+      try {
+        // Use shared rendering utility
+        const finalHtml = renderWithTemplate(payload, { enablePerformanceMonitoring, template });
+
+        // Set content type and return HTML
+        reply.header('Content-Type', 'text/html; charset=utf-8');
+        return finalHtml;
+      } catch (_error) {
+        console.error('Coherent.js rendering _error:', _error);
+        throw _error;
+      }
+    }
+
+    // For non-Coherent.js data, return as-is
+    return payload;
+  });
+
+  done();
+}
+
+/**
+ * Create a Fastify route handler for Coherent.js components
+ *
+ * @param {Function} componentFactory - Function that returns a Coherent.js component
+ * @param {Object} options - Handler options
+ * @returns {Function} Fastify route handler
+ */
+export function createHandler(componentFactory, options = {}) {
+  return async (request, reply) => {
+    try {
+      // Use shared rendering utility
+      const finalHtml = await renderComponentFactory(
+        componentFactory,
+        [request, reply],
+        options
+      );
+
+      // Send HTML response
+      reply.header('Content-Type', 'text/html; charset=utf-8');
+      return finalHtml;
+    } catch (_error) {
+      console.error('Coherent.js handler _error:', _error);
+      throw _error;
+    }
+  };
+}
+
+/**
+ * Setup Coherent.js with Fastify instance
+ *
+ * @param {Object} fastify - Fastify instance
+ * @param {Object} options - Setup options
+ */
+export function setupCoherent(fastify, options = {}) {
+  fastify.register(coherentFastify, options);
+}
+
+// Export plugin as default for Fastify's plugin system
+export default coherentFastify;

package/src/fastify/index.js

@@ -0,0 +1,13 @@
+// src/fastify/index.js
+//
+// Public entry point for @coherent.js/integrations/fastify. Re-exports the
+// full runtime surface from coherent-fastify.js so the runtime matches the
+// TypeScript declarations in ../../types/fastify/index.d.ts.
+
+export {
+  coherentFastify,
+  createHandler,
+  setupCoherent
+} from './coherent-fastify.js';
+
+export { default } from './coherent-fastify.js';