@finesoft/front 0.1.2 → 0.1.11

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 (16) hide show
  1. package/README.md +153 -9
  2. package/dist/browser.cjs +1214 -0
  3. package/dist/browser.cjs.map +1 -0
  4. package/dist/browser.d.cts +751 -0
  5. package/dist/browser.d.ts +751 -0
  6. package/dist/browser.js +97 -0
  7. package/dist/browser.js.map +1 -0
  8. package/dist/chunk-OVGQ4NUA.js +1143 -0
  9. package/dist/chunk-OVGQ4NUA.js.map +1 -0
  10. package/dist/index.cjs +209 -43
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +16 -1184
  13. package/dist/index.d.ts +16 -1184
  14. package/dist/index.js +191 -1071
  15. package/dist/index.js.map +1 -1
  16. package/package.json +11 -6
package/README.md CHANGED
@@ -10,13 +10,46 @@ Full-stack framework for building content-driven web applications with SSR suppo
10
10
  - **SSR** — server-side rendering pipeline with data serialization
11
11
  - **Server** — one-shot factory for Hono + Vite + SSR (Node / Deno / Bun)
12
12
  - **Browser Runtime** — app bootstrap, action handlers, history management
13
+ - **Browser Export Condition** — browser builds exclude server-only code automatically
13
14
 
14
15
  ## Install
15
16
 
17
+ ### Browser-only usage
18
+
16
19
  ```bash
17
20
  npm install @finesoft/front
18
21
  ```
19
22
 
23
+ ### SSR / full-stack usage
24
+
25
+ If you use `createServer()` or other server exports, install the peer dependencies too:
26
+
27
+ ```bash
28
+ npm install @finesoft/front hono vite @hono/node-server dotenv
29
+ ```
30
+
31
+ ### Peer dependencies
32
+
33
+ - `hono` — required for server usage
34
+ - `vite` — required for development SSR server usage
35
+ - `@hono/node-server` — required for Node.js server startup
36
+ - `dotenv` — optional, only needed if you want `.env` auto-loading in `createServer()`
37
+
38
+ ## Package entry behavior
39
+
40
+ `@finesoft/front` ships a browser-aware export map.
41
+
42
+ - In browser bundles, the `browser` condition resolves to the browser-only entry and excludes server code.
43
+ - In SSR / Node environments, the default import resolves to the full entry with browser + SSR + server exports.
44
+
45
+ That means you can keep importing from:
46
+
47
+ ```ts
48
+ import { startBrowserApp } from "@finesoft/front";
49
+ ```
50
+
51
+ and modern bundlers will avoid pulling in `createServer`, `startServer`, and other server-only code on the client side.
52
+
20
53
  ## Quick Start
21
54
 
22
55
  ### Server
@@ -27,38 +60,149 @@ import { createServer } from "@finesoft/front";
27
60
  const { app } = await createServer({
28
61
  locales: ["en-US", "zh-CN"],
29
62
  defaultLocale: "en-US",
30
- ssrEntry: "./src/ssr.ts",
63
+ port: 3000,
64
+ ssr: { ssrEntryPath: "/src/ssr.ts" },
31
65
  setup(app) {
32
66
  // register custom routes on the Hono app
33
67
  },
34
68
  });
35
69
  ```
36
70
 
71
+ Notes:
72
+
73
+ - `root` defaults to `process.cwd()`
74
+ - `port` defaults to `process.env.PORT ?? 3000`
75
+ - if a `.env` file exists at the project root, `createServer()` will try to load it automatically
76
+
37
77
  ### Browser
38
78
 
39
79
  ```ts
40
80
  import { startBrowserApp, Framework, defineRoutes } from "@finesoft/front";
41
81
 
42
- const routes = defineRoutes([
43
- { path: "/", intent: "home-page" },
44
- { path: "/app/:id", intent: "product-page" },
45
- ]);
46
-
47
- const framework = new Framework({ routes });
48
- startBrowserApp({ framework });
82
+ function bootstrap(framework: Framework) {
83
+ defineRoutes(framework, [
84
+ { path: "/", intentId: "home-page", controller: new HomeController() },
85
+ {
86
+ path: "/app/:id",
87
+ intentId: "product-page",
88
+ controller: new ProductController(),
89
+ },
90
+ ]);
91
+ }
92
+
93
+ startBrowserApp({
94
+ bootstrap,
95
+ mountId: "app",
96
+ mount: (target, { framework, locale }) => {
97
+ // mount your app (Svelte / React / Vue)
98
+ return ({ page }) => {
99
+ /* update on navigation */
100
+ };
101
+ },
102
+ callbacks: {
103
+ onNavigationStart: () => {},
104
+ onNavigationEnd: () => {},
105
+ },
106
+ });
49
107
  ```
50
108
 
109
+ Notes:
110
+
111
+ - `mountId` defaults to `"app"`
112
+ - `locale` is resolved from `document.documentElement.lang` first, then falls back to `defaultLocale`
113
+ - `startBrowserApp()` automatically reads prefetched server data from the DOM and performs the initial route action
114
+
51
115
  ### SSR Entry
52
116
 
53
117
  ```ts
54
118
  import { createSSRRender, serializeServerData } from "@finesoft/front";
55
119
 
56
120
  export const render = createSSRRender({
57
- /* ... */
121
+ bootstrap,
122
+ getErrorPage: (status, message) => ({ title: message }),
123
+ renderApp: (page, locale) => {
124
+ // render your app to HTML
125
+ return { html: "", head: "", css: "" };
126
+ },
58
127
  });
59
128
  export { serializeServerData };
60
129
  ```
61
130
 
131
+ `createSSRRender()` returns a `render(url, locale)` function compatible with the SSR module shape expected by `createServer()`.
132
+
133
+ ### HTML Template
134
+
135
+ Your `index.html` must include SSR placeholders:
136
+
137
+ ```html
138
+ <!doctype html>
139
+ <html lang="<!--ssr-lang-->">
140
+ <head>
141
+ <!--ssr-head-->
142
+ </head>
143
+ <body>
144
+ <div id="app"><!--ssr-body--></div>
145
+ <!--ssr-data-->
146
+ <script type="module" src="/src/browser.ts"></script>
147
+ </body>
148
+ </html>
149
+ ```
150
+
151
+ | Placeholder | Replaced with |
152
+ | ----------------- | ------------------------------------------ |
153
+ | `<!--ssr-lang-->` | Locale string (e.g. `en`) |
154
+ | `<!--ssr-head-->` | `<head>` content + CSS |
155
+ | `<!--ssr-body-->` | Server-rendered HTML |
156
+ | `<!--ssr-data-->` | `<script>` tag with serialized server data |
157
+
158
+ These are also available as `SSR_PLACEHOLDERS.LANG`, `.HEAD`, `.BODY`, `.DATA` constants.
159
+
160
+ `injectSSRContent()` automatically wraps serialized server data in a `<script>` tag for the `<!--ssr-data-->` placeholder.
161
+
162
+ ## Common patterns
163
+
164
+ ### Browser-only app
165
+
166
+ Use `startBrowserApp()` together with your framework mount callback. Browser bundlers will resolve the browser-only export automatically.
167
+
168
+ ### Full SSR app
169
+
170
+ Use the three pieces together:
171
+
172
+ 1. `createServer()` — dev/prod server bootstrap
173
+ 2. `createSSRRender()` — SSR render function factory
174
+ 3. `startBrowserApp()` — client hydration
175
+
176
+ ## Selected exports
177
+
178
+ ### Browser
179
+
180
+ - `startBrowserApp`
181
+ - `History`
182
+ - `registerActionHandlers`
183
+ - `registerExternalUrlHandler`
184
+ - `registerFlowActionHandler`
185
+ - `deserializeServerData`
186
+ - `createPrefetchedIntentsFromDom`
187
+ - `tryScroll`
188
+
189
+ ### SSR
190
+
191
+ - `createSSRRender`
192
+ - `ssrRender`
193
+ - `injectSSRContent`
194
+ - `serializeServerData`
195
+ - `SSR_PLACEHOLDERS`
196
+
197
+ ### Server
198
+
199
+ - `createServer`
200
+ - `createSSRApp`
201
+ - `startServer`
202
+ - `parseAcceptLanguage`
203
+ - `detectRuntime`
204
+ - `resolveRoot`
205
+
62
206
  ## API Overview
63
207
 
64
208
  | Category | Key Exports |