@webtypen/webframez-react 0.0.2 → 0.0.3

package/README.md

@@ -1,14 +1,14 @@
-# webframez-react
+# @webtypen/webframez-react
 
 React Server Components (RSC) extension for `@webtypen/webframez-core`.
 
-`webframez-react` provides:
-
+`@webtypen/webframez-react` provides:
 - seamless `webframez-core` integration via `initWebframezReact(Route)`
 - file-based routing for `pages/**/index.tsx`
 - layout/error handling with `RouteChildren`
 - client-side navigation (`Link`, `Redirect`, `useRouter`) and cookies (`useCookie`)
 - server-rendered initial HTML plus RSC streaming
+- a small CLI for the standard server/client build pipeline
 
 ## Requirements
 
@@ -26,111 +26,201 @@ npm i -D typescript webpack webpack-cli ts-loader
 ## Quick Start with webframez-core
 
 ```ts
-// server.ts
+// src/server.ts
+import path from "node:path";
 import { BaseKernelWeb, Route, WebApplication } from "@webtypen/webframez-core";
-import { initWebframezReact } from "@webtypen/webframez-react/webframez-core";
+import { initWebframezReact } from "@webtypen/webframez-react";
 
 class Kernel extends BaseKernelWeb {
   static controller = {};
   static middleware = {};
 }
 
-initWebframezReact(Route);
+const ReactRoute = initWebframezReact(Route);
 
 const app = new WebApplication();
 app.boot({
   kernel: Kernel,
   routesFunction: () => {
-    Route.renderReact("/react", {
-      distRootDir: `${process.cwd()}/dist`,
+    ReactRoute.renderReact("/react", {
+      distRootDir: path.resolve(process.cwd(), "dist"),
     });
   },
 });
 ```
 
 Notes:
-
 - `"/react"` is automatically registered as a catch-all route (`/react/*`).
-- `basePath`, `assetsPrefix`, `rscPath`, and `clientScriptUrl` are derived automatically from the mount path.
+- `basePath`, `assetsPrefix`, `rscPath`, and `clientScriptUrl` are derived automatically from the mount path unless you override them.
+- `initWebframezReact(Route)` returns the extended route facade, which gives you reliable editor autocompletion for `renderReact(...)` even in monorepos or symlinked development setups.
+- The package also ships module augmentation for `Route.renderReact(...)`, but using the returned `ReactRoute` variable is the most robust TypeScript setup.
 
-## Add to an Existing webframez-core Project
+## `Route.renderReact()`
 
-If you already have a running `@webtypen/webframez-core` app, this is the smallest setup to mount React and return a first JSX page.
+Signature:
 
-1. Install dependencies:
-
-```bash
-npm i @webtypen/webframez-react react react-dom react-server-dom-webpack
-npm i -D typescript webpack webpack-cli ts-loader
+```ts
+Route.renderReact(path, options)
 ```
 
-2. Extend `Route` and mount React inside your existing `routesFunction`:
+Example:
 
 ```ts
-// server.ts
-import path from "node:path";
-import { BaseKernelWeb, Route, WebApplication } from "@webtypen/webframez-core";
-import { initWebframezReact } from "@webtypen/webframez-react/webframez-core";
-
-class Kernel extends BaseKernelWeb {
-  static controller = {};
-  static middleware = {};
-}
-
-initWebframezReact(Route);
-
-const app = new WebApplication();
-app.boot({
-  kernel: Kernel,
-  port: 3000,
-  routesFunction: () => {
-    // Your existing core routes can stay here.
-    Route.renderReact("/app", {
-      distRootDir: path.resolve(process.cwd(), "dist"),
-    });
+Route.renderReact("/app", {
+  distRootDir: path.resolve(process.cwd(), "dist"),
+  method: "GET",
+  routeOptions: {
+    middleware: ["auth"],
   },
 });
 ```
 
-3. Create a minimal file-router page setup:
+### Options
+
+`distRootDir`
+- Required.
+- Directory containing the built client assets and generated manifests.
+
+`pagesDir`
+- Optional.
+- Directory containing the compiled `pages/**` output.
+- Default: `${distRootDir}/pages`
+
+`manifestPath`
+- Optional.
+- Path to the React client manifest.
+- Default: `${distRootDir}/react-client-manifest.json`
+
+`assetsPrefix`
+- Optional.
+- Public URL prefix used to serve built client assets.
+- Auto-derived from `path`.
+- Example for `"/react"`: `/react/assets/`
+
+`rscPath`
+- Optional.
+- Public URL for the RSC endpoint.
+- Auto-derived from `path`.
+- Example for `"/react"`: `/react/rsc`
+
+`clientScriptUrl`
+- Optional.
+- Public URL of the browser client entry bundle.
+- Auto-derived from `path`.
+- Example for `"/react"`: `/react/assets/client.js`
+
+`basePath`
+- Optional.
+- Basename mounted in front of all file-router paths.
+- Auto-derived from `path` when `path !== "/"`.
+
+`liveReloadPath`
+- Optional.
+- Enables dev live reload on a custom path or disables it explicitly with `false`.
+- Automatically disabled in production mode.
+
+`method`
+- Optional.
+- HTTP method or methods used to register the route.
+- Supported values: `"GET" | "POST" | "PUT" | "DELETE"`
+- Default: `"GET"`
+
+`routeOptions`
+- Optional.
+- Additional route options forwarded to `webframez-core`.
+- Typical use case: middleware.
+
+## Recommended Project Structure
 
-```tsx
-// pages/layout.tsx
-"use server";
+```txt
+pages/
+  layout.tsx
+  errors.tsx
+  index.tsx
+  about/index.tsx
+src/
+  server.ts
+  client.tsx
+  components/
+dist/
+```
 
-import React from "react";
-import { RouteChildren } from "@webtypen/webframez-react/router";
+## `tsconfig.server.json`
 
-export default function Layout() {
-  return (
-    <main>
-      <RouteChildren />
-    </main>
-  );
-}
-```
+Compared to a standard `@webtypen/webframez-core` project, the server TypeScript config usually needs a few changes:
 
-```tsx
-// pages/index.tsx
-"use server";
+- enable JSX via `"jsx": "react-jsx"`
+- include `pages/**/*.tsx`
+- include `src/components/**/*.tsx`
+- include your server entry (`src/server.ts` or `src/server.tsx`)
+- exclude the browser client entry (`src/client.tsx` by default)
+- add `paths` mappings for the `@webtypen/webframez-react` package and its subpaths
 
-import React from "react";
+When you use the CLI (`webframez-react build:server` / `watch:server`), it generates a temporary `.webframez-react.tsconfig.server.json` that extends your project `tsconfig.server.json`. That means:
 
-export default function HomePage() {
-  return <h1>Hello from webframez-react + JSX</h1>;
-}
-```
+- your own `tsconfig.server.json` stays the source of truth
+- the CLI only injects the resolved server entry and the standard RSC include/exclude rules
+- you only need to customize the base config when your project structure differs from the defaults
 
-4. Create the client entry:
+A good starting point is the shipped default config:
 
-```tsx
-// src/client.tsx
-import { mountWebframezClient } from "@webtypen/webframez-react/client";
+- `@webtypen/webframez-react/defaults/tsconfig.server`
+- `@webtypen/webframez-react/defaults/tsconfig.server.example`
 
-mountWebframezClient();
+Example:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "baseUrl": ".",
+    "paths": {
+      "@webtypen/webframez-react": [
+        "./node_modules/@webtypen/webframez-react/dist/index.d.ts"
+      ],
+      "@webtypen/webframez-react/types": [
+        "./node_modules/@webtypen/webframez-react/dist/types.d.ts"
+      ],
+      "@webtypen/webframez-react/router": [
+        "./node_modules/@webtypen/webframez-react/dist/router.d.ts"
+      ],
+      "@webtypen/webframez-react/client": [
+        "./node_modules/@webtypen/webframez-react/dist/client.d.ts"
+      ],
+      "@webtypen/webframez-react/navigation": [
+        "./node_modules/@webtypen/webframez-react/dist/navigation.d.ts"
+      ],
+      "@webtypen/webframez-react/webframez-core": [
+        "./node_modules/@webtypen/webframez-react/dist/webframez-core.d.ts"
+      ]
+    },
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": [
+    "src/server.ts",
+    "src/server.tsx",
+    "src/components/**/*.tsx",
+    "pages/**/*.tsx",
+    "src/types.d.ts"
+  ],
+  "exclude": [
+    "src/client.tsx",
+    "dist",
+    "node_modules"
+  ]
+}
 ```
 
-5. Add build scripts (with automatic config fallback):
+## `package.json` Scripts
+
+Recommended scripts:
 
 ```json
 {
@@ -138,6 +228,7 @@ mountWebframezClient();
     "build:server": "webframez-react build:server",
     "build:client": "webframez-react build:client",
     "build": "npm run build:server && npm run build:client",
+    "start": "node --conditions react-server start-server.cjs",
     "watch:server": "webframez-react watch:server",
     "watch:client": "webframez-react watch:client",
     "serve:watch": "node --watch --conditions react-server start-server.cjs",
@@ -147,9 +238,51 @@ mountWebframezClient();
 }
 ```
 
-After build, your first page is available at `http://localhost:3000/app`.
+Notes:
+- `build` compiles the server output (`pages`, `server.ts`) and the browser client bundle (`client.tsx` + RSC manifests).
+- `start` runs the built app in React Server mode.
+- `watch` / `dev` keep TypeScript and webpack in watch mode and restart Node automatically when server output changes.
+
+## CLI Config and Custom Entry Paths
+
+The CLI first checks project override files and then falls back to the package defaults:
+
+- `tsconfig.server.json`
+- `webpack.client.cjs`
+- `webpack.server.cjs`
+
+If you do not want to create your own webpack config just to move `client.tsx` or `server.ts`, you can use a small project config file:
+
+```js
+// webframez-react.config.mjs
+export default {
+  clientEntryPath: "src/app/client.tsx",
+  serverEntryPath: "src/app/server.tsx",
+};
+```
+
+Supported file names:
+- `webframez-react.config.mjs`
+- `webframez-react.config.cjs`
+- `webframez-react.config.js`
+- `webframez-react.config.json`
+
+You can also override the entry paths per command:
+
+```bash
+webframez-react build:client --client-entry=src/app/client.tsx
+webframez-react build:server --server-entry=src/app/server.tsx
+webframez-react watch:client --client-entry=src/app/client.tsx
+webframez-react watch:server --server-entry=src/app/server.tsx
+```
+
+Notes:
+- The default client entry is `src/client.tsx`.
+- The default server entry is `src/server.ts`, with automatic fallback to `src/server.tsx` if present.
+- `build:server:webpack` and `watch:server:webpack` also respect `serverEntryPath`.
+- `build:server` and `watch:server` generate a temporary `.webframez-react.tsconfig.server.json` so custom server entry paths also work with the TypeScript compiler.
 
-## Page Structure (File-Based Routing)
+## File-Based Routing
 
 Example:
 
@@ -205,9 +338,8 @@ export default function AccountPage({ params, abort }: PageProps) {
 ```
 
 Behavior:
-
 - default without options: `404` + `"Page not found"`
-- rendered through `pages/errors.tsx` (same behavior as unmatched routes)
+- rendered through `pages/errors.tsx`
 - `pathname` is provided automatically by context
 - optional `payload` is forwarded to `errors.tsx`
 
@@ -255,8 +387,7 @@ export function Guard({ loggedIn }: { loggedIn: boolean }) {
 }
 ```
 
-Note:
-
+Notes:
 - `Link` and `Redirect` automatically use the basename from `Route.renderReact()`.
 - You can override it per usage via `basename`.
 
@@ -288,7 +419,12 @@ export default function LoginAction() {
 ## Public Entrypoints
 
 - `@webtypen/webframez-react`
-  - `createNodeRequestHandler`, `createFileRouter`, `createHTMLShell`, `sendRSC`, `createRSCHandler`
+  - `initWebframezReact`
+  - `createNodeRequestHandler`
+  - `createFileRouter`
+  - `createHTMLShell`
+  - `sendRSC`
+  - `createRSCHandler`
 - `@webtypen/webframez-react/webframez-core`
   - `initWebframezReact`
 - `@webtypen/webframez-react/router`
@@ -298,48 +434,17 @@ export default function LoginAction() {
 - `@webtypen/webframez-react/navigation`
   - `Link`, `Redirect`
 - `@webtypen/webframez-react/types`
-  - all public types (`RouteContext`, `PageProps`, `ErrorPageProps`, ...)
+  - `RouteContext`, `PageProps`, `ErrorPageProps`, `AbortRouteOptions`, ...
 
-## package.json Scripts
-
-Example scripts for a `webframez-react` app:
-
-```json
-{
-  "scripts": {
-    "build:server": "webframez-react build:server",
-    "build:client": "webframez-react build:client",
-    "build": "npm run build:server && npm run build:client",
-    "start": "node --conditions react-server start-server.cjs",
-    "watch:server": "webframez-react watch:server",
-    "watch:client": "webframez-react watch:client",
-    "serve:watch": "node --watch --conditions react-server start-server.cjs",
-    "watch": "sh -c 'npm run watch:server & npm run watch:client & npm run serve:watch & wait'",
-    "dev": "sh -c 'npm run watch:server & npm run watch:client & npm run serve:watch & wait'"
-  }
-}
-```
-
-Notes:
-
-- `webframez-react` CLI first checks project overrides and falls back to package defaults:
-  - `tsconfig.server.json`
-  - `webpack.client.cjs`
-  - `webpack.server.cjs`
-- `webpack.server.cjs` is optional. Default flow compiles server with `tsc`. Use webpack-server only if you explicitly want a bundled server build:
-  - `webframez-react build:server:webpack`
-  - `webframez-react watch:server:webpack`
-- `build` compiles server output (`pages`, `server.ts`) and client output (`client.tsx` bundle + RSC manifests).
-- `start` runs the built app in React Server mode.
-- `watch` and `dev` run the same full watch pipeline and restart Node automatically on server output changes.
+## Package Build
 
-## Build
+Build the package itself:
 
 ```bash
 npm run build
 ```
 
-Watch mode:
+Watch mode for package development:
 
 ```bash
 npm run build:watch

package/bin/webframez-react.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import fsp from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const binFilePath = fileURLToPath(import.meta.url);
 const packageRoot = path.resolve(path.dirname(binFilePath), "..");
@@ -12,6 +13,7 @@ const projectRoot = process.cwd();
 const command = process.argv[2];
 const passthroughStart = process.argv[3] === "--" ? 4 : 3;
 const passthroughArgs = process.argv.slice(passthroughStart);
+const customArgPrefixes = ["--client-entry", "--server-entry"];
 
 function printHelp() {
   console.log(
@@ -34,6 +36,13 @@ function printHelp() {
       "  - tsconfig.server.json",
       "  - webpack.client.cjs",
       "  - webpack.server.cjs",
+      "",
+      "Optional project config file:",
+      "  - webframez-react.config.mjs|cjs|js|json",
+      "",
+      "Optional CLI overrides:",
+      "  --client-entry=src/client.tsx",
+      "  --server-entry=src/server.ts",
     ].join("\n"),
   );
 }
@@ -42,6 +51,43 @@ function hasFlag(flag) {
   return passthroughArgs.includes(flag);
 }
 
+function normalizeRelativePath(value) {
+  return value.replace(/\\/g, "/");
+}
+
+function readCustomArg(name) {
+  const withEquals = `${name}=`;
+  for (let index = 0; index < passthroughArgs.length; index += 1) {
+    const value = passthroughArgs[index];
+    if (value === name) {
+      return passthroughArgs[index + 1] || null;
+    }
+    if (value.startsWith(withEquals)) {
+      return value.slice(withEquals.length);
+    }
+  }
+  return null;
+}
+
+function stripCustomArgs(args) {
+  const filtered = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    const matchedPrefix = customArgPrefixes.find(
+      (prefix) => value === prefix || value.startsWith(`${prefix}=`),
+    );
+    if (!matchedPrefix) {
+      filtered.push(value);
+      continue;
+    }
+
+    if (value === matchedPrefix) {
+      index += 1;
+    }
+  }
+  return filtered;
+}
+
 function resolveConfig(localFileName, fallbackFileName) {
   const localPath = path.resolve(projectRoot, localFileName);
   if (fs.existsSync(localPath)) {
@@ -69,7 +115,78 @@ function resolveBinary(name) {
   return name;
 }
 
-function run(binaryName, args) {
+async function loadProjectConfig() {
+  const configFiles = [
+    "webframez-react.config.mjs",
+    "webframez-react.config.cjs",
+    "webframez-react.config.js",
+    "webframez-react.config.json",
+  ];
+
+  for (const fileName of configFiles) {
+    const filePath = path.resolve(projectRoot, fileName);
+    if (!fs.existsSync(filePath)) {
+      continue;
+    }
+
+    if (fileName.endsWith(".json")) {
+      return JSON.parse(await fsp.readFile(filePath, "utf8"));
+    }
+
+    const imported = await import(pathToFileURL(filePath).href);
+    return imported.default ?? imported;
+  }
+
+  return {};
+}
+
+function resolveEntryPath(projectConfig, customArgValue, configKey, defaults) {
+  const configuredValue = customArgValue || projectConfig?.[configKey];
+  if (configuredValue && typeof configuredValue === "string") {
+    return path.resolve(projectRoot, configuredValue);
+  }
+
+  for (const defaultPath of defaults) {
+    const resolved = path.resolve(projectRoot, defaultPath);
+    if (fs.existsSync(resolved)) {
+      return resolved;
+    }
+  }
+
+  return path.resolve(projectRoot, defaults[0]);
+}
+
+async function createServerTsConfig(baseConfig, serverEntryPath, clientEntryPath) {
+  const generatedPath = path.resolve(projectRoot, ".webframez-react.tsconfig.server.json");
+  const extendsPath =
+    baseConfig.source === "project"
+      ? `./${normalizeRelativePath(path.basename(baseConfig.path))}`
+      : normalizeRelativePath(path.relative(projectRoot, baseConfig.path));
+
+  const include = [
+    normalizeRelativePath(path.relative(projectRoot, serverEntryPath)),
+    "src/components/**/*.tsx",
+    "pages/**/*.tsx",
+    "src/types.d.ts",
+  ];
+
+  const exclude = [
+    normalizeRelativePath(path.relative(projectRoot, clientEntryPath)),
+    "dist",
+    "node_modules",
+  ];
+
+  const generatedConfig = {
+    extends: extendsPath,
+    include: Array.from(new Set(include)),
+    exclude: Array.from(new Set(exclude)),
+  };
+
+  await fsp.writeFile(generatedPath, JSON.stringify(generatedConfig, null, 2));
+  return generatedPath;
+}
+
+function run(binaryName, args, envAdditions = {}) {
   const binary = resolveBinary(binaryName);
 
   return new Promise((resolve, reject) => {
@@ -77,6 +194,10 @@ function run(binaryName, args) {
       cwd: projectRoot,
       stdio: "inherit",
       shell: false,
+      env: {
+        ...process.env,
+        ...envAdditions,
+      },
     });
 
     child.on("error", (error) => {
@@ -95,11 +216,35 @@ async function main() {
     return;
   }
 
+  const projectConfig = await loadProjectConfig();
+  const customClientEntry = readCustomArg("--client-entry");
+  const customServerEntry = readCustomArg("--server-entry");
+  const passthroughArgsClean = stripCustomArgs(passthroughArgs);
+
+  const clientEntryPath = resolveEntryPath(
+    projectConfig,
+    customClientEntry,
+    "clientEntryPath",
+    ["src/client.tsx"],
+  );
+  const serverEntryPath = resolveEntryPath(
+    projectConfig,
+    customServerEntry,
+    "serverEntryPath",
+    ["src/server.ts", "src/server.tsx"],
+  );
+
   if (command === "build:server" || command === "watch:server") {
     const config = resolveConfig("tsconfig.server.json", "tsconfig.server.json");
+    const generatedConfigPath = await createServerTsConfig(
+      config,
+      serverEntryPath,
+      clientEntryPath,
+    );
     console.log(`[webframez-react] tsc config (${config.source}): ${config.path}`);
+    console.log(`[webframez-react] server entry: ${serverEntryPath}`);
 
-    const args = ["-p", config.path, ...passthroughArgs];
+    const args = ["-p", generatedConfigPath, ...passthroughArgsClean];
     if (command === "watch:server") {
       if (!hasFlag("--watch")) {
         args.push("--watch");
@@ -117,13 +262,16 @@ async function main() {
   if (command === "build:client" || command === "watch:client") {
     const config = resolveConfig("webpack.client.cjs", "webpack.client.cjs");
     console.log(`[webframez-react] webpack config (${config.source}): ${config.path}`);
+    console.log(`[webframez-react] client entry: ${clientEntryPath}`);
 
-    const args = ["--config", config.path, ...passthroughArgs];
+    const args = ["--config", config.path, ...passthroughArgsClean];
     if (command === "watch:client" && !hasFlag("--watch")) {
       args.push("--watch");
     }
 
-    const code = await run("webpack", args);
+    const code = await run("webpack", args, {
+      WEBFRAMEZ_REACT_CLIENT_ENTRY: clientEntryPath,
+    });
     process.exit(code);
     return;
   }
@@ -131,13 +279,16 @@ async function main() {
   if (command === "build:server:webpack" || command === "watch:server:webpack") {
     const config = resolveConfig("webpack.server.cjs", "webpack.server.cjs");
     console.log(`[webframez-react] webpack server config (${config.source}): ${config.path}`);
+    console.log(`[webframez-react] server entry: ${serverEntryPath}`);
 
-    const args = ["--config", config.path, ...passthroughArgs];
+    const args = ["--config", config.path, ...passthroughArgsClean];
     if (command === "watch:server:webpack" && !hasFlag("--watch")) {
       args.push("--watch");
     }
 
-    const code = await run("webpack", args);
+    const code = await run("webpack", args, {
+      WEBFRAMEZ_REACT_SERVER_ENTRY: serverEntryPath,
+    });
     process.exit(code);
     return;
   }