@gjsify/create-app 0.40.0 → 0.42.0

package/README.md

@@ -16,36 +16,61 @@ yarn create @gjsify/app my-app
 pnpm create @gjsify/app my-app
 ```
 
+On a terminal it asks three questions in order — template, runtime, package
+manager — each narrowing the next. Every question can be answered by a flag
+instead, which is also how it is driven without a TTY.
+
 ### Options
 
 | | |
 |---|---|
 | `-t, --template <name>` | Template to scaffold from. Required when stdin is not a TTY; otherwise prompted for. |
+| `-r, --runtime <rt>` | Runtime to set the project up for — one of the runtimes the chosen template declares. Decides which package managers are offered and which start script the next steps name. |
 | `-f, --force` | Scaffold into a non-empty directory. |
 | `--install` | Install dependencies after scaffolding. |
-| `-p, --package-manager <pm>` | `npm` (default), `yarn`, `pnpm` or `gjsify`. Used for `--install` and for the commands printed in the next steps. |
+| `-p, --package-manager <pm>` | Must be one the chosen runtime can install for (see below). Used for `--install` and for the commands printed in the next steps. |
+
+### Runtime → package manager
+
+An installer has to produce the module layout its runtime resolves against, so
+the runtime decides which managers are on offer:
+
+| Runtime | Package managers |
+|---|---|
+| `gjs` | `gjsify` |
+| `node` | `npm`, `yarn`, `pnpm`, `gjsify` |
+| `bun` | `bun` |
+| `deno` | `deno` |
+
+Where a runtime offers exactly one, nothing is asked — it is used and named.
+`gjsify` is gjsify's own installer and the only one of the six that works on a
+host with no Node.js at all, which is why it is what the `gjs` column installs
+with.
 
-`gjsify` is gjsify's own installer and the only one of the four that works on a
-host with no Node.js at all.
+Passing `-p` without `-r` settles the runtime too: `-p bun` sets the project up
+for Bun, `-p gjsify` for GJS. Off a TTY, `--runtime` and `--package-manager` are
+reported when they fall back to a default rather than being assumed silently —
+and `--package-manager` is *required* alongside `--install`, since that is the
+one flag whose default would reach your disk.
 
 ## Templates
 
-| Template | Runtimes | |
-|---|---|---|
-| `gtk-minimal` | GJS | `Gtk.Window` + `Gtk.Label`; no Adwaita, no Blueprint. |
-| `adw-canvas2d` | GJS | Adwaita app rendering through the HTML Canvas 2D API (Blueprint UI). |
-| `adw-webgl` | GJS | Adwaita app rendering through WebGL + three.js (Blueprint UI). |
-| `adw-game` | GJS | Adwaita game shell on Excalibur.js; WebGL with a Canvas 2D fallback. |
-| `cli` | GJS · Node · Bun · Deno | Command-line tool using yargs. |
-| `web-server-hono` | GJS · Node · Bun · Deno | HTTP server using Hono (Web-standard fetch-style API). |
-| `web-server-express` | GJS · Node · Bun · Deno | HTTP server using Express. |
-
-The GTK/Adwaita templates drive libadwaita through `gi://`, so GJS is where they
-belong. The other three ship two bundles — `--app gjs` and `--app node`, the
-latter shared by Node, Bun and Deno, whose common ABI is Node-API. Each template
-declares its own reach in `package.json` as `gjsify.example.runtimes`, and every
-build names its `--app` target explicitly rather than inheriting whichever
-runtime happens to invoke it.
+| Template | |
+|---|---|
+| `gtk-minimal` | `Gtk.Window` + `Gtk.Label`; no Adwaita, no Blueprint. |
+| `adw-canvas2d` | Adwaita app rendering through the HTML Canvas 2D API (Blueprint UI). |
+| `adw-webgl` | Adwaita app rendering through WebGL + three.js (Blueprint UI). |
+| `adw-game` | Adwaita game shell on Excalibur.js; WebGL with a Canvas 2D fallback. |
+| `cli` | Command-line tool using yargs. |
+| `web-server-hono` | HTTP server using Hono (Web-standard fetch-style API). |
+| `web-server-express` | HTTP server using Express. |
+
+Each template declares its own reach in `package.json` as
+`gjsify.example.runtimes`, and the runtime prompt offers exactly that — no list
+is kept here, because a second copy is the one that goes stale. Templates ship
+two bundles, `--app gjs` and `--app node`, the latter shared by Node, Bun and
+Deno, whose common ABI is Node-API; every build names its `--app` target
+explicitly rather than inheriting whichever runtime happens to invoke it.
 
 ## Operating systems
 

package/dist-templates/adw-canvas2d/README.md

@@ -17,22 +17,32 @@ engine the build needs when it runs under GJS — is listed explicitly in
 ## Commands
 
 ```bash
-npm run dev       # build + run
-npm run build     # bundle for GJS  → dist/index.gjs.js
-npm start         # run the built bundle on GJS
-npm run check     # type-check
-npm run clear     # remove build output
+npm run dev            # watch, rebuild + relaunch on GJS
+npm run build          # bundle for every runtime (dist/index.gjs.js + dist/index.node.mjs)
+npm start              # run on GJS
+npm run start:node     # run on Node.js
+npm run start:bun      # run on Bun
+npm run start:deno     # run on Deno
+npm run check          # type-check
+npm run clear          # remove build output
 ```
 
 ## Runtimes
 
-This template targets **GJS**. It drives GTK/libadwaita through `gi://`, so GJS
-is where it belongs — `package.json` declares that as
-`gjsify.example.runtimes: ["gjs"]`, and the build passes `--app gjs` explicitly
-so the target does not silently follow whichever runtime happens to invoke it.
+This template runs on **GJS, Node.js, Bun and Deno**, declared in `package.json`
+as `gjsify.example.runtimes`. Two bundles cover all four: `--app gjs` produces
+`dist/index.gjs.js`, and `--app node` produces `dist/index.node.mjs`, which
+Node, Bun and Deno all consume (Node-API is their common ABI).
 
-gjsify itself also targets Node.js, Bun and Deno; the `cli`, `web-server-hono`
-and `web-server-express` templates are the ones that ship bundles for all four.
+Off GJS the `gi://` imports are served by `@gjsify/node-gi`, an N-API addon that
+gives Node/Bun/Deno a real GObject-Introspection host. That is why it is a
+runtime dependency here rather than a build tool: the `--app node` bundle imports
+it. GTK and libadwaita still have to be installed on the machine either way — the
+runtime only decides who talks to them.
+
+The build names its target explicitly. Without `--app`, `gjsify build` follows
+the runtime that happens to be invoking it, so the same `npm run build` would
+produce a different artifact on a contributor's machine than in CI.
 
 ## Operating systems
 

package/dist-templates/adw-canvas2d/package.json

@@ -7,9 +7,14 @@
     "scripts": {
         "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js --globals auto,dom",
+        "build": "gjsify run build:gjs && gjsify run build:node",
+        "build:gjs": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js --globals auto,dom",
+        "build:node": "gjsify build src/index.ts --app node --outfile dist/index.node.mjs --globals auto,dom",
         "start": "gjsify run dist/index.gjs.js",
-        "dev": "gjsify run build && gjsify run start"
+        "start:node": "gjsify run dist/index.node.mjs --runtime node",
+        "start:bun": "gjsify run dist/index.node.mjs --runtime bun",
+        "start:deno": "gjsify run dist/index.node.mjs --runtime deno",
+        "dev": "gjsify dev --runtime gjs"
     },
     "devDependencies": {
         "@girs/adw-1": "^4.1.0",
@@ -17,21 +22,27 @@
         "@girs/gjs": "^4.1.0",
         "@girs/gobject-2.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
-        "@gjsify/cli": "^0.40.0",
-        "@gjsify/rolldown-native": "^0.40.0",
-        "@gjsify/vite-plugin-blueprint": "^0.40.0",
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/dom-elements": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0",
+        "@gjsify/vite-plugin-blueprint": "^0.42.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
-        "@gjsify/canvas2d": "^0.40.0"
+        "@gjsify/canvas2d": "^0.42.0",
+        "@gjsify/node-gi": "^0.42.0"
     },
     "gjsify": {
         "main": "dist/index.gjs.js",
         "example": {
             "runtimes": [
-                "gjs"
-            ]
+                "gjs",
+                "node",
+                "bun",
+                "deno"
+            ],
+            "node": "dist/index.node.mjs"
         }
     }
 }

package/dist-templates/adw-canvas2d/src/index.ts

@@ -16,4 +16,9 @@ app.connect('activate', () => {
     win.present();
 });
 
-app.run([]);
+// runAsync, not the sync run(): it defers the blocking main loop to a macrotask so
+// promise continuations queued before it still drain. A sync run() works today, but
+// it parks them until the loop returns the moment anything here becomes asynchronous
+// — ADR 0009's latent hang, which node-gi inherits on node/bun/deno (node-gtk #442).
+// One lifecycle for all four runtimes, and the one a scaffolded app should grow from.
+await app.runAsync([]);

package/dist-templates/adw-game/README.md

@@ -17,22 +17,50 @@ engine the build needs when it runs under GJS — is listed explicitly in
 ## Commands
 
 ```bash
-npm run dev       # build + run
-npm run build     # bundle for GJS  → dist/index.gjs.js
-npm start         # run the built bundle on GJS
-npm run check     # type-check
-npm run clear     # remove build output
+npm run dev            # watch, rebuild + relaunch on GJS
+npm run build          # bundle for every runtime (dist/index.gjs.js + dist/index.node.mjs)
+npm start              # run on GJS
+npm run start:node     # run on Node.js
+npm run start:bun      # run on Bun
+npm run start:deno     # run on Deno
+npm run check          # type-check
+npm run clear          # remove build output
 ```
 
 ## Runtimes
 
-This template targets **GJS**. It drives GTK/libadwaita through `gi://`, so GJS
-is where it belongs — `package.json` declares that as
-`gjsify.example.runtimes: ["gjs"]`, and the build passes `--app gjs` explicitly
-so the target does not silently follow whichever runtime happens to invoke it.
+This template runs on **GJS, Node.js, Bun and Deno**, declared in `package.json`
+as `gjsify.example.runtimes`. Two bundles cover all four: `--app gjs` produces
+`dist/index.gjs.js`, and `--app node` produces `dist/index.node.mjs`, which
+Node, Bun and Deno all consume (Node-API is their common ABI). The GTK and
+libadwaita widgets are the same on every one — off GJS they come through
+`@gjsify/node-gi`, which is why it is a runtime dependency rather than a
+build-time one.
 
-gjsify itself also targets Node.js, Bun and Deno; the `cli`, `web-server-hono`
-and `web-server-express` templates are the ones that ship bundles for all four.
+The build names its target explicitly. Without `--app`, `gjsify build` follows
+the runtime that happens to be invoking it, so the same `npm run build` would
+produce a different artifact on a contributor's machine than in CI.
+
+`src/index.ts` awaits `app.runAsync()` rather than calling the blocking
+`app.run()`. Excalibur boots through promises, and `runAsync` defers the main
+loop by one macrotask so that work settles first. The blocking call still boots
+the starter game on all four runtimes; `runAsync` is what a game that loads
+resources before its first frame needs.
+
+### The `--globals` list
+
+Both builds inject the same set, so a global cannot be present on one runtime
+and missing on the other:
+
+- `auto,dom` — what the detector finds plus the DOM group Excalibur draws into
+  (`document`, `HTMLCanvasElement`, `Image`, `ResizeObserver`, …).
+- `XMLHttpRequest`, `ProgressEvent` — Excalibur's resource loader is XHR-based,
+  and the XHR implementation reports progress by constructing `ProgressEvent`.
+  Not detectable statically: `auto,dom` alone builds fine and then fails at
+  `engine.start()` with `XMLHttpRequest is not defined`.
+- `PointerEvent`, `MouseEvent`, `KeyboardEvent`, `WheelEvent` — Excalibur
+  constructs all four when it synthesises input events. Nothing in the starter
+  game reads input, so the failure would first appear in *your* code.
 
 ## Operating systems
 

package/dist-templates/adw-game/package.json

@@ -7,9 +7,14 @@
     "scripts": {
         "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js --globals auto,dom",
+        "build": "gjsify run build:gjs && gjsify run build:node",
+        "build:gjs": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js --globals auto,dom,XMLHttpRequest,ProgressEvent,PointerEvent,MouseEvent,KeyboardEvent,WheelEvent",
+        "build:node": "gjsify build src/index.ts --app node --outfile dist/index.node.mjs --globals auto,dom,XMLHttpRequest,ProgressEvent,PointerEvent,MouseEvent,KeyboardEvent,WheelEvent",
         "start": "gjsify run dist/index.gjs.js",
-        "dev": "gjsify run build && gjsify run start"
+        "start:node": "gjsify run dist/index.node.mjs --runtime node",
+        "start:bun": "gjsify run dist/index.node.mjs --runtime bun",
+        "start:deno": "gjsify run dist/index.node.mjs --runtime deno",
+        "dev": "gjsify dev --runtime gjs"
     },
     "devDependencies": {
         "@girs/adw-1": "^4.1.0",
@@ -17,23 +22,31 @@
         "@girs/gjs": "^4.1.0",
         "@girs/gobject-2.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
-        "@gjsify/canvas2d": "^0.40.0",
-        "@gjsify/cli": "^0.40.0",
-        "@gjsify/rolldown-native": "^0.40.0",
-        "@gjsify/vite-plugin-blueprint": "^0.40.0",
+        "@gjsify/canvas2d": "^0.42.0",
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/dom-elements": "^0.42.0",
+        "@gjsify/dom-events": "^0.42.0",
+        "@gjsify/fetch": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0",
+        "@gjsify/vite-plugin-blueprint": "^0.42.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
-        "@gjsify/webgl": "^0.40.0",
+        "@gjsify/node-gi": "^0.42.0",
+        "@gjsify/webgl": "^0.42.0",
         "excalibur": "0.32.0"
     },
     "gjsify": {
         "main": "dist/index.gjs.js",
         "example": {
             "runtimes": [
-                "gjs"
-            ]
+                "gjs",
+                "node",
+                "bun",
+                "deno"
+            ],
+            "node": "dist/index.node.mjs"
         }
     }
 }

package/dist-templates/adw-game/src/index.ts

@@ -16,4 +16,9 @@ app.connect('activate', () => {
     win.present();
 });
 
-app.run([]);
+// runAsync, not the blocking run(): it defers the main loop by one macrotask, so
+// promise work queued while the app starts — engine.start(), and the resources a
+// real game loads before its first frame — settles before the loop takes the
+// thread. The blocking run() does boot THIS starter game on all four runtimes;
+// runAsync is the lifecycle GJS recommends and the one a growing game needs.
+await app.runAsync([]);

package/dist-templates/adw-webgl/README.md

@@ -17,22 +17,45 @@ engine the build needs when it runs under GJS — is listed explicitly in
 ## Commands
 
 ```bash
-npm run dev       # build + run
-npm run build     # bundle for GJS  → dist/index.gjs.js
-npm start         # run the built bundle on GJS
-npm run check     # type-check
-npm run clear     # remove build output
+npm run dev         # watch, rebuild + relaunch on GJS
+npm run build       # both bundles: dist/index.gjs.js and dist/index.node.mjs
+npm start           # run the built bundle on GJS
+npm run start:node  # …on Node.js   ┐
+npm run start:bun   # …on Bun       ├ all three share dist/index.node.mjs
+npm run start:deno  # …on Deno      ┘
+npm run check       # type-check
+npm run clear       # remove build output
 ```
 
 ## Runtimes
 
-This template targets **GJS**. It drives GTK/libadwaita through `gi://`, so GJS
-is where it belongs — `package.json` declares that as
-`gjsify.example.runtimes: ["gjs"]`, and the build passes `--app gjs` explicitly
-so the target does not silently follow whichever runtime happens to invoke it.
+This app runs on all four runtimes gjsify targets — **GJS, Node.js, Bun and
+Deno** — and opens the same GTK/libadwaita window with the same three.js scene on
+each. `package.json` declares that as
+`gjsify.example.runtimes: ["gjs", "node", "bun", "deno"]`.
 
-gjsify itself also targets Node.js, Bun and Deno; the `cli`, `web-server-hono`
-and `web-server-express` templates are the ones that ship bundles for all four.
+Two bundles, not four. `--app gjs` produces the native GJS bundle; `--app node`
+produces one bundle that Node, Bun and Deno all run, with `gi://` served by
+`@gjsify/node-gi`. It is a **runtime** dependency, not a build-time one: the node
+bundle does not inline it, it keeps `import … from '@gjsify/node-gi/cairo'` (and
+`/system`, `/gi`) as live imports, so the package has to be there when the app
+runs, not only when it builds. That is why it sits in `dependencies` — move it to
+`devDependencies` and the app still builds and still runs from a dev checkout,
+then dies with `Cannot find module '@gjsify/node-gi/gi'` the first time someone
+installs without dev deps.
+
+`--globals auto,dom` on the `--app node` build is not decoration. Auto-detection
+runs on the GJS target only; a node bundle routes the `@gjsify/*` register
+subpaths to `@gjsify/empty` unless the DOM surface is requested by name. Drop
+`dom` and the window still opens, but `canvas.getContext('webgl2')` throws
+`WebGL2RenderingContext is not a constructor` and the canvas stays empty.
+
+The entry point uses `await app.runAsync([])` rather than the synchronous
+`app.run([])`. It is the recommended `Gio.Application` lifecycle and the form the
+multi-runtime showcases use: a sync `run()` blocks the thread inside the GLib main
+loop, which hangs any startup that awaits something. This scene awaits nothing, so
+the sync form happens to work here too — the async one is what keeps working once
+you add a step that does.
 
 ## Operating systems
 

package/dist-templates/adw-webgl/package.json

@@ -7,9 +7,14 @@
     "scripts": {
         "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js",
+        "build": "gjsify run build:gjs && gjsify run build:node",
+        "build:gjs": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js",
+        "build:node": "gjsify build src/index.ts --app node --outfile dist/index.node.mjs --globals auto,dom",
         "start": "gjsify run dist/index.gjs.js",
-        "dev": "gjsify run build && gjsify run start"
+        "start:node": "gjsify run dist/index.node.mjs --runtime node",
+        "start:bun": "gjsify run dist/index.node.mjs --runtime bun",
+        "start:deno": "gjsify run dist/index.node.mjs --runtime deno",
+        "dev": "gjsify dev --runtime gjs"
     },
     "devDependencies": {
         "@girs/adw-1": "^4.1.0",
@@ -17,23 +22,29 @@
         "@girs/gjs": "^4.1.0",
         "@girs/gobject-2.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
-        "@gjsify/cli": "^0.40.0",
-        "@gjsify/rolldown-native": "^0.40.0",
-        "@gjsify/vite-plugin-blueprint": "^0.40.0",
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/dom-elements": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0",
+        "@gjsify/vite-plugin-blueprint": "^0.42.0",
         "@types/node": "^25.9.2",
         "@types/three": "^0.185.0",
         "typescript": "^6.0.3"
     },
     "dependencies": {
-        "@gjsify/webgl": "^0.40.0",
+        "@gjsify/node-gi": "^0.42.0",
+        "@gjsify/webgl": "^0.42.0",
         "three": "0.185.1"
     },
     "gjsify": {
         "main": "dist/index.gjs.js",
         "example": {
             "runtimes": [
-                "gjs"
-            ]
+                "gjs",
+                "node",
+                "bun",
+                "deno"
+            ],
+            "node": "dist/index.node.mjs"
         }
     }
 }

package/dist-templates/adw-webgl/src/index.ts

@@ -16,4 +16,11 @@ app.connect('activate', () => {
     win.present();
 });
 
-app.run([]);
+// runAsync, not the sync run(): it is the recommended Gio.Application lifecycle
+// and what every multi-runtime showcase here uses, because sync run() blocks the
+// thread inside the GLib main loop — which is what hangs a startup that awaits
+// anything, and the documented hazard on the `--app node` reverse bridge.
+// Measured at 0.40.0: this scene starts nothing async, so the sync form happens
+// to work on all four today. Kept anyway, so the template does not hand a
+// scaffolded app the form that breaks the moment it grows an async startup step.
+await app.runAsync([]);

package/dist-templates/cli/README.md

@@ -17,7 +17,7 @@ engine the build needs when it runs under GJS — is listed explicitly in
 ## Commands
 
 ```bash
-npm run dev            # build for GJS + run
+npm run dev            # watch, rebuild + relaunch on GJS
 npm run build          # bundle for every runtime (dist/index.gjs.js + dist/index.node.mjs)
 npm start              # run on GJS
 npm run start:node     # run on Node.js

package/dist-templates/cli/package.json

@@ -14,13 +14,13 @@
         "start:node": "gjsify run dist/index.node.mjs --runtime node",
         "start:bun": "gjsify run dist/index.node.mjs --runtime bun",
         "start:deno": "gjsify run dist/index.node.mjs --runtime deno",
-        "dev": "gjsify run build:gjs && gjsify run start"
+        "dev": "gjsify dev --runtime gjs"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.40.0",
-        "@gjsify/node-globals": "^0.40.0",
-        "@gjsify/rolldown-native": "^0.40.0",
-        "@gjsify/runtime": "^0.40.0",
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/node-globals": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0",
+        "@gjsify/runtime": "^0.42.0",
         "@types/node": "^25.9.2",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"

package/dist-templates/cli/src/index.ts

@@ -31,7 +31,20 @@ yargs(hideBin(process.argv))
             console.log(`${c.dim}pid     :${c.reset} ${process.pid}`);
         },
     )
-    .demandCommand(1, 'Pass --help to see available commands.')
+    // The `$0` default command. Without it, `demandCommand(1)` made the scripts
+    // the scaffolder itself prints — `npm run dev`, `npm start`, neither of which
+    // passes an argument — exit 1 with "Pass --help to see available commands."
+    // on a project created seconds earlier.
+    .command(
+        '$0',
+        'Show what this starter does',
+        () => {},
+        () => {
+            console.log(`${c.dim}runtime :${c.reset} ${c.green}${runtimeName}${c.reset}`);
+            console.log('');
+            console.log(`Try ${c.cyan}greet <name>${c.reset}, ${c.cyan}info${c.reset} or ${c.cyan}--help${c.reset}.`);
+        },
+    )
     .strict()
     .help()
     .parse();

package/dist-templates/gtk-minimal/README.md

@@ -17,22 +17,43 @@ engine the build needs when it runs under GJS — is listed explicitly in
 ## Commands
 
 ```bash
-npm run dev       # build + run
-npm run build     # bundle for GJS  → dist/index.gjs.js
-npm start         # run the built bundle on GJS
-npm run check     # type-check
-npm run clear     # remove build output
+npm run dev         # watch, rebuild + relaunch on GJS
+npm run build       # bundle both targets
+npm run build:gjs   # → dist/index.gjs.js
+npm run build:node  # → dist/index.node.mjs
+npm start           # run on GJS
+npm run start:node  # run on Node.js
+npm run start:bun   # run on Bun
+npm run start:deno  # run on Deno
+npm run check       # type-check
+npm run clear       # remove build output
 ```
 
 ## Runtimes
 
-This template targets **GJS**. It drives GTK/libadwaita through `gi://`, so GJS
-is where it belongs — `package.json` declares that as
-`gjsify.example.runtimes: ["gjs"]`, and the build passes `--app gjs` explicitly
-so the target does not silently follow whichever runtime happens to invoke it.
+One `src/index.ts` runs on all four runtimes gjsify targets, out of two bundles:
 
-gjsify itself also targets Node.js, Bun and Deno; the `cli`, `web-server-hono`
-and `web-server-express` templates are the ones that ship bundles for all four.
+| Bundle | Built with | Runs on | `gi://` resolves through |
+|---|---|---|---|
+| `dist/index.gjs.js` | `--app gjs` | GJS | the interpreter itself |
+| `dist/index.node.mjs` | `--app node` | Node.js, Bun, Deno | [`@gjsify/node-gi`](https://www.npmjs.com/package/@gjsify/node-gi) |
+
+Node, Bun and Deno share the one `--app node` bundle — Node-API is their common
+ABI, so none of them needs a target of its own. That is also why
+`@gjsify/node-gi` sits in `dependencies` rather than `devDependencies`: the built
+bundle imports it while it runs, not while it builds.
+
+Both builds name `--app` explicitly so the target cannot silently follow
+whichever runtime happens to invoke the build. `package.json` then declares the
+result as `gjsify.example.runtimes`, which is what `gjsify run --runtime <name>`
+checks against — asking for a runtime this project has no bundle for fails with a
+message instead of crashing somewhere inside one.
+
+Neither build names `--globals`. The default is `auto`, and this source touches
+no web API — only `gi://` and `process`, which `auto` shims on GJS and which is
+native on the other three. Templates that draw through a Canvas or WebGL request
+that surface explicitly (`--globals auto,dom`); asking for it here would inject
+registers nothing ever calls.
 
 ## Operating systems
 

package/dist-templates/gtk-minimal/package.json

@@ -7,27 +7,37 @@
     "scripts": {
         "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js",
+        "build": "gjsify run build:gjs && gjsify run build:node",
+        "build:gjs": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js",
+        "build:node": "gjsify build src/index.ts --app node --outfile dist/index.node.mjs",
         "start": "gjsify run dist/index.gjs.js",
-        "dev": "gjsify run build && gjsify run start"
+        "start:node": "gjsify run dist/index.node.mjs --runtime node",
+        "start:bun": "gjsify run dist/index.node.mjs --runtime bun",
+        "start:deno": "gjsify run dist/index.node.mjs --runtime deno",
+        "dev": "gjsify dev --runtime gjs"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.40.0",
-        "@gjsify/rolldown-native": "^0.40.0",
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/rolldown-native": "^0.42.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "@girs/gio-2.0": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
-        "@girs/gtk-4.0": "^4.1.0"
+        "@girs/gtk-4.0": "^4.1.0",
+        "@gjsify/node-gi": "^0.42.0"
     },
     "gjsify": {
         "main": "dist/index.gjs.js",
         "example": {
             "runtimes": [
-                "gjs"
-            ]
+                "gjs",
+                "node",
+                "bun",
+                "deno"
+            ],
+            "node": "dist/index.node.mjs"
         }
     }
 }

package/dist-templates/web-server-express/README.md

@@ -17,7 +17,7 @@ engine the build needs when it runs under GJS — is listed explicitly in
 ## Commands
 
 ```bash
-npm run dev            # build for GJS + run
+npm run dev            # watch, rebuild + relaunch on GJS
 npm run build          # bundle for every runtime (dist/index.gjs.js + dist/index.node.mjs)
 npm start              # run on GJS
 npm run start:node     # run on Node.js