heliumts 0.10.2 → 0.11.0

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 (156) hide show
  1. package/README.md +45 -46
  2. package/dist/bin/helium.js +117 -172
  3. package/dist/bin/helium.js.map +1 -1
  4. package/dist/bin/projectCommands.d.ts +59 -0
  5. package/dist/bin/projectCommands.d.ts.map +1 -0
  6. package/dist/bin/projectCommands.js +103 -0
  7. package/dist/bin/projectCommands.js.map +1 -0
  8. package/dist/bin/publicApi.d.ts +30 -0
  9. package/dist/bin/publicApi.d.ts.map +1 -0
  10. package/dist/bin/publicApi.js +155 -0
  11. package/dist/bin/publicApi.js.map +1 -0
  12. package/dist/client/Router.d.ts.map +1 -1
  13. package/dist/client/Router.js +5 -1
  14. package/dist/client/Router.js.map +1 -1
  15. package/dist/client/callMethod.d.ts +2 -2
  16. package/dist/client/callMethod.d.ts.map +1 -1
  17. package/dist/client/callMethod.js +3 -2
  18. package/dist/client/callMethod.js.map +1 -1
  19. package/dist/client/index.d.ts +3 -1
  20. package/dist/client/index.d.ts.map +1 -1
  21. package/dist/client/index.js +1 -2
  22. package/dist/client/index.js.map +1 -1
  23. package/dist/client/pageModules.d.ts +18 -0
  24. package/dist/client/pageModules.d.ts.map +1 -0
  25. package/dist/client/pageModules.js +3 -0
  26. package/dist/client/pageModules.js.map +1 -0
  27. package/dist/client/routerManifest.d.ts +2 -11
  28. package/dist/client/routerManifest.d.ts.map +1 -1
  29. package/dist/client/routerManifest.js +15 -187
  30. package/dist/client/routerManifest.js.map +1 -1
  31. package/dist/client/types.d.ts +12 -12
  32. package/dist/client/types.d.ts.map +1 -1
  33. package/dist/client/types.js +8 -1
  34. package/dist/client/types.js.map +1 -1
  35. package/dist/client/useCall.d.ts +20 -9
  36. package/dist/client/useCall.d.ts.map +1 -1
  37. package/dist/client/useCall.js +21 -6
  38. package/dist/client/useCall.js.map +1 -1
  39. package/dist/client/useFetch.d.ts +3 -3
  40. package/dist/client/useFetch.d.ts.map +1 -1
  41. package/dist/client/useFetch.js +8 -5
  42. package/dist/client/useFetch.js.map +1 -1
  43. package/dist/client/useStreaming.d.ts +3 -3
  44. package/dist/client/useStreaming.d.ts.map +1 -1
  45. package/dist/client/useStreaming.js +9 -7
  46. package/dist/client/useStreaming.js.map +1 -1
  47. package/dist/internal/index.d.ts +4 -0
  48. package/dist/internal/index.d.ts.map +1 -0
  49. package/dist/internal/index.js +4 -0
  50. package/dist/internal/index.js.map +1 -0
  51. package/dist/runtime/pageRoutes.d.ts +11 -0
  52. package/dist/runtime/pageRoutes.d.ts.map +1 -0
  53. package/dist/runtime/pageRoutes.js +50 -0
  54. package/dist/runtime/pageRoutes.js.map +1 -0
  55. package/dist/server/defineMethod.d.ts +16 -2
  56. package/dist/server/defineMethod.d.ts.map +1 -1
  57. package/dist/server/defineMethod.js +27 -3
  58. package/dist/server/defineMethod.js.map +1 -1
  59. package/dist/server/defineWorker.d.ts.map +1 -1
  60. package/dist/server/defineWorker.js +4 -6
  61. package/dist/server/defineWorker.js.map +1 -1
  62. package/dist/server/devServer.d.ts +2 -1
  63. package/dist/server/devServer.d.ts.map +1 -1
  64. package/dist/server/devServer.js +6 -9
  65. package/dist/server/devServer.js.map +1 -1
  66. package/dist/server/index.d.ts +16 -9
  67. package/dist/server/index.d.ts.map +1 -1
  68. package/dist/server/index.js +9 -12
  69. package/dist/server/index.js.map +1 -1
  70. package/dist/server/prodServer.d.ts +2 -0
  71. package/dist/server/prodServer.d.ts.map +1 -1
  72. package/dist/server/prodServer.js +7 -5
  73. package/dist/server/prodServer.js.map +1 -1
  74. package/dist/server/ssr.d.ts +4 -1
  75. package/dist/server/ssr.d.ts.map +1 -1
  76. package/dist/server/ssr.js +27 -61
  77. package/dist/server/ssr.js.map +1 -1
  78. package/dist/vite/heliumPlugin.d.ts +0 -14
  79. package/dist/vite/heliumPlugin.d.ts.map +1 -1
  80. package/dist/vite/heliumPlugin.js +68 -294
  81. package/dist/vite/heliumPlugin.js.map +1 -1
  82. package/dist/vite/paths.d.ts +0 -2
  83. package/dist/vite/paths.d.ts.map +1 -1
  84. package/dist/vite/paths.js +0 -2
  85. package/dist/vite/paths.js.map +1 -1
  86. package/dist/vite/rpcDiscovery.d.ts +10 -0
  87. package/dist/vite/rpcDiscovery.d.ts.map +1 -0
  88. package/dist/vite/rpcDiscovery.js +237 -0
  89. package/dist/vite/rpcDiscovery.js.map +1 -0
  90. package/dist/vite/rpcModule.d.ts +4 -0
  91. package/dist/vite/rpcModule.d.ts.map +1 -0
  92. package/dist/vite/rpcModule.js +64 -0
  93. package/dist/vite/rpcModule.js.map +1 -0
  94. package/dist/vite/scanner.d.ts +14 -4
  95. package/dist/vite/scanner.d.ts.map +1 -1
  96. package/dist/vite/scanner.js +130 -236
  97. package/dist/vite/scanner.js.map +1 -1
  98. package/dist/vite/serverClientAdapter.d.ts +103 -0
  99. package/dist/vite/serverClientAdapter.d.ts.map +1 -0
  100. package/dist/vite/serverClientAdapter.js +139 -0
  101. package/dist/vite/serverClientAdapter.js.map +1 -0
  102. package/dist/vite/ssg.d.ts +5 -8
  103. package/dist/vite/ssg.d.ts.map +1 -1
  104. package/dist/vite/ssg.js +32 -263
  105. package/dist/vite/ssg.js.map +1 -1
  106. package/dist/vite/virtualServerModule.d.ts +4 -4
  107. package/dist/vite/virtualServerModule.d.ts.map +1 -1
  108. package/dist/vite/virtualServerModule.js +18 -62
  109. package/dist/vite/virtualServerModule.js.map +1 -1
  110. package/docs/agent/api-reference.md +45 -0
  111. package/docs/agent/editable-forms.md +37 -0
  112. package/docs/agent/guide-get.md +13 -0
  113. package/docs/agent/guide-index.md +15 -0
  114. package/docs/agent/http-handlers.md +9 -0
  115. package/docs/agent/imports.md +16 -0
  116. package/docs/agent/index.md +48 -0
  117. package/docs/agent/input-validation.md +9 -0
  118. package/docs/agent/measuring.md +7 -0
  119. package/docs/agent/mutations.md +11 -0
  120. package/docs/agent/operations.md +9 -0
  121. package/docs/agent/query-params.md +28 -0
  122. package/docs/agent/rendering.md +9 -0
  123. package/docs/agent/request-context.md +13 -0
  124. package/docs/agent/routing.md +11 -0
  125. package/docs/agent/scaffold.md +15 -0
  126. package/docs/agent/security.md +9 -0
  127. package/docs/agent/server-files.md +9 -0
  128. package/docs/agent/streaming.md +9 -0
  129. package/docs/agent/validation-page.md +21 -0
  130. package/docs/agent/validation.md +33 -0
  131. package/docs/agent/verify.md +19 -0
  132. package/docs/agent/workflow.md +11 -0
  133. package/docs/agent-guide.md +266 -0
  134. package/docs/agent-start.md +87 -0
  135. package/docs/migration-0.11.md +15 -0
  136. package/package.json +20 -5
  137. package/dist/server/handlerLoader.d.ts +0 -1
  138. package/dist/server/handlerLoader.d.ts.map +0 -1
  139. package/dist/server/handlerLoader.js +0 -2
  140. package/dist/server/handlerLoader.js.map +0 -1
  141. package/dist/server/ipExtractor.d.ts +0 -48
  142. package/dist/server/ipExtractor.d.ts.map +0 -1
  143. package/dist/server/ipExtractor.js +0 -96
  144. package/dist/server/ipExtractor.js.map +0 -1
  145. package/dist/server/requestRouting.d.ts +0 -4
  146. package/dist/server/requestRouting.d.ts.map +0 -1
  147. package/dist/server/requestRouting.js +0 -67
  148. package/dist/server/requestRouting.js.map +0 -1
  149. package/dist/utils/deepEqual.d.ts +0 -1
  150. package/dist/utils/deepEqual.d.ts.map +0 -1
  151. package/dist/utils/deepEqual.js +0 -2
  152. package/dist/utils/deepEqual.js.map +0 -1
  153. package/dist/utils/formatError.d.ts +0 -2
  154. package/dist/utils/formatError.d.ts.map +0 -1
  155. package/dist/utils/formatError.js +0 -18
  156. package/dist/utils/formatError.js.map +0 -1
package/README.md CHANGED
@@ -7,13 +7,14 @@
7
7
 
8
8
  HeliumTS is a lightweight, opinionated full-stack React + Vite framework designed for simplicity and type safety. It provides typed RPC communication and file-based routing.
9
9
 
10
+ For coding agents, start with the [one-read application context](docs/agent-start.md), keep server logic in `src/server`, and use generated RPC references in pages. Exact API/route lookups are available when a specific gap remains.
11
+
10
12
  ## Table of Contents
11
13
 
12
14
  1. [Getting Started](#1-getting-started)
13
- - [Installation](#11-installation)
14
- - [Running the Development Server](#12-running-the-development-server)
15
- - [Building for Production](#13-building-for-production)
16
- - [Starting the Production Server](#14-starting-the-production-server)
15
+ - [Quickstart](#11-quickstart)
16
+ - [Building for Production](#12-building-for-production)
17
+ - [Starting the Production Server](#13-starting-the-production-server)
17
18
  2. [Project Structure](#2-project-structure)
18
19
  3. [Core Concepts](#3-core-concepts)
19
20
  - [RPC (Remote Procedure Calls)](#31-rpc-remote-procedure-calls)
@@ -31,39 +32,28 @@ HeliumTS is a lightweight, opinionated full-stack React + Vite framework designe
31
32
 
32
33
  ## 1. Getting Started
33
34
 
34
- The current release is **0.10.2**. See the [changelog](./CHANGELOG.md) for fixes and upgrade notes.
35
+ This repository targets **0.11.0**. See the [changelog](https://github.com/heliobentes/heliumts/blob/main/CHANGELOG.md) for fixes and upgrade notes.
35
36
 
36
- ### 1.1. Installation
37
+ ### 1.1. Quickstart
37
38
 
38
39
  Requires Node.js 20.19+ within Node 20, or Node.js 22.12+, and React 18 or 19.
39
40
 
40
- The easiest way to get started with HeliumTS is by using the scaffolding tool:
41
-
42
41
  ```bash
43
42
  npm create heliumts-app@latest my-helium-app
43
+ cd my-helium-app
44
+ npm run dev
44
45
  ```
45
46
 
46
- Or (to create in the current directory):
47
+ The default starter has one page and one typed RPC method. To scaffold the tasks and streaming demo, use `npm create heliumts-app@latest my-helium-app -- --template examples`.
47
48
 
48
- ```
49
- npm create heliumts-app@latest .
50
- ```
49
+ For manual setup, see the [Manual Installation Guide](https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md).
51
50
 
52
- This command will guide you through setting up a new project with everything configured for you.
53
-
54
- If you prefer to set up the project manually, please refer to the [Manual Installation Guide](./docs/manual-installation.md).
55
-
56
- ### 1.2. Running the Development Server
57
-
58
- ```bash
59
- npx helium dev
60
- ```
61
- ### 1.3. Building for Production
51
+ ### 1.2. Building for Production
62
52
 
63
53
  ```bash
64
54
  npx helium build
65
55
  ```
66
- ### 1.4. Starting the Production Server
56
+ ### 1.3. Starting the Production Server
67
57
 
68
58
  ```bash
69
59
  npx helium start
@@ -108,6 +98,10 @@ No more `Axios` or `fetch` calls! Just define your server methods and call them
108
98
 
109
99
  Define server-side functions using `defineMethod` and call them from the client using `useCall` or `useFetch`.
110
100
 
101
+ The examples below use the app-local RPC module from HeliumTS 0.11.0. The dev server and production build generate `src/rpc.generated.ts` from methods in `src/server/`. Run `npx helium typegen` to generate it without starting a server, or `npx helium check` to generate it and check types together. Each export is an opaque method reference that preserves the method's argument and result types.
102
+
103
+ When upgrading from 0.10.2, switch browser RPC imports from `heliumts/server` to your generated module. Delete the old generated `src/types/heliumts-server.d.ts` if it exists, then run `npx helium check`.
104
+
111
105
  **Server (`src/server/tasks.ts`):**
112
106
 
113
107
  ```typescript
@@ -130,7 +124,7 @@ export const createTask = defineMethod(async (args: { name: string }) => {
130
124
 
131
125
  ```tsx
132
126
  import { useFetch, useCall } from "heliumts/client";
133
- import { getTasks, createTask } from "heliumts/server";
127
+ import { getTasks, createTask } from "../rpc.generated";
134
128
 
135
129
  export default function TasksPage() {
136
130
  // Fetch data (auto-runs on mount)
@@ -169,8 +163,9 @@ export const answer = defineMethod(async function* ({ prompt }: { prompt: string
169
163
  ```
170
164
 
171
165
  ```tsx
166
+ // src/pages/answer.tsx
172
167
  import { useStreaming } from "heliumts/client";
173
- import { answer } from "heliumts/server";
168
+ import { answer } from "../rpc.generated";
174
169
 
175
170
  function Answer() {
176
171
  const { text, isStreaming, error, start, cancel } = useStreaming(answer);
@@ -183,7 +178,7 @@ function Answer() {
183
178
  }
184
179
  ```
185
180
 
186
- Pass `ctx.signal` to upstream LLM requests for cooperative cancellation. See [streaming methods](./docs/streaming.md) for typed events, callbacks, errors, limits, and deployment guidance.
181
+ Pass `ctx.signal` to upstream LLM requests for cooperative cancellation. See [streaming methods](./docs/agent/streaming.md) for typed events, callbacks, errors, limits, and deployment guidance.
187
182
 
188
183
  ### 3.2. Routing
189
184
 
@@ -234,7 +229,7 @@ function MyComponent() {
234
229
  }
235
230
  ```
236
231
 
237
- See [Routing Documentation](./docs/routing.md) for detailed information including dynamic routes, layouts, and navigation.
232
+ See [Routing Documentation](./docs/agent/routing.md) for detailed information including dynamic routes, layouts, and navigation.
238
233
 
239
234
  ### 3.3. Custom HTTP Handlers
240
235
 
@@ -294,7 +289,7 @@ When the server starts:
294
289
  Starting worker 'queueConsumer'
295
290
  ```
296
291
 
297
- Workers support auto-restart, configurable restart delays, and max restart attempts. See [Workers Documentation](./docs/workers.md) for queue consumers, scheduled tasks, and more.
292
+ Workers support auto-restart, configurable restart delays, and max restart attempts. See [Workers Documentation](https://github.com/heliobentes/heliumts/blob/main/docs/workers.md) for queue consumers, scheduled tasks, and more.
298
293
 
299
294
  ### 3.5. Middleware
300
295
 
@@ -342,7 +337,7 @@ const config: HeliumConfig = {
342
337
 
343
338
  export default config;
344
339
  ```
345
- See [Configuration Documentation](./docs/helium-config.md) for detailed options.
340
+ See [Configuration Documentation](https://github.com/heliobentes/heliumts/blob/main/docs/helium-config.md) for detailed options.
346
341
 
347
342
  ### 3.7. Static Site Generation (SSG)
348
343
  HeliumTS supports Static Site Generation (SSG) through pre-rendering pages at build time.
@@ -367,7 +362,7 @@ export default function AboutPage() {
367
362
 
368
363
  During build, Helium validates SSG pages and generates optimized static HTML files.
369
364
 
370
- See [SSG Documentation](./docs/ssg.md) for detailed information including limitations, hybrid rendering, and best practices.
365
+ See [SSG Documentation](https://github.com/heliobentes/heliumts/blob/main/docs/ssg.md) for detailed information including limitations, hybrid rendering, and best practices.
371
366
 
372
367
  ### 3.8. Server-Side Rendering (SSR)
373
368
 
@@ -415,7 +410,7 @@ export default function AppLayout({ children }: { children: React.ReactNode }) {
415
410
  }
416
411
  ```
417
412
 
418
- See [SSR Documentation](./docs/ssr.md) for detailed information including sidecar files, layout guards, browser-only dependencies, and how hydration works.
413
+ See [SSR Documentation](https://github.com/heliobentes/heliumts/blob/main/docs/ssr.md) for detailed information including sidecar files, layout guards, browser-only dependencies, and how hydration works.
419
414
 
420
415
  ## 4. CLI Reference
421
416
 
@@ -430,29 +425,33 @@ See [SSR Documentation](./docs/ssr.md) for detailed information including sideca
430
425
  ## 5. More Documentation
431
426
 
432
427
  ### Getting Started
433
- - [Manual Installation](./docs/manual-installation.md) - Step-by-step guide to setting up a HeliumTS project manually
428
+ - [Manual Installation](https://github.com/heliobentes/heliumts/blob/main/docs/manual-installation.md) - Step-by-step guide to setting up a HeliumTS project manually
434
429
 
435
430
  ### Core Features
436
- - [Data Fetching](./docs/data-fetching.md) - useFetch and useCall hooks for data fetching and mutations
437
- - [Routing & useRouter](./docs/routing.md) - File-based routing, dynamic routes, navigation, and the useRouter hook
438
- - [Streaming](./docs/streaming.md) - Typed incremental results and LLM output
439
- - [Configuration](./docs/helium-config.md) - Configure HTTP RPC limits, security, and proxy settings
440
- - [Static Site Generation](./docs/ssg.md) - Pre-render pages at build time for better performance
441
- - [Server-Side Rendering](./docs/ssr.md) - Render pages on the server per-request for SEO and dynamic data
442
- - [Route Groups](./docs/route-groups.md) - Organize routes with shared layouts without affecting URLs
443
- - [Background Workers](./docs/workers.md) - Long-running background processes for queues, scheduled tasks, and more
431
+ - [Data Fetching](./docs/agent/operations.md) - useFetch and useCall hooks for data fetching and mutations
432
+ - [Routing & useRouter](./docs/agent/routing.md) - File-based routing, dynamic routes, navigation, and the useRouter hook
433
+ - [Streaming](./docs/agent/streaming.md) - Typed incremental results and LLM output
434
+ - [Configuration](https://github.com/heliobentes/heliumts/blob/main/docs/helium-config.md) - Configure HTTP RPC limits, security, and proxy settings
435
+ - [Static Site Generation](https://github.com/heliobentes/heliumts/blob/main/docs/ssg.md) - Pre-render pages at build time for better performance
436
+ - [Server-Side Rendering](https://github.com/heliobentes/heliumts/blob/main/docs/ssr.md) - Render pages on the server per-request for SEO and dynamic data
437
+ - [Route Groups](https://github.com/heliobentes/heliumts/blob/main/docs/route-groups.md) - Organize routes with shared layouts without affecting URLs
438
+ - [Background Workers](https://github.com/heliobentes/heliumts/blob/main/docs/workers.md) - Long-running background processes for queues, scheduled tasks, and more
444
439
 
445
440
  ### Deployment & Advanced
446
- - [Context API](./docs/context-api.md) - Access request metadata including client IPs and headers
447
- - [Proxy Configuration](./docs/proxy-configuration.md) - Configure IP detection for rate limiting behind proxies
448
- - [HTTP Handlers & Webhooks](./docs/http-handlers.md) - Create custom HTTP endpoints for webhooks and REST APIs
449
- - [Production Deployment](./docs/production-deployment.md) - Deploy to production platforms and platform compatibility
441
+ - [Context API](./docs/agent/request-context.md) - Access request metadata including client IPs and headers
442
+ - [Proxy Configuration](https://github.com/heliobentes/heliumts/blob/main/docs/proxy-configuration.md) - Configure IP detection for rate limiting behind proxies
443
+ - [HTTP Handlers & Webhooks](./docs/agent/http-handlers.md) - Create custom HTTP endpoints for webhooks and REST APIs
444
+ - [Production Deployment](https://github.com/heliobentes/heliumts/blob/main/docs/production-deployment.md) - Deploy to production platforms and platform compatibility
450
445
 
451
- > **Hosting:** Full Helium functionality runs through its persistent Node.js server. Static-only hosting serves assets and SSG output, but does not execute SSR, RPC, HTTP handlers, or workers. See [Production Deployment](./docs/production-deployment.md).
446
+ > **Hosting:** Full Helium functionality runs through its persistent Node.js server. Static-only hosting serves assets and SSG output, but does not execute SSR, RPC, HTTP handlers, or workers. See [Production Deployment](https://github.com/heliobentes/heliumts/blob/main/docs/production-deployment.md).
452
447
 
453
448
  ## 6. Contributing
454
449
 
455
- Contributions are welcome! Please read the [contributing guide](./CONTRIBUTING.md) for details.
450
+ Contributions are welcome! Please read the [contributing guide](https://github.com/heliobentes/heliumts/blob/main/CONTRIBUTING.md) for details.
456
451
 
457
452
  ## 7. License
458
453
  This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
454
+
455
+ ## Compact reference for agents
456
+
457
+ Read [the one-read startup context](docs/agent-start.md) once for the normal application path. Use [the Markdown task index](docs/agent/index.md) only for a specific gap. The 22 short guides include prerequisite and related-guide links. Use `npx helium api useCall --json` (or `--from server` for server symbols) to read one installed public declaration and its related type references. See [the compact application reference](docs/agent-guide.md) for import boundaries, a validated RPC example and the generate/check/inspect workflow. Use matching 0.11.0 framework/scaffolder versions. Keep RPC references generated and validation/authorization on the server; `useCall.submit()` handles form pending/errors while explicit invalidation names the reads to refresh. Examples are checked with `npm run test:docs` after `npm run build`; `npm run test:api` verifies declaration lookup in a packed package.
@@ -1,16 +1,12 @@
1
1
  #!/usr/bin/env node
2
2
  import { cac } from "cac";
3
3
  import { spawn } from "child_process";
4
- import { build as esbuild } from "esbuild";
5
4
  import fs from "fs";
6
5
  import path from "path";
7
6
  import { fileURLToPath } from "url";
8
- import { build as viteBuild } from "vite";
9
7
  import { replaceHtmlRootContents } from "../utils/html.js";
10
8
  import { log } from "../utils/logger.js";
11
- import { scanAppShell, scanPageRoutePatterns, scanServerExports, scanSSRPages } from "../vite/scanner.js";
12
- import { generateStaticPages } from "../vite/ssg.js";
13
- import { generateClientModule, generateServerManifest, generateTypeDefinitions } from "../vite/virtualServerModule.js";
9
+ import { generateServerClientModule, generateServerPrefetchModule, generateServerTransitionsModule } from "../vite/serverClientAdapter.js";
14
10
  const cli = cac("helium");
15
11
  const root = process.cwd();
16
12
  function monitorChild(child) {
@@ -28,23 +24,119 @@ function monitorChild(child) {
28
24
  process.exit(code ?? (signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 1));
29
25
  });
30
26
  }
27
+ cli.command("typegen", "Generate RPC imports and validate the application manifest").action(async () => {
28
+ try {
29
+ const { typegenProject } = await import("./projectCommands.js");
30
+ log("info", `Generated imports for ${typegenProject(root)} RPC method(s).`);
31
+ }
32
+ catch (error) {
33
+ log("error", String(error));
34
+ process.exitCode = 1;
35
+ }
36
+ });
37
+ cli.command("check", "Generate RPC references, validate the manifest, and check TypeScript").action(async () => {
38
+ try {
39
+ const { checkProject } = await import("./projectCommands.js");
40
+ checkProject(root);
41
+ log("info", "Manifest and TypeScript checks passed.");
42
+ }
43
+ catch (error) {
44
+ log("error", String(error));
45
+ process.exitCode = 1;
46
+ }
47
+ });
48
+ cli.command("api [symbol]", "Read or discover installed public API declarations without loading application modules")
49
+ .option("--from <entry>", "Public entrypoint, such as client (default) or server")
50
+ .option("--list", "List public symbol names instead of reading a declaration")
51
+ .option("--match <fragment>", "Filter --list by a case-insensitive literal name fragment")
52
+ .option("--json", "Pretty-print the declaration record")
53
+ .action(async (symbol, options) => {
54
+ try {
55
+ if (options.list !== undefined && options.list !== true) {
56
+ throw new Error("Specify --list only once, without a value.");
57
+ }
58
+ if (options.list && cli.args.length) {
59
+ throw new Error("Choose either a symbol lookup or --list, not both.");
60
+ }
61
+ if (!options.list && options.match !== undefined) {
62
+ throw new Error("--match requires --list.");
63
+ }
64
+ if (!options.list && cli.args.length !== 1) {
65
+ throw new Error("api accepts exactly one public symbol name.");
66
+ }
67
+ const { inspectPublicApi, listPublicApi } = await import("./publicApi.js");
68
+ const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
69
+ const result = options.list ? listPublicApi(packageRoot, options.from, options.match) : inspectPublicApi(packageRoot, symbol, options.from);
70
+ console.log(JSON.stringify(result, null, options.json ? 2 : 0));
71
+ }
72
+ catch (error) {
73
+ log("error", String(error));
74
+ process.exitCode = 1;
75
+ }
76
+ });
77
+ cli.command("inspect", "Inspect routes, rendering, RPC, and middleware without executing modules")
78
+ .option("--json", "Print the machine-readable application manifest")
79
+ .option("--route <pattern>", "Look up an exact route pattern")
80
+ .option("--rpc <name>", "Look up an exact RPC method name")
81
+ .action(async (options) => {
82
+ try {
83
+ const { inspectEntry, inspectProject, inspectSelection } = await import("./projectCommands.js");
84
+ const selection = inspectSelection(options);
85
+ if (selection) {
86
+ const entry = inspectEntry(root, selection.kind, selection.name);
87
+ console.log(JSON.stringify(entry, null, options.json ? 2 : 0));
88
+ return;
89
+ }
90
+ const manifest = inspectProject(root);
91
+ if (options.json) {
92
+ console.log(JSON.stringify(manifest, null, 2));
93
+ }
94
+ else {
95
+ for (const route of manifest.routes) {
96
+ console.log(`${route.render.toUpperCase()} ${route.pattern} (${route.file})`);
97
+ }
98
+ for (const method of manifest.rpc) {
99
+ console.log(`RPC ${method.name} (${method.file})`);
100
+ }
101
+ console.log(`Middleware: ${manifest.middleware?.file ?? "none"}`);
102
+ for (const collision of manifest.collisions) {
103
+ console.log(`Collision: ${collision.pattern}: ${collision.files.join(", ")}`);
104
+ }
105
+ }
106
+ if (manifest.collisions.length) {
107
+ process.exitCode = 1;
108
+ }
109
+ }
110
+ catch (error) {
111
+ log("error", String(error));
112
+ process.exitCode = 1;
113
+ }
114
+ });
31
115
  cli.command("dev", "Start development server").action(async () => {
32
116
  const vitePackage = fileURLToPath(import.meta.resolve("vite/package.json"));
33
117
  monitorChild(spawn(process.execPath, [path.join(path.dirname(vitePackage), "bin", "vite.js")], { stdio: "inherit" }));
34
118
  });
35
119
  cli.command("build", "Build for production").action(async () => {
36
- // Generate type definitions before building so TypeScript can resolve
37
- // server method types even if the dev server was never started.
120
+ // Production start and CLI help do not need the compiler/build toolchain.
121
+ const [vite, bundler, scanner, ssg, virtualModules, rpcModule] = await Promise.all([
122
+ import("vite"),
123
+ import("esbuild"),
124
+ import("../vite/scanner.js"),
125
+ import("../vite/ssg.js"),
126
+ import("../vite/virtualServerModule.js"),
127
+ import("../vite/rpcModule.js"),
128
+ ]);
129
+ const { build: viteBuild } = vite;
130
+ const { build: esbuild } = bundler;
131
+ const { scanAppShell, scanPageManifest, scanPageRoutePatterns, scanServerExports, scanSSRPages } = scanner;
132
+ const { generateStaticPages } = ssg;
133
+ const { generateServerManifest } = virtualModules;
134
+ const { writeRpcModule } = rpcModule;
135
+ const pages = scanPageManifest(root);
136
+ // Generate RPC references before Vite reads application modules.
38
137
  const { methods } = scanServerExports(root);
39
- const dts = generateTypeDefinitions(methods, root);
40
- const typesDir = path.join(root, "src", "types");
41
- const dtsPath = path.join(typesDir, "heliumts-server.d.ts");
42
- if (!fs.existsSync(typesDir)) {
43
- fs.mkdirSync(typesDir, { recursive: true });
44
- }
45
- if (!fs.existsSync(dtsPath) || fs.readFileSync(dtsPath, "utf-8") !== dts) {
46
- fs.writeFileSync(dtsPath, dts);
47
- log("info", `Generated type definitions for ${methods.length} method(s)`);
138
+ if (writeRpcModule(root, methods)) {
139
+ log("info", `Generated imports for ${methods.length} RPC method(s)`);
48
140
  }
49
141
  log("info", "--------------------------------");
50
142
  log("info", "Building client...");
@@ -87,7 +179,7 @@ cli.command("build", "Build for production").action(async () => {
87
179
  htmlTemplate = htmlTemplate.replace(/<script>window\.HELIUM_CONNECTION_TOKEN = "build-time-placeholder";<\/script>/g, "");
88
180
  // 2. Clear any existing content in root div from SPA build
89
181
  htmlTemplate = replaceHtmlRootContents(htmlTemplate, "", { "data-ssg-page": null, "data-ssg-failed": null });
90
- await generateStaticPages(null, root, htmlTemplate, distDir);
182
+ await generateStaticPages(null, root, htmlTemplate, distDir, pages);
91
183
  }
92
184
  else {
93
185
  log("warn", "index.html not found in dist, skipping SSG");
@@ -106,10 +198,10 @@ cli.command("build", "Build for production").action(async () => {
106
198
  log("info", "Building server...");
107
199
  // Generate server entry
108
200
  const serverExports = scanServerExports(root);
109
- const pageRoutePatterns = scanPageRoutePatterns(root);
110
- const ssrPages = scanSSRPages(root);
201
+ const pageRoutePatterns = scanPageRoutePatterns(root, pages);
202
+ const ssrPages = scanSSRPages(root, pages);
111
203
  const appShell = scanAppShell(root);
112
- const manifestCode = generateServerManifest(serverExports.methods, serverExports.httpHandlers, serverExports.seoMetadata, pageRoutePatterns, ssrPages, appShell, serverExports.middleware, serverExports.workers);
204
+ const manifestCode = generateServerManifest(serverExports.methods, serverExports.httpHandlers, serverExports.seoMetadata, pageRoutePatterns, ssrPages, appShell, serverExports.middleware, serverExports.workers, pages);
113
205
  // Create the main server module that will be imported after env is loaded
114
206
  const serverModuleCode = `
115
207
  import { startProdServer, loadConfig } from 'heliumts/server';
@@ -130,6 +222,7 @@ export async function start() {
130
222
  httpRouter.setMiddleware(middlewareHandler);
131
223
  }
132
224
  },
225
+ pageRoutes,
133
226
  ssrPages,
134
227
  appShell,
135
228
  workers
@@ -145,7 +238,7 @@ const { start } = await import('./server-module.js');
145
238
  await start();
146
239
  `;
147
240
  const envLoaderCode = `
148
- import { loadEnvFiles, injectEnvToProcess, log } from 'heliumts/server';
241
+ import { loadEnvFiles, injectEnvToProcess, log } from 'heliumts/internal';
149
242
  import { fileURLToPath } from 'node:url';
150
243
  process.env.HELIUM_CONFIG_DIR ??= fileURLToPath(new URL('.', import.meta.url));
151
244
  process.env.NODE_ENV ??= 'production';
@@ -169,147 +262,12 @@ if (Object.keys(envVars).length > 0) {
169
262
  const ssrClientStubPath = path.join(heliumDir, "ssr-client-stub.ts");
170
263
  const ssrTransitionsStubPath = path.join(heliumDir, "ssr-transitions-stub.ts");
171
264
  const ssrPrefetchStubPath = path.join(heliumDir, "ssr-prefetch-stub.ts");
172
- const ssrClientStubCode = `
173
- import React from 'react';
174
-
175
- export const RouterContext = React.createContext(null);
176
-
177
- function getSSRRouterSnapshot() {
178
- const snapshot = globalThis.__HELIUM_SSR_ROUTER__ as
179
- | { path?: string; params?: Record<string, string | string[]>; search?: string }
180
- | undefined;
181
-
182
- if (!snapshot || typeof snapshot !== 'object') {
183
- return {
184
- path: '/',
185
- params: {},
186
- search: '',
187
- };
188
- }
189
-
190
- return {
191
- path: typeof snapshot.path === 'string' ? snapshot.path : '/',
192
- params: snapshot.params && typeof snapshot.params === 'object' ? snapshot.params : {},
193
- search: typeof snapshot.search === 'string' ? snapshot.search : '',
194
- };
195
- }
196
-
197
- export function useRouter() {
198
- const snapshot = getSSRRouterSnapshot();
199
- return {
200
- path: snapshot.path,
201
- params: snapshot.params,
202
- searchParams: new URLSearchParams(snapshot.search),
203
- push: () => {},
204
- replace: () => {},
205
- on: () => () => {},
206
- status: 200,
207
- isNavigating: false,
208
- isPending: false,
209
- };
210
- }
211
-
212
- export function Link(props: { href?: string; children?: React.ReactNode } & Record<string, unknown>) {
213
- const { href = '#', children, prefetch: _prefetch, ...rest } = props || {};
214
- return React.createElement('a', { href, ...rest }, children);
215
- }
216
-
217
- export function Redirect() {
218
- return null;
219
- }
220
-
221
- export function AppRouter() {
222
- return null;
223
- }
224
-
225
- export async function callMethod() {
226
- throw new Error('callMethod is only available in the browser. Load server data with getServerSideProps instead.');
227
- }
228
-
229
- export function useStreaming() {
230
- return {
231
- chunks: [],
232
- text: '',
233
- isStreaming: false,
234
- error: null,
235
- stats: null,
236
- start: async () => {
237
- throw new Error('useStreaming.start is only available in the browser. Load server data with getServerSideProps instead.');
238
- },
239
- cancel: () => {},
240
- reset: () => {},
241
- };
242
- }
243
-
244
- export function useCall() {
245
- return {
246
- call: async () => null,
247
- isCalling: false,
248
- error: null,
249
- };
250
- }
251
-
252
- export function useFetch() {
253
- return {
254
- data: null,
255
- isLoading: false,
256
- error: null,
257
- refetch: async () => undefined,
258
- };
259
- }
260
-
261
- export class RpcError extends Error {}
262
-
263
- export function getPublicEnv() {
264
- return Object.fromEntries(Object.entries(process.env).filter(([key, value]) => key.startsWith('HELIUM_PUBLIC_') && value !== undefined));
265
- }
266
-
267
- export function getPublicEnvValue(key: string) {
268
- return getPublicEnv()[key];
269
- }
270
-
271
- export function isDevEnvironment() {
272
- return false;
273
- }
274
-
275
- export function isSSR() {
276
- return true;
277
- }
278
- `;
279
- const ssrTransitionsStubCode = `
280
- import React from 'react';
281
- import { useRouter } from 'heliumts/client';
282
-
283
- export function useDeferredNavigation() {
284
- const { path } = useRouter();
285
- return {
286
- path,
287
- deferredPath: path,
288
- isStale: false,
289
- isPending: false,
290
- isTransitioning: false,
291
- };
292
- }
293
-
294
- export function PageTransition({ children, fallback = null }: { children?: React.ReactNode; fallback?: React.ReactNode }) {
295
- return React.createElement('div', { style: { opacity: 1, transition: 'opacity 150ms ease' } },
296
- React.createElement(React.Suspense, { fallback }, children));
297
- }
298
- `;
299
- const ssrPrefetchStubCode = `
300
- export function prefetchRoute() {}
301
- export function clearPrefetchCache() {}
302
- `;
265
+ const ssrClientStubCode = generateServerClientModule("ssr");
266
+ const ssrTransitionsStubCode = generateServerTransitionsModule("ssr");
267
+ const ssrPrefetchStubCode = generateServerPrefetchModule();
303
268
  fs.writeFileSync(entryPath, entryCode);
304
269
  fs.writeFileSync(envLoaderPath, envLoaderCode);
305
270
  fs.writeFileSync(serverModuleSrcPath, serverModuleCode);
306
- // Generate a client-side stub for heliumts/server that provides method stubs
307
- // (e.g. { __id: 'subscribeWaitlist' }) so client components that import
308
- // user-defined methods from 'heliumts/server' resolve correctly during
309
- // the esbuild server bundle (mirroring the Vite plugin's virtual module).
310
- const rpcClientStubPath = path.join(heliumDir, "rpc-client-stub.ts");
311
- const rpcClientStubCode = `export * from 'heliumts/server';\n${generateClientModule(serverExports.methods)}`;
312
- fs.writeFileSync(rpcClientStubPath, rpcClientStubCode);
313
271
  fs.writeFileSync(ssrClientStubPath, ssrClientStubCode);
314
272
  fs.writeFileSync(ssrTransitionsStubPath, ssrTransitionsStubCode);
315
273
  fs.writeFileSync(ssrPrefetchStubPath, ssrPrefetchStubCode);
@@ -330,19 +288,6 @@ export function clearPrefetchCache() {}
330
288
  build.onResolve({ filter: /^heliumts\/client$/ }, () => ({ path: ssrClientStubPath }));
331
289
  build.onResolve({ filter: /^heliumts\/client\/transitions$/ }, () => ({ path: ssrTransitionsStubPath }));
332
290
  build.onResolve({ filter: /^heliumts\/client\/prefetch$/ }, () => ({ path: ssrPrefetchStubPath }));
333
- // Intercept heliumts/server imports from client code
334
- // and redirect to the RPC stub module (method stubs).
335
- // Server-side files and generated server-module resolve normally.
336
- const serverDirAbs = path.join(root, "src", "server");
337
- build.onResolve({ filter: /^heliumts\/server$/ }, (args) => {
338
- const importer = args.importer;
339
- // Allow the generated server-module and env-loader to
340
- // import the real heliumts/server framework exports.
341
- if (importer.startsWith(heliumDir) || importer.startsWith(serverDirAbs)) {
342
- return undefined; // let esbuild resolve normally
343
- }
344
- return { path: rpcClientStubPath };
345
- });
346
291
  },
347
292
  },
348
293
  ],