@taujs/server 0.0.1 → 0.0.4

package/README.md

@@ -1,26 +1,244 @@
 # @taujs/server
 
-Streaming React SSR & Hydration Fastify Plugin for integration with taujs [ τjs ] template
+`npm install @taujs/server`
+
+`yarn add @taujs/server`
+
+`pnpm add @taujs/server`
+
+## Streaming React SSR & Hydration
+
+Fastify Plugin for integration with taujs [ τjs ] template https://github.com/aoede3/taujs
+
+- Production: Fastify, React
+- Development: Fastify, React, tsx, Vite
 
 TypeScript / ESM-only focus
-τjs - DX: Developer eXperience first focus. Integrated ViteDevServer HMR + Vite Runtime API run alongside tsx (TS eXecute) providing fast responsive dev reload times for both backend / frontend
 
-Build: client (Vite) & server (ESBuild + Rollup)
+## τjs - Developer eXperience
+
+Integrated ViteDevServer HMR + Vite Runtime API run alongside tsx (TS eXecute) providing fast responsive dev reload times for both backend / frontend
 
-Fastify https://fastify.dev/
-Vite https://vitejs.dev/guide/ssr#building-for-production
-React https://reactjs.org/
+- Fastify https://fastify.dev/
+- React https://reactjs.org/
+- tsx https://tsx.is/
+- Vite https://vitejs.dev/guide/ssr#building-for-production
 
-tsx https://tsx.is/
-ViteDevServer HMR https://vitejs.dev/guide/ssr#setting-up-the-dev-server
-Vite Runtime API https://vitejs.dev/guide/api-vite-runtime
-ESBuild https://esbuild.github.io/
-Rollup https://rollupjs.org/
-ESM https://nodejs.org/api/esm.html
+- ViteDevServer HMR https://vitejs.dev/guide/ssr#setting-up-the-dev-server
+- Vite Runtime API https://vitejs.dev/guide/api-vite-runtime
+- ESBuild https://esbuild.github.io/
+- Rollup https://rollupjs.org/
+- ESM https://nodejs.org/api/esm.html
 
 ## Development / CI
 
-    "@fastify/static": "^7.0.4",
-    "path-to-regexp": "^7.0.0"
+`npm install --legacy-peer-deps`
+
+## Usage
+
+### Fastify
+
+```
+import { SSRServer } from '@taujs/server;
+
+void (await fastify.register(SSRServer, {
+    clientEntryClient: 'entry-client',
+    clientEntryServer: 'entry-server',
+    clientHtmlTemplate: 'index.html',
+    clientRoot: path.resolve(__dirname, '../client'),
+    routes,
+    serviceRegistry,
+}));
+```
+
+Not utilising taujs [ τjs ] template? Add in your own `alias` object for your own particular setup e.g. `alias: { object }`
+
+### React 'entry-client.tsx'
+
+```
+import React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { createSSRStore, SSRStoreProvider } from '@taujs/server/data-store';
+
+import AppBootstrap from './AppBootstrap';
+
+const bootstrap = () => {
+  const initialDataPromise = Promise.resolve(window.__INITIAL_DATA__);
+  const store = createSSRStore(initialDataPromise);
+
+  hydrateRoot(
+    document.getElementById('root') as HTMLElement,
+    <SSRStoreProvider store={store}>
+      <AppBootstrap />
+    </SSRStoreProvider>,
+  );
+};
+
+if (document.readyState !== 'loading') {
+  bootstrap();
+} else {
+  document.addEventListener('DOMContentLoaded', () => {
+    bootstrap();
+  });
+}
+
+```
+
+### React 'entry-server.tsx'
+
+Extended pipe object with callbacks to @taujs/server enabling additional manipulation of HEAD content from client code
+
+```
+import { ServerResponse } from 'node:http';
+
+import React from 'react';
+import { createSSRStore, SSRStoreProvider } from '@taujs/server/data-store';
+import { createStreamRenderer } from '@taujs/server/render';
+
+import AppBootstrap from '@client/AppBootstrap';
+
+import type { RenderCallbacks } from '@taujs/server';
+
+export const streamRender = (
+  serverResponse: ServerResponse,
+  { onHead, onFinish, onError }: RenderCallbacks,
+  initialDataPromise: Promise<Record<string, unknown>>,
+  bootstrapModules: string,
+) => {
+  const store = createSSRStore(initialDataPromise);
+
+  const headContent = `
+    <meta name="description" content="taujs [ τjs ]">
+    <link rel="icon" type="image/svg+xml" href="/taujs.svg" />
+    <title>taujs [ τjs ]</title>
+  `;
+
+  createStreamRenderer(
+    serverResponse,
+    { onHead, onFinish, onError },
+    {
+      appElement: (
+        <SSRStoreProvider store={store}>
+          <AppBootstrap />
+        </SSRStoreProvider>
+      ),
+      bootstrapModules,
+      getStoreSnapshot: store.getSnapshot,
+      headContent,
+    },
+  );
+};
+
+```
+
+### index.html
+
+```
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!--ssr-head-->
+  </head>
+  <body>
+    <main id="root"><!--ssr-html--></main>
+  </body>
+</html>
+```
+
+### client.d.ts
+
+```
+interface Window {
+  __INITIAL_DATA__: Record<string, unknown>;
+}
+```
+
+### 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 elsewhere syntactically not unlike 'fetch' providing params to a 'fetch' call
+2. Internally calling a service which in turn will make 'call' to return 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.
+
+```
+import type { Route, RouteParams } from '@taujs/server';
+
+export const routes: Route<RouteParams>[] = [
+  {
+    path: '/',
+    attributes: {
+      fetch: async () => {
+        return {
+          url: 'http://localhost:5173/api/initial',
+          options: {
+            method: 'GET',
+          },
+        };
+      },
+    },
+  },
+  {
+    path: '/:id',
+    attributes: {
+      fetch: async (params: RouteParams) => {
+        return {
+          url: `http://localhost:5173/api/initial/${params.id}`,
+          options: {
+            method: 'GET',
+          },
+        };
+      },
+    },
+  },
+  {
+    path: '/:id/:another',
+    attributes: {
+      fetch: async (params: RouteParams) => {
+        return {
+          options: { params },
+          serviceMethod: 'exampleMethod',
+          serviceName: 'ServiceExample',
+        };
+      },
+    },
+  },
+];
+```
+
+### Service Registry
+
+In supporting internal calls via τjs a registry of available services and methods provides the linkage to your own architectural setup and developmental patterns
+
+```
+import { ServiceExample } from './ServiceExample';
+
+import type { ServiceRegistry } from '@taujs/server';
+
+export const serviceRegistry: ServiceRegistry = {
+  ServiceExample,
+};
+```
 
-npm install --legacy-peer-deps
+```
+export const ServiceExample = {
+  async exampleMethod(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        resolve({ hello: `world internal service call response with id: ${params.id} and another: ${params.another}` });
+      }, 5500);
+    });
+  },
+};
+```

package/dist/SSRDataStore.d.ts

@@ -12,4 +12,4 @@ declare const SSRStoreProvider: React.FC<React.PropsWithChildren<{
 }>>;
 declare const useSSRStore: <T>() => SSRStore<T>;
 
-export { SSRStoreProvider, createSSRStore, useSSRStore };
+export { type SSRStore, SSRStoreProvider, createSSRStore, useSSRStore };

package/dist/SSRRender.d.ts

@@ -0,0 +1,18 @@
+import { ServerResponse } from 'node:http';
+import React from 'react';
+
+type RenderCallbacks = {
+    onHead: (headContent: string) => void;
+    onFinish: (initialDataResolved: unknown) => void;
+    onError: (error: unknown) => void;
+};
+
+type StreamRender = {
+    appElement: React.JSX.Element;
+    bootstrapModules: string;
+    headContent: string;
+    getStoreSnapshot: () => unknown;
+};
+declare const createStreamRenderer: (serverResponse: ServerResponse, { onHead, onFinish, onError }: RenderCallbacks, { appElement, bootstrapModules, headContent, getStoreSnapshot }: StreamRender) => void;
+
+export { createStreamRenderer };

package/dist/SSRRender.js

@@ -0,0 +1,31 @@
+// src/SSRRender.ts
+import { Writable } from "node:stream";
+import "react";
+import { renderToPipeableStream } from "react-dom/server";
+var createStreamRenderer = (serverResponse, { onHead, onFinish, onError }, { appElement, bootstrapModules, headContent, getStoreSnapshot }) => {
+  const { pipe } = renderToPipeableStream(appElement, {
+    bootstrapModules: [bootstrapModules],
+    onShellReady() {
+      onHead(headContent);
+      pipe(
+        new Writable({
+          write(chunk, _encoding, callback) {
+            serverResponse.write(chunk, callback);
+          },
+          final(callback) {
+            onFinish(getStoreSnapshot());
+            callback();
+          }
+        })
+      );
+    },
+    onAllReady() {
+    },
+    onError(error) {
+      onError(error);
+    }
+  });
+};
+export {
+  createStreamRenderer
+};

package/dist/SSRServer.d.ts

@@ -21,6 +21,7 @@ type FetchConfig = {
     serviceMethod?: string;
 };
 type SSRServerOptions = {
+    alias: Record<string, string>;
     clientRoot: string;
     clientHtmlTemplate: string;
     clientEntryClient: string;

package/dist/SSRServer.js

@@ -244,7 +244,7 @@ var overrideCSSHMRConsoleError = () => {
 // src/SSRServer.ts
 var SSRServer = (0, import_fastify_plugin.default)(
   async (app, opts) => {
-    const { clientRoot, clientHtmlTemplate, clientEntryClient, clientEntryServer, routes, serviceRegistry, isDebug } = opts;
+    const { alias, clientRoot, clientHtmlTemplate, clientEntryClient, clientEntryServer, routes, serviceRegistry, isDebug } = opts;
     const templateHtmlPath = path.join(clientRoot, clientHtmlTemplate);
     const templateHtml = !isDevelopment ? await fs.readFile(templateHtmlPath, "utf-8") : await fs.readFile(path.join(clientRoot, clientHtmlTemplate), "utf-8");
     const ssrManifestPath = path.join(clientRoot, ".vite/ssr-manifest.json");
@@ -283,9 +283,12 @@ var SSRServer = (0, import_fastify_plugin.default)(
         ],
         resolve: {
           alias: {
-            "@client": path.resolve(clientRoot),
-            "@server": path.resolve(__dirname),
-            "@shared": path.resolve(__dirname, "../shared")
+            ...{
+              "@client": path.resolve(clientRoot),
+              "@server": path.resolve(__dirname),
+              "@shared": path.resolve(__dirname, "../shared")
+            },
+            ...alias
           }
         },
         root: clientRoot,

package/package.json

@@ -20,7 +20,7 @@
     "type": "git",
     "url": "git+https://github.com/aoede3/taujs-server.git"
   },
-  "version": "0.0.1",
+  "version": "0.0.4",
   "exports": {
     ".": {
       "import": "./dist/SSRServer.js",
@@ -30,6 +30,10 @@
       "import": "./dist/SSRDataStore.js",
       "types": "./dist/SSRDataStore.d.ts"
     },
+    "./render": {
+      "import": "./dist/SSRRender.js",
+      "types": "./dist/SSRRender.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -41,6 +45,9 @@
     "*": {
       "data-store": [
         "./dist/SSRDataStore.d.ts"
+      ],
+      "render": [
+        "./dist/SSRRender.d.ts"
       ]
     }
   },
@@ -55,8 +62,10 @@
     "@changesets/cli": "^2.27.7",
     "@types/node": "^20.14.9",
     "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
     "fastify": "^4.28.0",
     "prettier": "^3.3.3",
+    "react-dom": "^18.3.1",
     "tsup": "^8.2.4",
     "vite": "^5.4.2",
     "vitest": "^2.0.5"