@finesoft/front 0.1.3 → 0.1.12

package/README.md

@@ -4,19 +4,52 @@ Full-stack framework for building content-driven web applications with SSR suppo
 
 ## Features
 
-- **Router** — file-system-style route definitions with intent-driven navigation
-- **DI Container** — lightweight dependency injection for controllers and services
-- **Actions & Intents** — declarative navigation model (FlowAction, ExternalUrlAction)
-- **SSR** — server-side rendering pipeline with data serialization
-- **Server** — one-shot factory for Hono + Vite + SSR (Node / Deno / Bun)
-- **Browser Runtime** — app bootstrap, action handlers, history management
+-   **Router** — file-system-style route definitions with intent-driven navigation
+-   **DI Container** — lightweight dependency injection for controllers and services
+-   **Actions & Intents** — declarative navigation model (FlowAction, ExternalUrlAction)
+-   **SSR** — server-side rendering pipeline with data serialization
+-   **Server** — one-shot factory for Hono + Vite + SSR (Node / Deno / Bun)
+-   **Browser Runtime** — app bootstrap, action handlers, history management
+-   **Browser Export Condition** — browser builds exclude server-only code automatically
 
 ## Install
 
+### Browser-only usage
+
 ```bash
 npm install @finesoft/front
 ```
 
+### SSR / full-stack usage
+
+If you use `createServer()` or other server exports, install the peer dependencies too:
+
+```bash
+npm install @finesoft/front hono vite @hono/node-server dotenv
+```
+
+### Peer dependencies
+
+-   `hono` — required for server usage
+-   `vite` — required for development SSR server usage
+-   `@hono/node-server` — required for Node.js server startup
+-   `dotenv` — optional, only needed if you want `.env` auto-loading in `createServer()`
+
+## Package entry behavior
+
+`@finesoft/front` ships a browser-aware export map.
+
+-   In browser bundles, the `browser` condition resolves to the browser-only entry and excludes server code.
+-   In SSR / Node environments, the default import resolves to the full entry with browser + SSR + server exports.
+
+That means you can keep importing from:
+
+```ts
+import { startBrowserApp } from "@finesoft/front";
+```
+
+and modern bundlers will avoid pulling in `createServer`, `startServer`, and other server-only code on the client side.
+
 ## Quick Start
 
 ### Server
@@ -27,38 +60,149 @@ import { createServer } from "@finesoft/front";
 const { app } = await createServer({
 	locales: ["en-US", "zh-CN"],
 	defaultLocale: "en-US",
-	ssrEntry: "./src/ssr.ts",
+	port: 3000,
+	ssr: { ssrEntryPath: "/src/ssr.ts" },
 	setup(app) {
 		// register custom routes on the Hono app
 	},
 });
 ```
 
+Notes:
+
+-   `root` defaults to `process.cwd()`
+-   `port` defaults to `process.env.PORT ?? 3000`
+-   if a `.env` file exists at the project root, `createServer()` will try to load it automatically
+
 ### Browser
 
 ```ts
 import { startBrowserApp, Framework, defineRoutes } from "@finesoft/front";
 
-const routes = defineRoutes([
-	{ path: "/", intent: "home-page" },
-	{ path: "/app/:id", intent: "product-page" },
-]);
-
-const framework = new Framework({ routes });
-startBrowserApp({ framework });
+function bootstrap(framework: Framework) {
+	defineRoutes(framework, [
+		{ path: "/", intentId: "home-page", controller: new HomeController() },
+		{
+			path: "/app/:id",
+			intentId: "product-page",
+			controller: new ProductController(),
+		},
+	]);
+}
+
+startBrowserApp({
+	bootstrap,
+	mountId: "app",
+	mount: (target, { framework, locale }) => {
+		// mount your app (Svelte / React / Vue)
+		return ({ page }) => {
+			/* update on navigation */
+		};
+	},
+	callbacks: {
+		onNavigationStart: () => {},
+		onNavigationEnd: () => {},
+	},
+});
 ```
 
+Notes:
+
+-   `mountId` defaults to `"app"`
+-   `locale` is resolved from `document.documentElement.lang` first, then falls back to `defaultLocale`
+-   `startBrowserApp()` automatically reads prefetched server data from the DOM and performs the initial route action
+
 ### SSR Entry
 
 ```ts
 import { createSSRRender, serializeServerData } from "@finesoft/front";
 
 export const render = createSSRRender({
-	/* ... */
+	bootstrap,
+	getErrorPage: (status, message) => ({ title: message }),
+	renderApp: (page, locale) => {
+		// render your app to HTML
+		return { html: "", head: "", css: "" };
+	},
 });
 export { serializeServerData };
 ```
 
+`createSSRRender()` returns a `render(url, locale)` function compatible with the SSR module shape expected by `createServer()`.
+
+### HTML Template
+
+Your `index.html` must include SSR placeholders:
+
+```html
+<!DOCTYPE html>
+<html lang="<!--ssr-lang-->">
+	<head>
+		<!--ssr-head-->
+	</head>
+	<body>
+		<div id="app"><!--ssr-body--></div>
+		<!--ssr-data-->
+		<script type="module" src="/src/browser.ts"></script>
+	</body>
+</html>
+```
+
+| Placeholder       | Replaced with                              |
+| ----------------- | ------------------------------------------ |
+| `<!--ssr-lang-->` | Locale string (e.g. `en`)                  |
+| `<!--ssr-head-->` | `<head>` content + CSS                     |
+| `<!--ssr-body-->` | Server-rendered HTML                       |
+| `<!--ssr-data-->` | `<script>` tag with serialized server data |
+
+These are also available as `SSR_PLACEHOLDERS.LANG`, `.HEAD`, `.BODY`, `.DATA` constants.
+
+`injectSSRContent()` automatically wraps serialized server data in a `<script>` tag for the `<!--ssr-data-->` placeholder.
+
+## Common patterns
+
+### Browser-only app
+
+Use `startBrowserApp()` together with your framework mount callback. Browser bundlers will resolve the browser-only export automatically.
+
+### Full SSR app
+
+Use the three pieces together:
+
+1. `createServer()` — dev/prod server bootstrap
+2. `createSSRRender()` — SSR render function factory
+3. `startBrowserApp()` — client hydration
+
+## Selected exports
+
+### Browser
+
+-   `startBrowserApp`
+-   `History`
+-   `registerActionHandlers`
+-   `registerExternalUrlHandler`
+-   `registerFlowActionHandler`
+-   `deserializeServerData`
+-   `createPrefetchedIntentsFromDom`
+-   `tryScroll`
+
+### SSR
+
+-   `createSSRRender`
+-   `ssrRender`
+-   `injectSSRContent`
+-   `serializeServerData`
+-   `SSR_PLACEHOLDERS`
+
+### Server
+
+-   `createServer`
+-   `createSSRApp`
+-   `startServer`
+-   `parseAcceptLanguage`
+-   `detectRuntime`
+-   `resolveRoot`
+
 ## API Overview
 
 | Category | Key Exports                                                                     |