@runic-artifex/vite-plugin-runic 0.10.0 → 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 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.10.0/docs/diagnostics.md#runicp007).
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 once a View connects, and forwards
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 (specs/application, "Shared globals").
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.10.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",
@@ -50,7 +50,7 @@
50
50
  "vite": "8.3.4"
51
51
  },
52
52
  "engines": {
53
- "node": ">=24.18.0 <25"
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.10.0/packages/web/vite-plugin-runic#readme",
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": "fcc71ba13aa56c8f1a720909c1074825a1f5dd6f"
75
+ "gitHead": "318762a9d5dcdd74303ca30b095fed355a1ab21f"
76
76
  }