@taujs/react 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Aoede Ltd 2025
+
+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,101 @@
+# @taujs/server
+
+`npm install @taujs/server`
+
+`yarn add @taujs/server`
+
+`pnpm add @taujs/server`
+
+## CSR; SSR; Streaming SSR; Hydration; Fastify + React 19
+
+Supports rendering modes:
+
+- Client-side rendering (CSR)
+- Server-side rendering (SSR)
+- Streaming SSR
+
+Supported application structure and composition:
+
+- Single-page Application (SPA)
+- Multi-page Application (MPA)
+- Build-time Micro-Frontends (MFE), with server orchestration and delivery
+
+Assemble independent frontends at build time incorporating flexible per-route SPA-MPA hybrid with CSR, SSR, and Streaming SSR, rendering options.
+
+Fastify Plugin for integration with taujs [ τjs ] template https://github.com/aoede3/taujs
+
+- Production: Fastify, React
+- Development: Fastify, React, tsx, Vite
+
+- TypeScript-first
+- ESM-only focus
+
+## τjs - DX Developer Experience
+
+Integrated Vite HMR run alongside tsx (TS eXecute) providing fast responsive dev reload times for universal backend / frontend changes
+
+- Fastify https://fastify.dev/
+- React https://reactjs.org/
+- tsx https://tsx.is/
+- Vite https://vitejs.dev/guide/ssr#building-for-production
+
+- ESBuild https://esbuild.github.io/
+- Rollup https://rollupjs.org/
+- ESM https://nodejs.org/api/esm.html
+
+## Development / CI
+
+`npm install --legacy-peer-deps`
+
+## Usage
+
+### Fastify
+
+https://github.com/aoede3/taujs/blob/main/src/server/index.ts
+
+Not utilising taujs [ τjs ] template? Add in your own ts `alias` object for your own particular directory setup e.g. `alias: { object }`
+
+### React 'entry-client.tsx'
+
+https://github.com/aoede3/taujs/blob/main/src/client/entry-client.tsx
+
+### React 'entry-server.tsx'
+
+Extended pipe object with callbacks to @taujs/server enabling additional manipulation of HEAD content from client code
+
+https://github.com/aoede3/taujs/blob/main/src/client/entry-server.tsx
+
+### index.html
+
+https://github.com/aoede3/taujs/blob/main/src/client/index.html
+
+### client.d.ts
+
+https://github.com/aoede3/taujs/blob/main/src/client/client.d.ts
+
+### Routes
+
+Integral to τjs is its internal routing:
+
+1. Fastify serving index.html to client browser for client routing
+2. Internal service calls to API to provide data for streaming/hydration
+3. Fastify serving API calls via HTTP in the more traditional sense of client/server
+
+In ensuring a particular 'route' receives data for hydration there are two options:
+
+1. An HTTP call syntactically not unlike 'fetch' providing params to a 'fetch' call
+2. Internal service call returning data as per your architecture
+
+In supporting Option 2. there is a registry of services. More detail in 'Service Registry'.
+
+Each routes 'path' is a simple URL regex as per below examples.
+
+https://github.com/aoede3/taujs/blob/main/src/shared/routes/Routes.ts
+
+### Service Registry
+
+In supporting internal calls via τjs a registry of available services and methods can provide linkage to your own architectural setup and developmental patterns
+
+https://github.com/aoede3/taujs/blob/main/src/server/services/ServiceRegistry.ts
+
+https://github.com/aoede3/taujs/blob/main/src/server/services/ServiceExample.ts

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import React from 'react';
+import { ServerResponse } from 'node:http';
+
+type SSRStore<T> = {
+    getSnapshot: () => T;
+    getServerSnapshot: () => T;
+    setData: (newData: T) => void;
+    subscribe: (callback: () => void) => () => void;
+};
+declare const createSSRStore: <T>(initialDataOrPromise: T | Promise<T>) => SSRStore<T>;
+declare const SSRStoreProvider: React.FC<React.PropsWithChildren<{
+    store: SSRStore<Record<string, unknown>>;
+}>>;
+declare const useSSRStore: <T>() => T;
+
+type HydrateAppOptions = {
+    appComponent: React.ReactElement;
+    initialDataKey?: keyof Window;
+    rootElementId?: string;
+    debug?: boolean;
+};
+declare const hydrateApp: ({ appComponent, initialDataKey, rootElementId, debug }: HydrateAppOptions) => void;
+
+type RendererOptions = {
+    appComponent: (props: {
+        location: string;
+    }) => React.ReactElement;
+    headContent: string | ((data: Record<string, unknown>) => string);
+};
+type RenderCallbacks = {
+    onHead: (headContent: string) => void;
+    onFinish: (initialDataResolved: unknown) => void;
+    onError: (error: unknown) => void;
+};
+declare const resolveHeadContent: (headContent: string | ((meta: Record<string, unknown>) => string), meta?: Record<string, unknown>) => string;
+declare const createRenderer: ({ appComponent, headContent }: RendererOptions) => {
+    renderSSR: (initialDataResolved: Record<string, unknown>, location: string, meta?: Record<string, unknown>) => Promise<{
+        headContent: string;
+        appHtml: string;
+    }>;
+    renderStream: (serverResponse: ServerResponse, callbacks: RenderCallbacks, initialDataResolved: Record<string, unknown>, location: string, bootstrapModules?: string, meta?: Record<string, unknown>) => void;
+};
+declare const createRenderStream: (serverResponse: ServerResponse, { onHead, onFinish, onError }: RenderCallbacks, { appComponent, headContent, initialDataResolved, location, bootstrapModules, }: RendererOptions & {
+    initialDataResolved: Record<string, unknown>;
+    location: string;
+    bootstrapModules?: string;
+}) => void;
+
+export { type SSRStore, SSRStoreProvider, createRenderStream, createRenderer, createSSRStore, hydrateApp, resolveHeadContent, useSSRStore };

package/dist/index.js

@@ -0,0 +1,182 @@
+// src/SSRDataStore.tsx
+import { createContext, useContext, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+var createSSRStore = (initialDataOrPromise) => {
+  let currentData;
+  let status;
+  const subscribers = /* @__PURE__ */ new Set();
+  let serverDataPromise;
+  if (initialDataOrPromise instanceof Promise) {
+    status = "pending";
+    serverDataPromise = initialDataOrPromise.then((data) => {
+      currentData = data;
+      status = "success";
+      subscribers.forEach((callback) => callback());
+    }).catch((error) => {
+      console.error("Failed to load initial data:", error);
+      status = "error";
+    }).then(() => {
+    });
+  } else {
+    currentData = initialDataOrPromise;
+    status = "success";
+    serverDataPromise = Promise.resolve();
+  }
+  const setData = (newData) => {
+    currentData = newData;
+    status = "success";
+    subscribers.forEach((callback) => callback());
+  };
+  const subscribe = (callback) => {
+    subscribers.add(callback);
+    return () => subscribers.delete(callback);
+  };
+  const getSnapshot = () => {
+    if (status === "pending") {
+      throw serverDataPromise;
+    } else if (status === "error") {
+      throw new Error("An error occurred while fetching the data.");
+    }
+    return currentData;
+  };
+  const getServerSnapshot = () => {
+    if (status === "pending") {
+      throw serverDataPromise;
+    } else if (status === "error") {
+      throw new Error("Data is not available on the server.");
+    }
+    return currentData;
+  };
+  return { getSnapshot, getServerSnapshot, setData, subscribe };
+};
+var SSRStoreContext = createContext(null);
+var SSRStoreProvider = ({ store, children }) => /* @__PURE__ */ jsx(SSRStoreContext.Provider, { value: store, children });
+var useSSRStore = () => {
+  const store = useContext(SSRStoreContext);
+  if (!store) throw new Error("useSSRStore must be used within a SSRStoreProvider");
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+};
+
+// src/SSRHydration.tsx
+import React2 from "react";
+import { createRoot, hydrateRoot } from "react-dom/client";
+
+// src/utils/Logger.ts
+var createLogger = (debug) => ({
+  log: (...args) => {
+    if (debug) console.log(...args);
+  },
+  warn: (...args) => {
+    if (debug) console.warn(...args);
+  },
+  error: (...args) => {
+    if (debug) console.error(...args);
+  }
+});
+
+// src/SSRHydration.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var hydrateApp = ({ appComponent, initialDataKey = "__INITIAL_DATA__", rootElementId = "root", debug = false }) => {
+  const { log, warn, error } = createLogger(debug);
+  const bootstrap = () => {
+    log("Hydration started");
+    const rootElement = document.getElementById(rootElementId);
+    if (!rootElement) {
+      error(`Root element with id "${rootElementId}" not found.`);
+      return;
+    }
+    const initialData = window[initialDataKey];
+    if (!initialData) {
+      warn(`Initial data key "${initialDataKey}" is undefined on window. Defaulting to SPA createRoot`);
+      const root = createRoot(rootElement);
+      root.render(/* @__PURE__ */ jsx2(React2.StrictMode, { children: appComponent }));
+    } else {
+      log("Initial data loaded:", initialData);
+      const initialDataPromise = Promise.resolve(initialData);
+      const store = createSSRStore(initialDataPromise);
+      log("Store created:", store);
+      hydrateRoot(
+        rootElement,
+        /* @__PURE__ */ jsx2(React2.StrictMode, { children: /* @__PURE__ */ jsx2(SSRStoreProvider, { store, children: appComponent }) })
+      );
+      log("Hydration completed");
+    }
+  };
+  if (document.readyState !== "loading") {
+    bootstrap();
+  } else {
+    document.addEventListener("DOMContentLoaded", bootstrap);
+  }
+};
+
+// src/SSRRender.tsx
+import "http";
+import { Writable } from "stream";
+import "react";
+import { renderToPipeableStream, renderToString } from "react-dom/server";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var resolveHeadContent = (headContent, meta = {}) => typeof headContent === "function" ? headContent(meta) : headContent;
+var createRenderer = ({ appComponent, headContent }) => {
+  const renderSSR = async (initialDataResolved, location, meta = {}) => {
+    const dataForHeadContent = Object.keys(initialDataResolved).length > 0 ? initialDataResolved : meta;
+    const dynamicHeadContent = resolveHeadContent(headContent, dataForHeadContent);
+    const appHtml = renderToString(/* @__PURE__ */ jsx3(SSRStoreProvider, { store: createSSRStore(initialDataResolved), children: appComponent({ location }) }));
+    return {
+      headContent: dynamicHeadContent,
+      appHtml
+    };
+  };
+  const renderStream = (serverResponse, callbacks, initialDataResolved, location, bootstrapModules, meta = {}) => {
+    const dynamicHeadContent = resolveHeadContent(headContent, meta);
+    createRenderStream(serverResponse, callbacks, {
+      appComponent: (props) => appComponent({ ...props, location }),
+      headContent: dynamicHeadContent,
+      initialDataResolved,
+      location,
+      bootstrapModules
+    });
+  };
+  return { renderSSR, renderStream };
+};
+var createRenderStream = (serverResponse, { onHead, onFinish, onError }, {
+  appComponent,
+  headContent,
+  initialDataResolved,
+  location,
+  bootstrapModules
+}) => {
+  const store = createSSRStore(initialDataResolved);
+  const appElement = /* @__PURE__ */ jsx3(SSRStoreProvider, { store, children: appComponent({ location }) });
+  const { pipe } = renderToPipeableStream(appElement, {
+    bootstrapModules: bootstrapModules ? [bootstrapModules] : void 0,
+    onShellReady() {
+      const dynamicHeadContent = resolveHeadContent(headContent, initialDataResolved);
+      onHead(dynamicHeadContent);
+      pipe(
+        new Writable({
+          write(chunk, _encoding, callback) {
+            serverResponse.write(chunk, callback);
+          },
+          final(callback) {
+            onFinish(store.getSnapshot());
+            callback();
+          }
+        })
+      );
+    },
+    onAllReady() {
+    },
+    onError(error) {
+      onError(error);
+    }
+  });
+};
+export {
+  SSRStoreProvider,
+  createRenderStream,
+  createRenderer,
+  createSSRStore,
+  hydrateApp,
+  resolveHeadContent,
+  useSSRStore
+};

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@taujs/react",
+  "version": "0.0.1",
+  "description": "taujs | τjs",
+  "author": "Aoede <taujs@aoede.uk.net> (https://www.aoede.uk.net)",
+  "license": "MIT",
+  "homepage": "https://github.com/aoede3/taujs-react",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aoede3/taujs-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aoede3/taujs-react/issues"
+  },
+  "keywords": [
+    "fastify",
+    "typescript",
+    "esm",
+    "vite",
+    "streaming",
+    "react",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.15.4",
+    "@babel/preset-typescript": "^7.24.7",
+    "@changesets/cli": "^2.27.7",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "@vitest/coverage-v8": "^2.1.0",
+    "jsdom": "^25.0.0",
+    "prettier": "^3.3.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4",
+    "vite": "^6.3.5",
+    "vitest": "^2.0.5"
+  },
+  "peerDependencies": {
+    "@taujs/server": "^0.2.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.5.4",
+    "vite": "^6.3.5"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "build-local": "tsup && ./move.sh",
+    "ci": "npm run build && npm run check-format && npm run lint",
+    "lint": "tsc",
+    "test": "vitest run",
+    "test:ui": "vitest --ui --coverage.enabled=true",
+    "coverage": "vitest run --coverage",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
+    "prepublishOnly": "npm run ci",
+    "local-release": "npm run ci && changeset version && changeset publish"
+  }
+}