npm - @kurdel/template-react - Versions diffs - 0.1.0-beta.1 - Mend

@kurdel/template-react 0.1.0-beta.1

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 (15) hide show

package/LICENSE +21 -0
package/README.md +20 -0
package/lib/index.d.ts +2 -0
package/lib/index.js +3 -0
package/lib/index.js.map +1 -0
package/lib/react-template-engine.d.ts +25 -0
package/lib/react-template-engine.js +52 -0
package/lib/react-template-engine.js.map +1 -0
package/lib/react-template-module.d.ts +32 -0
package/lib/react-template-module.js +47 -0
package/lib/react-template-module.js.map +1 -0
package/lib/react-template-options.d.ts +42 -0
package/lib/react-template-options.js +2 -0
package/lib/react-template-options.js.map +1 -0
package/package.json +67 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025-2026 Andrii Sorokin
+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 ADDED Viewed

@@ -0,0 +1,20 @@
+# @kurdel/template-react
+Integration module for using **React components** with the Kurdel framework.
+Provides a unified `TemplateEngine` implementation for server-side rendering (SSR).
+---
+## 📦 Installation
+```bash
+npm install @kurdel/template-react
+```
+> Requires Node 20.19+, 22.12+, or 24+ and `@kurdel/core` / `@kurdel/runtime`.
+---
+## 📄 License
+MIT © Andrii Sorokin

package/lib/index.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export * from './react-template-engine.js';
2	+ export * from './react-template-module.js';

package/lib/index.js ADDED Viewed

@@ -0,0 +1,3 @@
+export * from './react-template-engine.js';
+export * from './react-template-module.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC"}

package/lib/react-template-engine.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import type { TemplateEngine } from '@kurdel/core/template';
+/**
+ * ReactTemplateEngine
+ *
+ * Renders React components (views) into static HTML strings
+ * for use in SSR (Server-Side Rendering).
+ *
+ * Responsibilities:
+ * - Dynamically import the base Document and page component
+ * - Compose them as a React element tree
+ * - Convert the tree to an HTML string
+ */
+export declare class ReactTemplateEngine implements TemplateEngine {
+    /** Base directory where `document.js` and view components reside */
+    private readonly baseDir;
+    constructor(baseDir: string);
+    /**
+     * Renders a React view wrapped in the shared Document layout.
+     *
+     * @param view - The view component name (without .js extension)
+     * @param data - Props to pass both to Document and the view
+     * @returns Rendered HTML string with <!DOCTYPE html>
+     */
+    render(view: string, data?: Record<string, unknown>): Promise<string>;
+}

package/lib/react-template-engine.js ADDED Viewed

@@ -0,0 +1,52 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createElement } from 'react';
+import { renderToString } from 'react-dom/server';
+/**
+ * ReactTemplateEngine
+ *
+ * Renders React components (views) into static HTML strings
+ * for use in SSR (Server-Side Rendering).
+ *
+ * Responsibilities:
+ * - Dynamically import the base Document and page component
+ * - Compose them as a React element tree
+ * - Convert the tree to an HTML string
+ */
+export class ReactTemplateEngine {
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    /**
+     * Renders a React view wrapped in the shared Document layout.
+     *
+     * @param view - The view component name (without .js extension)
+     * @param data - Props to pass both to Document and the view
+     * @returns Rendered HTML string with <!DOCTYPE html>
+     */
+    async render(view, data = {}) {
+        // 1️⃣ Load Document (HTML shell)
+        const documentPath = path.resolve(this.baseDir, 'document.js');
+        const documentUrl = pathToFileURL(documentPath).href;
+        const documentModule = await import(documentUrl);
+        const Document = documentModule.default;
+        if (!Document) {
+            throw new Error(`React document has no default export at ${documentPath}`);
+        }
+        // 2️⃣ Load view (React page component)
+        const viewPath = path.resolve(this.baseDir, `${view}.js`);
+        const viewUrl = pathToFileURL(viewPath).href;
+        const viewModule = await import(viewUrl);
+        const Component = viewModule.default;
+        if (!Component) {
+            throw new Error(`React view "${view}" has no default export at ${viewPath}`);
+        }
+        // 3️⃣ Compose React tree (Document → Component)
+        const content = createElement(Component, data);
+        const page = createElement(Document, data, content);
+        // 4️⃣ Convert to HTML string with doctype prefix
+        const html = renderToString(page);
+        return '<!DOCTYPE html>' + html;
+    }
+}
+//# sourceMappingURL=react-template-engine.js.map

package/lib/react-template-engine.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"react-template-engine.js","sourceRoot":"","sources":["../src/react-template-engine.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAqB,MAAM,OAAO,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIlD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mBAAmB;IAI9B,YAAY,OAAe;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,OAAgC,EAAE;QAClE,iCAAiC;QACjC,MAAM,YAAY,GAAW,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACvE,MAAM,WAAW,GAAW,aAAa,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC;QAC7D,MAAM,cAAc,GAAwB,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QACtE,MAAM,QAAQ,GAA8B,cAAc,CAAC,OAAO,CAAC;QAEnE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,2CAA2C,YAAY,EAAE,CAAC,CAAC;QAC7E,CAAC;QAED,uCAAuC;QACvC,MAAM,QAAQ,GAAW,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,KAAK,CAAC,CAAC;QAClE,MAAM,OAAO,GAAW,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;QACrD,MAAM,UAAU,GAAwB,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9D,MAAM,SAAS,GAA8B,UAAU,CAAC,OAAO,CAAC;QAEhE,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,8BAA8B,QAAQ,EAAE,CAAC,CAAC;QAC/E,CAAC;QAED,gDAAgD;QAChD,MAAM,OAAO,GAAiB,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAiB,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAElE,iDAAiD;QACjD,MAAM,IAAI,GAAW,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,iBAAiB,GAAG,IAAI,CAAC;IAClC,CAAC;CACF"}

package/lib/react-template-module.d.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import type { AppModule } from '@kurdel/core/app';
+import type { ReactTemplateOptions } from './react-template-options.js';
+/**
+ * ReactTemplateModule
+ *
+ * Application module that provides server-side React rendering
+ * via the {@link ReactTemplateEngine}.
+ *
+ * Responsibilities:
+ * - Registers `ReactTemplateEngine` as the default template engine
+ * - Exposes it through the `TemplateEngineToken`
+ *
+ * @example:
+ * ```ts
+ * const app = await createNodeApplication({
+ *   modules: [
+ *     ReactTemplateModule.forRoot({
+ *       baseDir: resolve(__dirname, './views'),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare class ReactTemplateModule {
+    /**
+     * Configures the module for root application context.
+     *
+     * @param options - Configuration options for the React template engine
+     * @returns AppModule definition that can be passed into `createApplication()`
+     */
+    static forRoot(options: ReactTemplateOptions): AppModule;
+}

package/lib/react-template-module.js ADDED Viewed

@@ -0,0 +1,47 @@
+import { TOKENS } from '@kurdel/core/tokens';
+import { ReactTemplateEngine } from './react-template-engine.js';
+/**
+ * ReactTemplateModule
+ *
+ * Application module that provides server-side React rendering
+ * via the {@link ReactTemplateEngine}.
+ *
+ * Responsibilities:
+ * - Registers `ReactTemplateEngine` as the default template engine
+ * - Exposes it through the `TemplateEngineToken`
+ *
+ * @example:
+ * ```ts
+ * const app = await createNodeApplication({
+ *   modules: [
+ *     ReactTemplateModule.forRoot({
+ *       baseDir: resolve(__dirname, './views'),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class ReactTemplateModule {
+    /**
+     * Configures the module for root application context.
+     *
+     * @param options - Configuration options for the React template engine
+     * @returns AppModule definition that can be passed into `createApplication()`
+     */
+    static forRoot(options) {
+        const providers = [
+            {
+                provide: TOKENS.TemplateEngineToken,
+                useFactory: () => new ReactTemplateEngine(options.baseDir),
+                singleton: true,
+            },
+        ];
+        return {
+            exports: {
+                view: TOKENS.TemplateEngineToken,
+            },
+            providers,
+        };
+    }
+}
+//# sourceMappingURL=react-template-module.js.map

package/lib/react-template-module.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"react-template-module.js","sourceRoot":"","sources":["../src/react-template-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAI7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAA6B;QAC1C,MAAM,SAAS,GAAqB;YAClC;gBACE,OAAO,EAAE,MAAM,CAAC,mBAAmB;gBACnC,UAAU,EAAE,GAAwB,EAAE,CAAC,IAAI,mBAAmB,CAAC,OAAO,CAAC,OAAO,CAAC;gBAC/E,SAAS,EAAE,IAAI;aAChB;SACF,CAAC;QAEF,OAAO;YACL,OAAO,EAAE;gBACP,IAAI,EAAE,MAAM,CAAC,mBAAmB;aACjC;YACD,SAAS;SACV,CAAC;IACJ,CAAC;CACF"}

package/lib/react-template-options.d.ts ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * ReactTemplateOptions
+ *
+ * Configuration options for the {@link ReactTemplateEngine}.
+ *
+ * Defines how and where the engine should locate and render
+ * React-based server-side templates.
+ */
+export interface ReactTemplateOptions {
+    /**
+     * Absolute or relative path to the directory
+     * containing your React views and `document.js` layout.
+     *
+     * @example
+     * ```ts
+     * {
+     *   baseDir: resolve(__dirname, './views')
+     * }
+     * ```
+     */
+    baseDir: string;
+    /**
+     * Optional flag to disable wrapping each view
+     * inside the shared `Document` component.
+     *
+     * When set to `false`, the engine will render
+     * only the view itself (useful for fragments or APIs).
+     *
+     * @default true
+     */
+    withDocument?: boolean;
+    /**
+     * Optional flag to enable React strict mode
+     * during server-side rendering.
+     *
+     * When enabled, the engine will wrap rendered content
+     * with `<React.StrictMode>` to help detect unsafe patterns.
+     *
+     * @default false
+     */
+    strictMode?: boolean;
+}

package/lib/react-template-options.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export {};
2	+ //# sourceMappingURL=react-template-options.js.map

package/lib/react-template-options.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"react-template-options.js","sourceRoot":"","sources":["../src/react-template-options.ts"],"names":[],"mappings":""}

package/package.json ADDED Viewed

@@ -0,0 +1,67 @@
+{
+  "name": "@kurdel/template-react",
+  "version": "0.1.0-beta.1",
+  "description": "React server-side rendering template engine for Kurdel",
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:ui": "vitest",
+    "test:watch": "vitest --watch",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf lib ../../.cache/tsconfig.template-react.build.tsbuildinfo",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "build:force": "npm run clean && tsc -p tsconfig.build.json --force && tsc-alias -p tsconfig.build.json"
+  },
+  "keywords": [
+    "kurdel",
+    "framework",
+    "react",
+    "ssr",
+    "template"
+  ],
+  "author": "Andrii Sorokin",
+  "license": "MIT",
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ignorantic/kurdel.git",
+    "directory": "packages/template-react"
+  },
+  "homepage": "https://github.com/ignorantic/kurdel/tree/main/packages/template-react#readme",
+  "bugs": {
+    "url": "https://github.com/ignorantic/kurdel/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.2.4",
+    "rimraf": "^6.0.1",
+    "tsc-alias": "^1.8.16"
+  },
+  "dependencies": {
+    "@kurdel/core": "0.1.0-beta.1"
+  }
+}