@silkui/vite 0.1.0 → 0.1.1

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
@@ -1,33 +1,85 @@
1
1
  # @silkui/vite
2
2
 
3
- Vite plugin for ui-js applications: a library build with one ES module for the host to
4
- evaluate, and a reload of the native window after each rebuild. It knows no UI framework:
5
- a React application adds `react()` from `@silkui/react/vite` for JSX and Fast Refresh.
3
+ The [Vite](https://vite.dev) plugin for [Silk UI](https://github.com/silk-lang/SilkUI)
4
+ JavaScript apps. It builds the app into the one ES module a Silk UI host runs, serves its
5
+ modules to the window under the dev server with hot module replacement, and reports the web
6
+ and Node APIs the build uses that the embedded SilkJS runtime does not have. It knows no UI
7
+ framework: a React app adds `react()` from `@silkui/react/vite`.
8
+
9
+ ## Install
10
+
11
+ The templates (`silk init my-app -t ui-react`, `ui-foldkit` or `ui-js`) set it up, and
12
+ `silk task dev` and `silk task build` run Vite for you. See
13
+ [Get started](https://silk-ui-docs.juliaortiz-js.workers.dev/start/). To add it to an
14
+ existing project:
15
+
16
+ ```sh
17
+ npm install -D @silkui/vite vite
18
+ ```
19
+
20
+ ## Usage
6
21
 
7
22
  ```js
23
+ // vite.config.js
8
24
  import { defineConfig } from "vite";
9
25
  import silk from "@silkui/vite";
10
26
  import react from "@silkui/react/vite";
11
27
 
12
- export default defineConfig({ plugins: [silk(), react()] });
28
+ export default defineConfig({ plugins: [silk({ entry: "src/main.tsx" }), react()] });
13
29
  ```
14
30
 
31
+ - `vite build` writes the production bundle, `dist/app.js`, with `process.env.NODE_ENV`
32
+ from the Vite mode.
33
+ - `vite` serves the modules to the host and replaces the ones an edit touches. A module
34
+ nothing accepts restarts the app. With `@silkui/react/vite`, component files keep their
35
+ state (React Fast Refresh). A build error is printed and the running app is left alone.
36
+ `import.meta.hot` works as in Vite.
37
+ - `vite build --watch --mode development` rebuilds the bundle on every change and writes
38
+ `<bundle>.stamp` after each successful build. A host that watches it reloads the whole app.
39
+ This is the production code path, so it is the mode to check a bundle in.
40
+
41
+ ## Options
42
+
15
43
  | Option | Default | Meaning |
16
44
  | --- | --- | --- |
17
45
  | `entry` | `src/main.jsx` | Entry module, relative to the Vite root |
18
46
  | `fileName` | `app.js` | Name of the bundle in `build.outDir` |
19
- | `host` | the `SILKUI_HOST` program, which `silk task dev` sets | `{ command, args, cwd }`: a host binary to start, given `--dev <port>` under the dev server and `--watch <bundle>` in watch mode |
47
+ | `host` | the `SILKUI_HOST` program, which `silk task dev` sets | `{ command, args, cwd }`: a host binary to start, given `--dev <port>` under the dev server and `--watch <bundle>` in watch mode. Without one, the plugin prints the port for a host you start yourself |
20
48
  | `port` | any free one | Port the dev server listens on for the host |
21
- | `apis` | `warn` | What to do when the build uses a web or Node API a ui-js runtime does not have: `warn`, `error` or `off` |
22
- | `allow` | none | Names of such APIs the application provides itself |
23
- | `node` | `false` | The host runs the full SilkJS runtime (ui-js-node): `node:fs` and the other Node builtins stay imports, and `apis` reports only what that runtime lacks |
49
+ | `apis` | `"warn"` | What to do when the build uses an API the runtime does not have: `"warn"`, `"error"` or `"off"` |
50
+ | `allow` | none | Names of such APIs the app provides itself, such as `provided` from `@silkui/foldkit/apis` |
51
+ | `node` | `false` | The host runs the full SilkJS runtime: `node:fs` and the other Node builtins stay imports, and `apis` reports only what that runtime lacks |
24
52
 
25
- - `vite build` makes the production bundle.
26
- - `vite` serves the modules to the host and replaces the ones an edit touches. A module
27
- nothing accepts restarts the application; with `@silkui/react/vite`, component files keep
28
- their state (React Fast Refresh).
29
- - `vite build --watch --mode development` keeps building the bundle and writes
30
- `<bundle>.stamp` after each successful build; a host that watches it reloads the whole
31
- application.
53
+ ## The missing API report
54
+
55
+ A realm has ECMAScript, timers, `requestAnimationFrame`, `console`, `performance.now`,
56
+ `navigator.clipboard` and `@silkui/core`, but no `fetch`, `URL`, `Intl`, `document`,
57
+ `process` or Node modules. Libraries written for browsers or Node often expect them, so the
58
+ plugin reads every module of a build and says which are used, and by whom:
59
+
60
+ ```
61
+ APIs used here that a ui-js runtime does not have:
62
+ fetch (network): src/api.js, ky
63
+ Intl (intl): date-fns
64
+ node:fs (node): some-package
65
+ ```
66
+
67
+ A name counts when a module reads it as a global. A `typeof` test for it, a local of the
68
+ same name and `process.env.NAME` do not count. Under the dev server the warning comes when
69
+ the module is first served. For Node's APIs at run time, build with `node: true` and give
70
+ the app the full runtime (`App.runtime(Runtime.node())` in `src/tasks.silk`).
71
+
72
+ ## TypeScript
73
+
74
+ The package ships its types: `silk(options?: SilkOptions): Plugin[]`.
75
+
76
+ ## Requirements
77
+
78
+ `vite` 8.
79
+
80
+ ## More
32
81
 
33
- See [the ui-js README](../../README.md#silkvite).
82
+ - [The ui-js reference](https://github.com/silk-lang/SilkUI/blob/main/modules/js/README.md#silkuivite),
83
+ including how the dev server talks to the host.
84
+ - [Templates](https://github.com/silk-lang/examples).
85
+ - [Source](https://github.com/silk-lang/SilkUI/tree/main/modules/js/packages/vite). MIT license.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@silkui/vite",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Vite plugin that builds a ui-js application and reloads it in the native window",
5
5
  "repository": {
6
6
  "type": "git",
package/src/dev.js CHANGED
@@ -100,7 +100,7 @@ async function bootstrapScript(modules) {
100
100
 
101
101
  /**
102
102
  * The plugins of `vite` (serve) for a ui-js application.
103
- * @param {{ entry: string, port: number, host?: { command: string, args?: string[], cwd?: string } }} options
103
+ * @param {{ entry: string, port: number, host?: { command: string, args?: readonly string[], cwd?: string } }} options
104
104
  */
105
105
  export function devPlugins(options) {
106
106
  const { channel, accept } = createChannel();
package/src/index.d.ts CHANGED
@@ -6,13 +6,13 @@ export interface SilkOptions {
6
6
  /** Name of the bundle in `build.outDir`. Default `app.js`. */
7
7
  fileName?: string;
8
8
  /** Host binary to start: given `--watch <bundle>` in watch mode, `--dev <port>` under the dev server. */
9
- host?: { command: string; args?: string[]; cwd?: string };
9
+ host?: { command: string; args?: readonly string[]; cwd?: string };
10
10
  /** Port the dev server listens on for the host. Default: any free one. */
11
11
  port?: number;
12
12
  /** What to do when the build uses a web or Node API the runtime does not have. Default `warn`. */
13
13
  apis?: "warn" | "error" | "off";
14
14
  /** Such APIs the application provides itself. */
15
- allow?: string[];
15
+ allow?: readonly string[];
16
16
  /**
17
17
  * The host runs the full SilkJS runtime (ui-js-node): Node builtins stay `node:` imports,
18
18
  * and `apis` reports only what that runtime lacks.
package/src/index.js CHANGED
@@ -20,7 +20,7 @@ import { resolveOptions } from "./resolve.js";
20
20
  * @param {object} [options]
21
21
  * @param {string} [options.entry] Entry module, relative to the Vite root. Default `src/main.jsx`.
22
22
  * @param {string} [options.fileName] Name of the bundle in `build.outDir`. Default `app.js`.
23
- * @param {{ command: string, args?: string[], cwd?: string }} [options.host] Host binary to
23
+ * @param {{ command: string, args?: readonly string[], cwd?: string }} [options.host] Host binary to
24
24
  * start. In watch mode it is given `--watch <bundle>` after `args`, under the dev
25
25
  * server `--dev <port>`.
26
26
  * @param {number} [options.port] Port the dev server listens on for the host. Default: any