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.
- package/README.md +45 -46
- package/dist/bin/helium.js +117 -172
- package/dist/bin/helium.js.map +1 -1
- package/dist/bin/projectCommands.d.ts +59 -0
- package/dist/bin/projectCommands.d.ts.map +1 -0
- package/dist/bin/projectCommands.js +103 -0
- package/dist/bin/projectCommands.js.map +1 -0
- package/dist/bin/publicApi.d.ts +30 -0
- package/dist/bin/publicApi.d.ts.map +1 -0
- package/dist/bin/publicApi.js +155 -0
- package/dist/bin/publicApi.js.map +1 -0
- package/dist/client/Router.d.ts.map +1 -1
- package/dist/client/Router.js +5 -1
- package/dist/client/Router.js.map +1 -1
- package/dist/client/callMethod.d.ts +2 -2
- package/dist/client/callMethod.d.ts.map +1 -1
- package/dist/client/callMethod.js +3 -2
- package/dist/client/callMethod.js.map +1 -1
- package/dist/client/index.d.ts +3 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -2
- package/dist/client/index.js.map +1 -1
- package/dist/client/pageModules.d.ts +18 -0
- package/dist/client/pageModules.d.ts.map +1 -0
- package/dist/client/pageModules.js +3 -0
- package/dist/client/pageModules.js.map +1 -0
- package/dist/client/routerManifest.d.ts +2 -11
- package/dist/client/routerManifest.d.ts.map +1 -1
- package/dist/client/routerManifest.js +15 -187
- package/dist/client/routerManifest.js.map +1 -1
- package/dist/client/types.d.ts +12 -12
- package/dist/client/types.d.ts.map +1 -1
- package/dist/client/types.js +8 -1
- package/dist/client/types.js.map +1 -1
- package/dist/client/useCall.d.ts +20 -9
- package/dist/client/useCall.d.ts.map +1 -1
- package/dist/client/useCall.js +21 -6
- package/dist/client/useCall.js.map +1 -1
- package/dist/client/useFetch.d.ts +3 -3
- package/dist/client/useFetch.d.ts.map +1 -1
- package/dist/client/useFetch.js +8 -5
- package/dist/client/useFetch.js.map +1 -1
- package/dist/client/useStreaming.d.ts +3 -3
- package/dist/client/useStreaming.d.ts.map +1 -1
- package/dist/client/useStreaming.js +9 -7
- package/dist/client/useStreaming.js.map +1 -1
- package/dist/internal/index.d.ts +4 -0
- package/dist/internal/index.d.ts.map +1 -0
- package/dist/internal/index.js +4 -0
- package/dist/internal/index.js.map +1 -0
- package/dist/runtime/pageRoutes.d.ts +11 -0
- package/dist/runtime/pageRoutes.d.ts.map +1 -0
- package/dist/runtime/pageRoutes.js +50 -0
- package/dist/runtime/pageRoutes.js.map +1 -0
- package/dist/server/defineMethod.d.ts +16 -2
- package/dist/server/defineMethod.d.ts.map +1 -1
- package/dist/server/defineMethod.js +27 -3
- package/dist/server/defineMethod.js.map +1 -1
- package/dist/server/defineWorker.d.ts.map +1 -1
- package/dist/server/defineWorker.js +4 -6
- package/dist/server/defineWorker.js.map +1 -1
- package/dist/server/devServer.d.ts +2 -1
- package/dist/server/devServer.d.ts.map +1 -1
- package/dist/server/devServer.js +6 -9
- package/dist/server/devServer.js.map +1 -1
- package/dist/server/index.d.ts +16 -9
- package/dist/server/index.d.ts.map +1 -1
- package/dist/server/index.js +9 -12
- package/dist/server/index.js.map +1 -1
- package/dist/server/prodServer.d.ts +2 -0
- package/dist/server/prodServer.d.ts.map +1 -1
- package/dist/server/prodServer.js +7 -5
- package/dist/server/prodServer.js.map +1 -1
- package/dist/server/ssr.d.ts +4 -1
- package/dist/server/ssr.d.ts.map +1 -1
- package/dist/server/ssr.js +27 -61
- package/dist/server/ssr.js.map +1 -1
- package/dist/vite/heliumPlugin.d.ts +0 -14
- package/dist/vite/heliumPlugin.d.ts.map +1 -1
- package/dist/vite/heliumPlugin.js +68 -294
- package/dist/vite/heliumPlugin.js.map +1 -1
- package/dist/vite/paths.d.ts +0 -2
- package/dist/vite/paths.d.ts.map +1 -1
- package/dist/vite/paths.js +0 -2
- package/dist/vite/paths.js.map +1 -1
- package/dist/vite/rpcDiscovery.d.ts +10 -0
- package/dist/vite/rpcDiscovery.d.ts.map +1 -0
- package/dist/vite/rpcDiscovery.js +237 -0
- package/dist/vite/rpcDiscovery.js.map +1 -0
- package/dist/vite/rpcModule.d.ts +4 -0
- package/dist/vite/rpcModule.d.ts.map +1 -0
- package/dist/vite/rpcModule.js +64 -0
- package/dist/vite/rpcModule.js.map +1 -0
- package/dist/vite/scanner.d.ts +14 -4
- package/dist/vite/scanner.d.ts.map +1 -1
- package/dist/vite/scanner.js +130 -236
- package/dist/vite/scanner.js.map +1 -1
- package/dist/vite/serverClientAdapter.d.ts +103 -0
- package/dist/vite/serverClientAdapter.d.ts.map +1 -0
- package/dist/vite/serverClientAdapter.js +139 -0
- package/dist/vite/serverClientAdapter.js.map +1 -0
- package/dist/vite/ssg.d.ts +5 -8
- package/dist/vite/ssg.d.ts.map +1 -1
- package/dist/vite/ssg.js +32 -263
- package/dist/vite/ssg.js.map +1 -1
- package/dist/vite/virtualServerModule.d.ts +4 -4
- package/dist/vite/virtualServerModule.d.ts.map +1 -1
- package/dist/vite/virtualServerModule.js +18 -62
- package/dist/vite/virtualServerModule.js.map +1 -1
- package/docs/agent/api-reference.md +45 -0
- package/docs/agent/editable-forms.md +37 -0
- package/docs/agent/guide-get.md +13 -0
- package/docs/agent/guide-index.md +15 -0
- package/docs/agent/http-handlers.md +9 -0
- package/docs/agent/imports.md +16 -0
- package/docs/agent/index.md +48 -0
- package/docs/agent/input-validation.md +9 -0
- package/docs/agent/measuring.md +7 -0
- package/docs/agent/mutations.md +11 -0
- package/docs/agent/operations.md +9 -0
- package/docs/agent/query-params.md +28 -0
- package/docs/agent/rendering.md +9 -0
- package/docs/agent/request-context.md +13 -0
- package/docs/agent/routing.md +11 -0
- package/docs/agent/scaffold.md +15 -0
- package/docs/agent/security.md +9 -0
- package/docs/agent/server-files.md +9 -0
- package/docs/agent/streaming.md +9 -0
- package/docs/agent/validation-page.md +21 -0
- package/docs/agent/validation.md +33 -0
- package/docs/agent/verify.md +19 -0
- package/docs/agent/workflow.md +11 -0
- package/docs/agent-guide.md +266 -0
- package/docs/agent-start.md +87 -0
- package/docs/migration-0.11.md +15 -0
- package/package.json +20 -5
- package/dist/server/handlerLoader.d.ts +0 -1
- package/dist/server/handlerLoader.d.ts.map +0 -1
- package/dist/server/handlerLoader.js +0 -2
- package/dist/server/handlerLoader.js.map +0 -1
- package/dist/server/ipExtractor.d.ts +0 -48
- package/dist/server/ipExtractor.d.ts.map +0 -1
- package/dist/server/ipExtractor.js +0 -96
- package/dist/server/ipExtractor.js.map +0 -1
- package/dist/server/requestRouting.d.ts +0 -4
- package/dist/server/requestRouting.d.ts.map +0 -1
- package/dist/server/requestRouting.js +0 -67
- package/dist/server/requestRouting.js.map +0 -1
- package/dist/utils/deepEqual.d.ts +0 -1
- package/dist/utils/deepEqual.d.ts.map +0 -1
- package/dist/utils/deepEqual.js +0 -2
- package/dist/utils/deepEqual.js.map +0 -1
- package/dist/utils/formatError.d.ts +0 -2
- package/dist/utils/formatError.d.ts.map +0 -1
- package/dist/utils/formatError.js +0 -18
- 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
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
- [
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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 "
|
|
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 "
|
|
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](
|
|
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](
|
|
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](
|
|
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](
|
|
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](
|
|
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/
|
|
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](
|
|
440
|
-
- [Static Site Generation](
|
|
441
|
-
- [Server-Side Rendering](
|
|
442
|
-
- [Route Groups](
|
|
443
|
-
- [Background Workers](
|
|
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
|
|
447
|
-
- [Proxy Configuration](
|
|
448
|
-
- [HTTP Handlers & Webhooks](./docs/http-handlers.md) - Create custom HTTP endpoints for webhooks and REST APIs
|
|
449
|
-
- [Production Deployment](
|
|
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](
|
|
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](
|
|
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.
|
package/dist/bin/helium.js
CHANGED
|
@@ -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 {
|
|
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
|
-
//
|
|
37
|
-
|
|
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
|
-
|
|
40
|
-
|
|
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/
|
|
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
|
-
|
|
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
|
],
|