@runic-artifex/vite-plugin-runic 0.9.1 → 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 +41 -3
- package/dist/client.js +7 -1
- package/dist/dev-session.d.ts +17 -0
- package/dist/dev-session.js +53 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +5 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -19,13 +19,14 @@ omit the plugin entirely. A Runic Views frontend needs neither: its page loads
|
|
|
19
19
|
passes the host it builds for as `RUNIC_APPLICATION_HOST` for a configuration
|
|
20
20
|
that still differs per host. The optional
|
|
21
21
|
`@vitejs/devtools` peer enables the Runic dock; register `DevTools()` in your
|
|
22
|
-
Vite configuration when selecting `devtools: true`.
|
|
22
|
+
Vite configuration when selecting `devtools: true`. The plugin runs on Node 24.18
|
|
23
|
+
or later 24.x, or Node 26.
|
|
23
24
|
|
|
24
25
|
`devtools` takes `true`, `false` or `"auto"`. `"auto"` is the default and the
|
|
25
26
|
same as omitting the option: the development client is injected while serving,
|
|
26
27
|
and the Runic dock appears when `DevTools()` is registered. `true` also requires
|
|
27
28
|
`DevTools()`: serving without it fails with
|
|
28
|
-
[`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.
|
|
29
|
+
[`RUNICP007`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.11.0/docs/diagnostics.md#runicp007).
|
|
29
30
|
`false` turns off both the dock and the development client.
|
|
30
31
|
`maxTimelineEntries` sets how many timeline entries the dock keeps: 200 by
|
|
31
32
|
default, rounded down and limited to 1 to 500.
|
|
@@ -34,7 +35,9 @@ While serving, the plugin adds `virtual:runic/client`, which loads the
|
|
|
34
35
|
development client (`@runic-artifex/vite-plugin-runic/client`), to `index.html`.
|
|
35
36
|
The client has no exports. It shows the page's connection to its .NET host, as
|
|
36
37
|
`@runic-artifex/views` reports it (`connecting`, `connected`, `reconnecting`,
|
|
37
|
-
`lost`), on the dock's **Connection** card
|
|
38
|
+
`lost`), on the dock's **Connection** card from page load, before a View
|
|
39
|
+
connects (with `@runic-artifex/views` 0.11 or later; earlier releases start it
|
|
40
|
+
when the first View connects), and forwards
|
|
38
41
|
`@runic-artifex/views` failures to the timeline: the failed route, the
|
|
39
42
|
error kind and, for errors, a failure with the exception type, message and
|
|
40
43
|
stack. .NET includes that detail only in development (see the
|
|
@@ -49,6 +52,41 @@ The plugin adds `@runic-artifex/vite-plugin-runic/client` to
|
|
|
49
52
|
client: with a cold `node_modules/.vite` cache, the first page would otherwise
|
|
50
53
|
discover it, and Vite would reload the page and close the host's connection.
|
|
51
54
|
|
|
55
|
+
Under `dotnet runic dev`, the Vite process gets a random value for the session
|
|
56
|
+
in `RUNIC_APPLICATION_DEV_SESSION`, and `/__runic/state` answers with it in the
|
|
57
|
+
`X-Runic-Dev-Session` header. Since 0.11, `dev` treats the server as ready
|
|
58
|
+
only when that answer matches. Another process that takes the port before Vite
|
|
59
|
+
binds it cannot answer, so `dev` never loads its pages into the application.
|
|
60
|
+
Pages and other responses do not carry the header. Use the plugin from the same
|
|
61
|
+
release as `dotnet-runic`, because an older plugin does not answer and `dev`
|
|
62
|
+
times out with `RAPPDEV1007`.
|
|
63
|
+
|
|
64
|
+
Two exports answer only the session, for development servers that cannot use
|
|
65
|
+
`runic()`. Without `dotnet runic dev` neither changes anything.
|
|
66
|
+
|
|
67
|
+
- `runicDevSession()` is a Vite plugin without `runic()`'s HTML hooks, for
|
|
68
|
+
SvelteKit, which warns about plugins with a `transformIndexHtml` hook:
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
plugins: [sveltekit({ adapter: runicAdapter() }), runicDevSession()],
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- `runicDevSessionProxy()` returns Vite proxy entries, for the Angular CLI,
|
|
75
|
+
which takes a proxy configuration but no Vite plugins. Spread it into the
|
|
76
|
+
file that the serve target's `proxyConfig` in `angular.json` names:
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
// proxy.conf.mjs
|
|
80
|
+
import { runicDevSessionProxy } from "@runic-artifex/vite-plugin-runic";
|
|
81
|
+
|
|
82
|
+
export default { ...runicDevSessionProxy() };
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`dotnet runic dev` expects the answer from an Angular frontend whose
|
|
86
|
+
`package.json` declares this package.
|
|
87
|
+
|
|
88
|
+
The `runic-app` template's SvelteKit and Angular frontends are set up this way.
|
|
89
|
+
|
|
52
90
|
The native host serves `webui.js` and its client script (`runic-desktop.js`,
|
|
53
91
|
`runic-views.js`, `runic-cswebui.js` or `runic-desktop-views.js`) from the root
|
|
54
92
|
of the web content, outside the Vite build. The plugin leaves those classic script tags
|
package/dist/client.js
CHANGED
|
@@ -57,7 +57,8 @@ function connectViewsDiagnostics() {
|
|
|
57
57
|
hot.data[viewsListenerKey] = reportViewsDiagnostic;
|
|
58
58
|
}
|
|
59
59
|
// @runic-artifex/views publishes the page's connection state on this channel once a View
|
|
60
|
-
// connects
|
|
60
|
+
// connects, or from page load when this client asks for it with `requested` and `start`
|
|
61
|
+
// (specs/application, "Shared globals").
|
|
61
62
|
const viewsConnectionKey = Symbol.for("runic.views.connection");
|
|
62
63
|
const connectionListenerKey = "runic:connection-listener";
|
|
63
64
|
function reportConnection(state) {
|
|
@@ -75,6 +76,11 @@ function connectViewsConnection() {
|
|
|
75
76
|
hot.data[connectionListenerKey] = reportConnection;
|
|
76
77
|
if (typeof channel.state === "string")
|
|
77
78
|
reportConnection(channel.state);
|
|
79
|
+
// Observe from page load, not only once a View connects: a copy of @runic-artifex/views that
|
|
80
|
+
// loads later sees `requested`, and one that already loaded has set `start`.
|
|
81
|
+
channel.requested = true;
|
|
82
|
+
if (typeof channel.start === "function")
|
|
83
|
+
channel.start();
|
|
78
84
|
}
|
|
79
85
|
connectViewsDiagnostics();
|
|
80
86
|
connectViewsConnection();
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Plugin, ProxyOptions } from "vite";
|
|
2
|
+
export declare const devSessionVariable = "RUNIC_APPLICATION_DEV_SESSION";
|
|
3
|
+
export declare const devSessionHeader = "X-Runic-Dev-Session";
|
|
4
|
+
/** The session value `dotnet runic dev` set, when it has the shape the tool writes: 32 to 128 hex digits. */
|
|
5
|
+
export declare function devSessionValue(value: string | undefined): string | undefined;
|
|
6
|
+
/**
|
|
7
|
+
* A Vite plugin that only answers `/__runic/state` with the `dotnet runic dev` session, for a configuration that
|
|
8
|
+
* cannot use `runic()`: SvelteKit, which warns about `runic()`'s `transformIndexHtml` hook. `runic()` already
|
|
9
|
+
* answers it. Without `dotnet runic dev` the plugin does nothing.
|
|
10
|
+
*/
|
|
11
|
+
export declare function runicDevSession(): Plugin;
|
|
12
|
+
/**
|
|
13
|
+
* Vite proxy entries that answer `/__runic/state` with the `dotnet runic dev` session, for a development server
|
|
14
|
+
* that takes a Vite proxy configuration but no Vite plugins: the Angular CLI's `proxyConfig`. Spread the result
|
|
15
|
+
* into the proxy configuration. Without `dotnet runic dev` it is empty and changes nothing.
|
|
16
|
+
*/
|
|
17
|
+
export declare function runicDevSessionProxy(): Record<string, ProxyOptions>;
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
// `dotnet runic dev` gives the development server process a random session value and accepts the server as ready
|
|
2
|
+
// only when /__runic/state answers with it, so another process that takes the port first is not mistaken for this
|
|
3
|
+
// server.
|
|
4
|
+
export const devSessionVariable = "RUNIC_APPLICATION_DEV_SESSION";
|
|
5
|
+
export const devSessionHeader = "X-Runic-Dev-Session";
|
|
6
|
+
const statePath = "/__runic/state";
|
|
7
|
+
/** The session value `dotnet runic dev` set, when it has the shape the tool writes: 32 to 128 hex digits. */
|
|
8
|
+
export function devSessionValue(value) {
|
|
9
|
+
return value !== undefined && /^[0-9a-f]{32,128}$/.test(value) ? value : undefined;
|
|
10
|
+
}
|
|
11
|
+
function answerSession(response, session) {
|
|
12
|
+
response.statusCode = 204;
|
|
13
|
+
response.setHeader("Cache-Control", "no-store");
|
|
14
|
+
response.setHeader(devSessionHeader, session);
|
|
15
|
+
response.end();
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* A Vite plugin that only answers `/__runic/state` with the `dotnet runic dev` session, for a configuration that
|
|
19
|
+
* cannot use `runic()`: SvelteKit, which warns about `runic()`'s `transformIndexHtml` hook. `runic()` already
|
|
20
|
+
* answers it. Without `dotnet runic dev` the plugin does nothing.
|
|
21
|
+
*/
|
|
22
|
+
export function runicDevSession() {
|
|
23
|
+
return {
|
|
24
|
+
name: "runic:dev-session",
|
|
25
|
+
configureServer(server) {
|
|
26
|
+
const session = devSessionValue(process.env[devSessionVariable]);
|
|
27
|
+
if (session === undefined)
|
|
28
|
+
return;
|
|
29
|
+
server.middlewares.use(statePath, (_request, response) => answerSession(response, session));
|
|
30
|
+
},
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Vite proxy entries that answer `/__runic/state` with the `dotnet runic dev` session, for a development server
|
|
35
|
+
* that takes a Vite proxy configuration but no Vite plugins: the Angular CLI's `proxyConfig`. Spread the result
|
|
36
|
+
* into the proxy configuration. Without `dotnet runic dev` it is empty and changes nothing.
|
|
37
|
+
*/
|
|
38
|
+
export function runicDevSessionProxy() {
|
|
39
|
+
const session = devSessionValue(process.env[devSessionVariable]);
|
|
40
|
+
if (session === undefined)
|
|
41
|
+
return {};
|
|
42
|
+
return {
|
|
43
|
+
"^/__runic/state(?:[/?#]|$)": {
|
|
44
|
+
// The entry never proxies: it answers in bypass, and Vite then ends the request.
|
|
45
|
+
bypass(request, response) {
|
|
46
|
+
if (response === undefined)
|
|
47
|
+
return false;
|
|
48
|
+
answerSession(response, session);
|
|
49
|
+
return request.url ?? statePath;
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
};
|
|
53
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Plugin } from "vite";
|
|
2
2
|
import type { RunicDiagnosticEntry, RunicDiagnosticDetail, RunicDiagnosticFailure, RunicDiagnosticSource } from "./diagnostics.js";
|
|
3
|
+
export { runicDevSession, runicDevSessionProxy } from "./dev-session.js";
|
|
3
4
|
export type { RunicDiagnosticDetail, RunicDiagnosticDetailValue, RunicDiagnosticFailure, RunicDiagnosticEntry, RunicDiagnosticSource, RunicTraceKind, } from "./diagnostics.js";
|
|
4
5
|
/** The API another Vite plugin reaches through `plugin.api`, Vite's inter-plugin convention. */
|
|
5
6
|
export interface RunicVitePluginApi {
|
package/dist/index.js
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
import { isAbsolute, relative } from "node:path";
|
|
3
3
|
import { sanitizeDiagnosticSummary } from "./diagnostics.js";
|
|
4
4
|
import { rewriteHostScripts, webRootPrefix } from "./host-scripts.js";
|
|
5
|
+
import { devSessionHeader, devSessionValue, devSessionVariable } from "./dev-session.js";
|
|
6
|
+
export { runicDevSession, runicDevSessionProxy } from "./dev-session.js";
|
|
5
7
|
const virtualClientId = "virtual:runic/client";
|
|
6
8
|
const resolvedVirtualClientId = `\0${virtualClientId}`;
|
|
7
9
|
const clientPackageId = "@runic-artifex/vite-plugin-runic/client";
|
|
@@ -130,10 +132,13 @@ export function runic(options = {}) {
|
|
|
130
132
|
server = viteServer;
|
|
131
133
|
viteServer.ws.on(connectionEvent, (payload) => applyConnection(payload));
|
|
132
134
|
viteServer.ws.on(diagnosticEvent, (payload) => appendDiagnostic(payload));
|
|
135
|
+
const devSession = devSessionValue(process.env[devSessionVariable]);
|
|
133
136
|
viteServer.middlewares.use("/__runic/state", (_request, response) => {
|
|
134
137
|
response.statusCode = 200;
|
|
135
138
|
response.setHeader("Content-Type", "application/json; charset=utf-8");
|
|
136
139
|
response.setHeader("Cache-Control", "no-store");
|
|
140
|
+
if (devSession !== undefined)
|
|
141
|
+
response.setHeader(devSessionHeader, devSession);
|
|
137
142
|
response.end(JSON.stringify(withoutFailures(state)));
|
|
138
143
|
});
|
|
139
144
|
viteServer.httpServer?.once("close", () => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@runic-artifex/vite-plugin-runic",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Vite 8 development and DevTools integration for Runic applications",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
},
|
|
36
36
|
"peerDependencies": {
|
|
37
37
|
"@vitejs/devtools": "^0.7.6",
|
|
38
|
-
"vite": ">=8.
|
|
38
|
+
"vite": ">=8.3.3 <9"
|
|
39
39
|
},
|
|
40
40
|
"peerDependenciesMeta": {
|
|
41
41
|
"@vitejs/devtools": {
|
|
@@ -50,7 +50,7 @@
|
|
|
50
50
|
"vite": "8.3.4"
|
|
51
51
|
},
|
|
52
52
|
"engines": {
|
|
53
|
-
"node": "
|
|
53
|
+
"node": "^24.18.0 || ^26.0.0"
|
|
54
54
|
},
|
|
55
55
|
"publishConfig": {
|
|
56
56
|
"access": "public",
|
|
@@ -61,7 +61,7 @@
|
|
|
61
61
|
"url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
|
|
62
62
|
"directory": "packages/web/vite-plugin-runic"
|
|
63
63
|
},
|
|
64
|
-
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.
|
|
64
|
+
"homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.11.0/packages/web/vite-plugin-runic#readme",
|
|
65
65
|
"bugs": {
|
|
66
66
|
"url": "https://github.com/Runic-Artifex/runic-sdk/issues"
|
|
67
67
|
},
|
|
@@ -72,5 +72,5 @@
|
|
|
72
72
|
"vite-plugin",
|
|
73
73
|
"devtools"
|
|
74
74
|
],
|
|
75
|
-
"gitHead": "
|
|
75
|
+
"gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
|
|
76
76
|
}
|