@gjsify/create-app 0.30.0 → 0.32.0

package/README.md

@@ -2,18 +2,56 @@
 
 Scaffolding tool for creating new Gjsify projects.
 
-Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js, Web and
+DOM APIs for GJS (GNOME JavaScript), plus Node.js, Bun and Deno.
 
 ## Usage
 
 ```bash
 gjsify create my-app
 
-# npm or yarn create also work:
+# npm, yarn and pnpm create also work:
 npm create @gjsify/app my-app
 yarn create @gjsify/app my-app
+pnpm create @gjsify/app my-app
 ```
 
+### Options
+
+| | |
+|---|---|
+| `-t, --template <name>` | Template to scaffold from. Required when stdin is not a TTY; otherwise prompted for. |
+| `-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. |
+
+`gjsify` is gjsify's own installer and the only one of the four that works on a
+host with no Node.js at all.
+
+## 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.
+
+## Operating systems
+
+gjsify targets Linux, macOS and Windows (ADR 0018). What a scaffolded project
+can do on each depends on the GNOME libraries installed there, not on gjsify.
+
 ## License
 
 MIT

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

@@ -1,25 +1,57 @@
 # new-gjsify-app
 
-An Adwaita app with HTML Canvas 2D rendering (Blueprint UI), scaffolded from the gjsify `adw-canvas2d` template.
+An Adwaita app rendering with the HTML Canvas 2D API (Blueprint UI), scaffolded from the gjsify `adw-canvas2d` template.
+
+## Install
+
+```bash
+npm install          # or: yarn / pnpm install, or `gjsify install`
+```
+
+Any of the four works. `gjsify install` is gjsify's own installer and the only
+one that works on a host with no Node.js at all; npm, yarn and pnpm are fine
+everywhere else. Whichever you use, `@gjsify/rolldown-native` — the bundler
+engine the build needs when it runs under GJS — is listed explicitly in
+`devDependencies` so it is installed either way.
 
 ## Commands
 
 ```bash
-npm install       # or: gjsify install
 npm run dev       # build + run
-npm run build     # bundle for GJS
-npm start         # run the built bundle
+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
 ```
 
+## 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.
+
+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.
+
+## Operating systems
+
+gjsify targets Linux, macOS and Windows. What this project can actually do on
+each depends on the GNOME libraries you have installed, not on gjsify — GTK and
+libadwaita are packaged for all three, but Linux is where they are best
+supported and best tested. See
+[Platform support](https://gjsify.github.io/gjsify/platform-support/).
+
 ## Versioning & compatibility
 
 All `@gjsify/*` packages ship as one release train — compatibility between them
-is guaranteed only within the same release version. Upgrade them together
-instead of bumping individual packages:
+is guaranteed only within the same release version, so upgrade them together
+rather than bumping individual packages:
 
 ```bash
-gjsify upgrade --latest --filter @gjsify   # bump all @gjsify/* deps to the same train
+gjsify upgrade --latest --filter @gjsify   # bump every @gjsify/* dep to the newest train
+gjsify upgrade --align                     # repair drift back onto one train
+gjsify upgrade --check                     # fail if the deps straddle two trains
 ```
 
 See [Versioning & Compatibility](https://gjsify.github.io/gjsify/versioning/)

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

@@ -1,14 +1,15 @@
 {
     "name": "new-gjsify-app",
     "description": "Adwaita app with HTML Canvas 2D rendering (Blueprint UI).",
-    "version": "0.1.10",
+    "version": "0.1.0",
     "type": "module",
     "private": true,
     "scripts": {
+        "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --outfile dist/index.js --globals auto,dom",
-        "start": "gjsify run dist/index.js",
-        "dev": "gjsify build src/index.ts --outfile dist/index.js --globals auto,dom && gjsify run dist/index.js"
+        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js --globals auto,dom",
+        "start": "gjsify run dist/index.gjs.js",
+        "dev": "gjsify run build && gjsify run start"
     },
     "devDependencies": {
         "@girs/adw-1": "^4.1.0",
@@ -16,12 +17,21 @@
         "@girs/gjs": "^4.1.0",
         "@girs/gobject-2.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
-        "@gjsify/cli": "^0.30.0",
-        "@gjsify/vite-plugin-blueprint": "^0.30.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0",
+        "@gjsify/vite-plugin-blueprint": "^0.32.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
-        "@gjsify/canvas2d": "^0.30.0"
+        "@gjsify/canvas2d": "^0.32.0"
+    },
+    "gjsify": {
+        "main": "dist/index.gjs.js",
+        "example": {
+            "runtimes": [
+                "gjs"
+            ]
+        }
     }
 }

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

@@ -1,25 +1,57 @@
 # new-gjsify-app
 
-An Adwaita game shell using Excalibur.js with WebGL → Canvas2D fallback, scaffolded from the gjsify `adw-game` template.
+An Adwaita game shell built on Excalibur.js, WebGL with a Canvas 2D fallback, scaffolded from the gjsify `adw-game` template.
+
+## Install
+
+```bash
+npm install          # or: yarn / pnpm install, or `gjsify install`
+```
+
+Any of the four works. `gjsify install` is gjsify's own installer and the only
+one that works on a host with no Node.js at all; npm, yarn and pnpm are fine
+everywhere else. Whichever you use, `@gjsify/rolldown-native` — the bundler
+engine the build needs when it runs under GJS — is listed explicitly in
+`devDependencies` so it is installed either way.
 
 ## Commands
 
 ```bash
-npm install       # or: gjsify install
 npm run dev       # build + run
-npm run build     # bundle for GJS
-npm start         # run the built bundle
+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
 ```
 
+## 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.
+
+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.
+
+## Operating systems
+
+gjsify targets Linux, macOS and Windows. What this project can actually do on
+each depends on the GNOME libraries you have installed, not on gjsify — GTK and
+libadwaita are packaged for all three, but Linux is where they are best
+supported and best tested. See
+[Platform support](https://gjsify.github.io/gjsify/platform-support/).
+
 ## Versioning & compatibility
 
 All `@gjsify/*` packages ship as one release train — compatibility between them
-is guaranteed only within the same release version. Upgrade them together
-instead of bumping individual packages:
+is guaranteed only within the same release version, so upgrade them together
+rather than bumping individual packages:
 
 ```bash
-gjsify upgrade --latest --filter @gjsify   # bump all @gjsify/* deps to the same train
+gjsify upgrade --latest --filter @gjsify   # bump every @gjsify/* dep to the newest train
+gjsify upgrade --align                     # repair drift back onto one train
+gjsify upgrade --check                     # fail if the deps straddle two trains
 ```
 
 See [Versioning & Compatibility](https://gjsify.github.io/gjsify/versioning/)

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

@@ -1,14 +1,15 @@
 {
     "name": "new-gjsify-app",
     "description": "Adwaita game shell using Excalibur.js, WebGL → Canvas2D fallback.",
-    "version": "0.1.10",
+    "version": "0.1.0",
     "type": "module",
     "private": true,
     "scripts": {
+        "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --outfile dist/index.js --globals auto,dom",
-        "start": "gjsify run dist/index.js",
-        "dev": "gjsify build src/index.ts --outfile dist/index.js --globals auto,dom && gjsify run dist/index.js"
+        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js --globals auto,dom",
+        "start": "gjsify run dist/index.gjs.js",
+        "dev": "gjsify run build && gjsify run start"
     },
     "devDependencies": {
         "@girs/adw-1": "^4.1.0",
@@ -16,14 +17,23 @@
         "@girs/gjs": "^4.1.0",
         "@girs/gobject-2.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
-        "@gjsify/canvas2d": "^0.30.0",
-        "@gjsify/cli": "^0.30.0",
-        "@gjsify/vite-plugin-blueprint": "^0.30.0",
+        "@gjsify/canvas2d": "^0.32.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0",
+        "@gjsify/vite-plugin-blueprint": "^0.32.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
-        "@gjsify/webgl": "^0.30.0",
+        "@gjsify/webgl": "^0.32.0",
         "excalibur": "0.32.0"
+    },
+    "gjsify": {
+        "main": "dist/index.gjs.js",
+        "example": {
+            "runtimes": [
+                "gjs"
+            ]
+        }
     }
 }

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

@@ -1,25 +1,57 @@
 # new-gjsify-app
 
-An Adwaita app with WebGL + three.js (Blueprint UI), scaffolded from the gjsify `adw-webgl` template.
+An Adwaita app rendering with WebGL and three.js (Blueprint UI), scaffolded from the gjsify `adw-webgl` template.
+
+## Install
+
+```bash
+npm install          # or: yarn / pnpm install, or `gjsify install`
+```
+
+Any of the four works. `gjsify install` is gjsify's own installer and the only
+one that works on a host with no Node.js at all; npm, yarn and pnpm are fine
+everywhere else. Whichever you use, `@gjsify/rolldown-native` — the bundler
+engine the build needs when it runs under GJS — is listed explicitly in
+`devDependencies` so it is installed either way.
 
 ## Commands
 
 ```bash
-npm install       # or: gjsify install
 npm run dev       # build + run
-npm run build     # bundle for GJS
-npm start         # run the built bundle
+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
 ```
 
+## 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.
+
+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.
+
+## Operating systems
+
+gjsify targets Linux, macOS and Windows. What this project can actually do on
+each depends on the GNOME libraries you have installed, not on gjsify — GTK and
+libadwaita are packaged for all three, but Linux is where they are best
+supported and best tested. See
+[Platform support](https://gjsify.github.io/gjsify/platform-support/).
+
 ## Versioning & compatibility
 
 All `@gjsify/*` packages ship as one release train — compatibility between them
-is guaranteed only within the same release version. Upgrade them together
-instead of bumping individual packages:
+is guaranteed only within the same release version, so upgrade them together
+rather than bumping individual packages:
 
 ```bash
-gjsify upgrade --latest --filter @gjsify   # bump all @gjsify/* deps to the same train
+gjsify upgrade --latest --filter @gjsify   # bump every @gjsify/* dep to the newest train
+gjsify upgrade --align                     # repair drift back onto one train
+gjsify upgrade --check                     # fail if the deps straddle two trains
 ```
 
 See [Versioning & Compatibility](https://gjsify.github.io/gjsify/versioning/)

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

@@ -1,14 +1,15 @@
 {
     "name": "new-gjsify-app",
     "description": "Adwaita app with WebGL + three.js (Blueprint UI).",
-    "version": "0.1.10",
+    "version": "0.1.0",
     "type": "module",
     "private": true,
     "scripts": {
+        "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --outfile dist/index.js",
-        "start": "gjsify run dist/index.js",
-        "dev": "gjsify build src/index.ts --outfile dist/index.js && gjsify run dist/index.js"
+        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js",
+        "start": "gjsify run dist/index.gjs.js",
+        "dev": "gjsify run build && gjsify run start"
     },
     "devDependencies": {
         "@girs/adw-1": "^4.1.0",
@@ -16,14 +17,23 @@
         "@girs/gjs": "^4.1.0",
         "@girs/gobject-2.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0",
-        "@gjsify/cli": "^0.30.0",
-        "@gjsify/vite-plugin-blueprint": "^0.30.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0",
+        "@gjsify/vite-plugin-blueprint": "^0.32.0",
         "@types/node": "^25.9.2",
         "@types/three": "^0.185.0",
         "typescript": "^6.0.3"
     },
     "dependencies": {
-        "@gjsify/webgl": "^0.30.0",
+        "@gjsify/webgl": "^0.32.0",
         "three": "0.185.1"
+    },
+    "gjsify": {
+        "main": "dist/index.gjs.js",
+        "example": {
+            "runtimes": [
+                "gjs"
+            ]
+        }
     }
 }

package/dist-templates/cli/README.md

@@ -1,25 +1,61 @@
 # new-gjsify-app
 
-A command-line tool using yargs, runnable on GJS, scaffolded from the gjsify `cli` template.
+A command-line tool using yargs, scaffolded from the gjsify `cli` template.
+
+## Install
+
+```bash
+npm install          # or: yarn / pnpm install, or `gjsify install`
+```
+
+Any of the four works. `gjsify install` is gjsify's own installer and the only
+one that works on a host with no Node.js at all; npm, yarn and pnpm are fine
+everywhere else. Whichever you use, `@gjsify/rolldown-native` — the bundler
+engine the build needs when it runs under GJS — is listed explicitly in
+`devDependencies` so it is installed either way.
 
 ## Commands
 
 ```bash
-npm install       # or: gjsify install
-npm run dev       # build + run
-npm run build     # bundle for GJS
-npm start         # run the built bundle
-npm run check     # type-check
+npm run dev            # build for GJS + run
+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 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 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
+
+gjsify targets Linux, macOS and Windows. What this project can actually do on
+each depends on the GNOME libraries you have installed, not on gjsify — GTK and
+libadwaita are packaged for all three, but Linux is where they are best
+supported and best tested. See
+[Platform support](https://gjsify.github.io/gjsify/platform-support/).
+
 ## Versioning & compatibility
 
 All `@gjsify/*` packages ship as one release train — compatibility between them
-is guaranteed only within the same release version. Upgrade them together
-instead of bumping individual packages:
+is guaranteed only within the same release version, so upgrade them together
+rather than bumping individual packages:
 
 ```bash
-gjsify upgrade --latest --filter @gjsify   # bump all @gjsify/* deps to the same train
+gjsify upgrade --latest --filter @gjsify   # bump every @gjsify/* dep to the newest train
+gjsify upgrade --align                     # repair drift back onto one train
+gjsify upgrade --check                     # fail if the deps straddle two trains
 ```
 
 See [Versioning & Compatibility](https://gjsify.github.io/gjsify/versioning/)

package/dist-templates/cli/package.json

@@ -1,24 +1,43 @@
 {
     "name": "new-gjsify-app",
     "description": "Command-line tool using yargs (Node.js + GJS).",
-    "version": "0.1.10",
+    "version": "0.1.0",
     "type": "module",
     "private": true,
     "scripts": {
+        "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --outfile dist/index.js",
-        "start": "gjsify run dist/index.js",
-        "dev": "gjsify build src/index.ts --outfile dist/index.js && gjsify run dist/index.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",
+        "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"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.30.0",
-        "@gjsify/node-globals": "^0.30.0",
-        "@gjsify/runtime": "^0.30.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/node-globals": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0",
+        "@gjsify/runtime": "^0.32.0",
         "@types/node": "^25.9.2",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "yargs": "^18.0.0"
+    },
+    "gjsify": {
+        "main": "dist/index.gjs.js",
+        "example": {
+            "runtimes": [
+                "gjs",
+                "node",
+                "bun",
+                "deno"
+            ],
+            "node": "dist/index.node.mjs"
+        }
     }
 }

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

@@ -2,24 +2,56 @@
 
 A minimal GTK 4 app — `Gtk.Window` + `Gtk.Label`, no Adwaita, no Blueprint — scaffolded from the gjsify `gtk-minimal` template.
 
+## Install
+
+```bash
+npm install          # or: yarn / pnpm install, or `gjsify install`
+```
+
+Any of the four works. `gjsify install` is gjsify's own installer and the only
+one that works on a host with no Node.js at all; npm, yarn and pnpm are fine
+everywhere else. Whichever you use, `@gjsify/rolldown-native` — the bundler
+engine the build needs when it runs under GJS — is listed explicitly in
+`devDependencies` so it is installed either way.
+
 ## Commands
 
 ```bash
-npm install       # or: gjsify install
 npm run dev       # build + run
-npm run build     # bundle for GJS
-npm start         # run the built bundle
+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
 ```
 
+## 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.
+
+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.
+
+## Operating systems
+
+gjsify targets Linux, macOS and Windows. What this project can actually do on
+each depends on the GNOME libraries you have installed, not on gjsify — GTK and
+libadwaita are packaged for all three, but Linux is where they are best
+supported and best tested. See
+[Platform support](https://gjsify.github.io/gjsify/platform-support/).
+
 ## Versioning & compatibility
 
 All `@gjsify/*` packages ship as one release train — compatibility between them
-is guaranteed only within the same release version. Upgrade them together
-instead of bumping individual packages:
+is guaranteed only within the same release version, so upgrade them together
+rather than bumping individual packages:
 
 ```bash
-gjsify upgrade --latest --filter @gjsify   # bump all @gjsify/* deps to the same train
+gjsify upgrade --latest --filter @gjsify   # bump every @gjsify/* dep to the newest train
+gjsify upgrade --align                     # repair drift back onto one train
+gjsify upgrade --check                     # fail if the deps straddle two trains
 ```
 
 See [Versioning & Compatibility](https://gjsify.github.io/gjsify/versioning/)

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

@@ -1,17 +1,19 @@
 {
     "name": "new-gjsify-app",
     "description": "Minimal GTK4 app — Gtk.Window + Gtk.Label (no Adwaita, no Blueprint).",
-    "version": "0.1.10",
+    "version": "0.1.0",
     "type": "module",
     "private": true,
     "scripts": {
+        "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --outfile dist/index.js",
-        "start": "gjsify run dist/index.js",
-        "dev": "gjsify build src/index.ts --outfile dist/index.js && gjsify run dist/index.js"
+        "build": "gjsify build src/index.ts --app gjs --outfile dist/index.gjs.js",
+        "start": "gjsify run dist/index.gjs.js",
+        "dev": "gjsify run build && gjsify run start"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.30.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
@@ -19,5 +21,13 @@
         "@girs/gio-2.0": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
         "@girs/gtk-4.0": "^4.1.0"
+    },
+    "gjsify": {
+        "main": "dist/index.gjs.js",
+        "example": {
+            "runtimes": [
+                "gjs"
+            ]
+        }
     }
 }

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

@@ -1,25 +1,61 @@
 # new-gjsify-app
 
-An HTTP server using Express (familiar Node.js stack), scaffolded from the gjsify `web-server-express` template.
+An HTTP server using Express (the familiar Node.js stack), scaffolded from the gjsify `web-server-express` template.
+
+## Install
+
+```bash
+npm install          # or: yarn / pnpm install, or `gjsify install`
+```
+
+Any of the four works. `gjsify install` is gjsify's own installer and the only
+one that works on a host with no Node.js at all; npm, yarn and pnpm are fine
+everywhere else. Whichever you use, `@gjsify/rolldown-native` — the bundler
+engine the build needs when it runs under GJS — is listed explicitly in
+`devDependencies` so it is installed either way.
 
 ## Commands
 
 ```bash
-npm install       # or: gjsify install
-npm run dev       # build + run
-npm run build     # bundle for GJS
-npm start         # run the built bundle
-npm run check     # type-check
+npm run dev            # build for GJS + run
+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 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 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
+
+gjsify targets Linux, macOS and Windows. What this project can actually do on
+each depends on the GNOME libraries you have installed, not on gjsify — GTK and
+libadwaita are packaged for all three, but Linux is where they are best
+supported and best tested. See
+[Platform support](https://gjsify.github.io/gjsify/platform-support/).
+
 ## Versioning & compatibility
 
 All `@gjsify/*` packages ship as one release train — compatibility between them
-is guaranteed only within the same release version. Upgrade them together
-instead of bumping individual packages:
+is guaranteed only within the same release version, so upgrade them together
+rather than bumping individual packages:
 
 ```bash
-gjsify upgrade --latest --filter @gjsify   # bump all @gjsify/* deps to the same train
+gjsify upgrade --latest --filter @gjsify   # bump every @gjsify/* dep to the newest train
+gjsify upgrade --align                     # repair drift back onto one train
+gjsify upgrade --check                     # fail if the deps straddle two trains
 ```
 
 See [Versioning & Compatibility](https://gjsify.github.io/gjsify/versioning/)

package/dist-templates/web-server-express/package.json

@@ -1,24 +1,43 @@
 {
     "name": "new-gjsify-app",
     "description": "HTTP server using Express (familiar Node.js stack).",
-    "version": "0.1.10",
+    "version": "0.1.0",
     "type": "module",
     "private": true,
     "scripts": {
+        "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --outfile dist/index.js",
-        "start": "gjsify run dist/index.js",
-        "dev": "gjsify build src/index.ts --outfile dist/index.js && gjsify run dist/index.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",
+        "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"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.30.0",
-        "@gjsify/node-globals": "^0.30.0",
-        "@gjsify/runtime": "^0.30.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/node-globals": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0",
+        "@gjsify/runtime": "^0.32.0",
         "@types/express": "^5.0.6",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "express": "^5.2.1"
+    },
+    "gjsify": {
+        "main": "dist/index.gjs.js",
+        "example": {
+            "runtimes": [
+                "gjs",
+                "node",
+                "bun",
+                "deno"
+            ],
+            "node": "dist/index.node.mjs"
+        }
     }
 }

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

@@ -2,24 +2,60 @@
 
 An HTTP server using Hono (Web-standard fetch-style API), scaffolded from the gjsify `web-server-hono` template.
 
+## Install
+
+```bash
+npm install          # or: yarn / pnpm install, or `gjsify install`
+```
+
+Any of the four works. `gjsify install` is gjsify's own installer and the only
+one that works on a host with no Node.js at all; npm, yarn and pnpm are fine
+everywhere else. Whichever you use, `@gjsify/rolldown-native` — the bundler
+engine the build needs when it runs under GJS — is listed explicitly in
+`devDependencies` so it is installed either way.
+
 ## Commands
 
 ```bash
-npm install       # or: gjsify install
-npm run dev       # build + run
-npm run build     # bundle for GJS
-npm start         # run the built bundle
-npm run check     # type-check
+npm run dev            # build for GJS + run
+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 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 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
+
+gjsify targets Linux, macOS and Windows. What this project can actually do on
+each depends on the GNOME libraries you have installed, not on gjsify — GTK and
+libadwaita are packaged for all three, but Linux is where they are best
+supported and best tested. See
+[Platform support](https://gjsify.github.io/gjsify/platform-support/).
+
 ## Versioning & compatibility
 
 All `@gjsify/*` packages ship as one release train — compatibility between them
-is guaranteed only within the same release version. Upgrade them together
-instead of bumping individual packages:
+is guaranteed only within the same release version, so upgrade them together
+rather than bumping individual packages:
 
 ```bash
-gjsify upgrade --latest --filter @gjsify   # bump all @gjsify/* deps to the same train
+gjsify upgrade --latest --filter @gjsify   # bump every @gjsify/* dep to the newest train
+gjsify upgrade --align                     # repair drift back onto one train
+gjsify upgrade --check                     # fail if the deps straddle two trains
 ```
 
 See [Versioning & Compatibility](https://gjsify.github.io/gjsify/versioning/)

package/dist-templates/web-server-hono/package.json

@@ -1,24 +1,43 @@
 {
     "name": "new-gjsify-app",
     "description": "HTTP server using Hono (Web-standard fetch-style API).",
-    "version": "0.1.10",
+    "version": "0.1.0",
     "type": "module",
     "private": true,
     "scripts": {
+        "clear": "gjsify clear dist tsconfig.tsbuildinfo",
         "check": "gjsify tsc --noEmit",
-        "build": "gjsify build src/index.ts --outfile dist/index.js",
-        "start": "gjsify run dist/index.js",
-        "dev": "gjsify build src/index.ts --outfile dist/index.js && gjsify run dist/index.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",
+        "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"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.30.0",
-        "@gjsify/node-globals": "^0.30.0",
-        "@gjsify/runtime": "^0.30.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/node-globals": "^0.32.0",
+        "@gjsify/rolldown-native": "^0.32.0",
+        "@gjsify/runtime": "^0.32.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "@hono/node-server": "^2.0.8",
         "hono": "^4.12.27"
+    },
+    "gjsify": {
+        "main": "dist/index.gjs.js",
+        "example": {
+            "runtimes": [
+                "gjs",
+                "node",
+                "bun",
+                "deno"
+            ],
+            "node": "dist/index.node.mjs"
+        }
     }
 }

package/lib/create.d.ts

@@ -1,13 +1,26 @@
 export { discoverTemplates, findTemplate } from './discover-templates.js';
 export type { TemplateInfo } from './discover-templates.js';
+/**
+ * Package managers a scaffolded project can be installed with. All four work:
+ * the templates declare every dependency they need explicitly — including
+ * `@gjsify/rolldown-native`, which npm/yarn/pnpm would otherwise skip as an
+ * optional peer of `@gjsify/cli`.
+ *
+ * `gjsify` is gjsify's own installer and the only one of the four that works on
+ * a host with no Node.js at all.
+ */
+export declare const PACKAGE_MANAGERS: readonly ["npm", "yarn", "pnpm", "gjsify"];
+export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 export interface CreateProjectOptions {
     projectName: string;
     /** Template short name, e.g. "gtk-minimal". If omitted, the caller is responsible for providing one via prompt. */
     template: string;
     /** Allow scaffolding into an existing non-empty directory. */
     force?: boolean;
-    /** Run `npm install` in the scaffolded directory after writing files. */
+    /** Install dependencies in the scaffolded directory after writing files. */
     install?: boolean;
+    /** Which package manager to install with, and to name in the printed next steps. */
+    packageManager?: PackageManager;
 }
 /** npm package names: lowercase, digits, -, _, .; no leading . or _. */
 export declare function sanitizeProjectName(raw: string): string;

package/lib/create.js

@@ -3,6 +3,23 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, cpSync
 import { resolve, join } from 'node:path';
 import { discoverTemplates, findTemplate } from './discover-templates.js';
 export { discoverTemplates, findTemplate } from './discover-templates.js';
+/**
+ * Package managers a scaffolded project can be installed with. All four work:
+ * the templates declare every dependency they need explicitly — including
+ * `@gjsify/rolldown-native`, which npm/yarn/pnpm would otherwise skip as an
+ * optional peer of `@gjsify/cli`.
+ *
+ * `gjsify` is gjsify's own installer and the only one of the four that works on
+ * a host with no Node.js at all.
+ */
+export const PACKAGE_MANAGERS = ['npm', 'yarn', 'pnpm', 'gjsify'];
+/** The `install` argv for each package manager. */
+const INSTALL_ARGV = {
+    npm: ['install', '--no-audit', '--no-fund'],
+    yarn: ['install'],
+    pnpm: ['install'],
+    gjsify: ['install'],
+};
 /** Sentinel replaced by the user's project name in every text file under the template. */
 const PROJECT_NAME_SENTINEL = 'new-gjsify-app';
 /** File extensions we treat as text and scan for the sentinel. */
@@ -43,7 +60,7 @@ function isDirEmpty(path) {
 }
 export async function createProject(options) {
     const projectName = sanitizeProjectName(options.projectName);
-    const { template, force = false, install = false } = options;
+    const { template, force = false, install = false, packageManager = 'npm' } = options;
     const info = findTemplate(template);
     if (!info) {
         const available = discoverTemplates()
@@ -64,7 +81,8 @@ export async function createProject(options) {
     cpSync(info.path, targetDir, { recursive: true });
     substituteProjectName(targetDir, projectName);
     if (install) {
-        console.log('Running npm install...');
+        const argv = INSTALL_ARGV[packageManager];
+        console.log(`Running ${packageManager} ${argv[0]}...`);
         // `shell: true` is what makes this work on Windows, where `npm` is
         // `npm.cmd`: `CreateProcess` appends only `.exe` when it searches PATH
         // for a bare name, so `spawnSync('npm', …)` is ENOENT there — and
@@ -72,23 +90,24 @@ export async function createProject(options) {
         // below fired and told the user npm had failed. `npm create gjsify
         // my-app` therefore scaffolded a project, never installed anything, and
         // blamed npm for it. `shell: true` is the exemption the invariant in
-        // `@gjsify/cli`'s `utils/spawn.ts` sanctions for exactly this case.
-        const result = spawnSync('npm', ['install', '--no-audit', '--no-fund'], {
+        // `@gjsify/cli`'s `utils/spawn.ts` sanctions for exactly this case. It
+        // applies to all four managers, which all ship as `.cmd` shims there.
+        const result = spawnSync(packageManager, argv, {
             cwd: targetDir,
             stdio: 'inherit',
             shell: true,
         });
         // Report the spawn error itself when there is one. Without it a failure
-        // to START npm and a failure OF npm read identically, which is how the
-        // Windows case stayed invisible.
+        // to START the package manager and a failure OF it read identically,
+        // which is how the Windows case stayed invisible.
         if (result.error) {
-            console.warn(`npm install could not start (${result.error.message}); re-run it manually.`);
+            console.warn(`${packageManager} install could not start (${result.error.message}); re-run it manually.`);
         }
         else if (result.status !== 0) {
-            console.warn('npm install failed; re-run it manually in the project directory.');
+            console.warn(`${packageManager} install failed; re-run it manually in the project directory.`);
         }
     }
-    printNextSteps(projectName, info, install);
+    printNextSteps(projectName, info, install, packageManager);
 }
 /**
  * Walk the scaffolded tree and replace the sentinel in every text file.
@@ -119,14 +138,43 @@ function substituteProjectName(rootDir, projectName) {
         }
     }
 }
-function printNextSteps(projectName, template, installed) {
+function printNextSteps(projectName, template, installed, packageManager) {
+    // `npm run <script>` / `yarn <script>` / `pnpm <script>` / `gjsify run
+    // <script>` — the same script, four spellings. Printing the one that
+    // matches the manager the user actually chose is the whole point of
+    // threading it this far.
+    const run = packageManager === 'npm' ? 'npm run' : packageManager === 'gjsify' ? 'gjsify run' : packageManager;
     console.log('');
     console.log(`Project created from template "${template.name}".`);
     console.log('');
     console.log('Next steps:');
     console.log(`  cd ${projectName}`);
     if (!installed)
-        console.log('  npm install');
-    console.log('  npm run dev');
+        console.log(`  ${packageManager} install`);
+    console.log(`  ${run} dev`);
     console.log('');
+    // The runtimes the template DECLARES, not a fixed list: a GJS-only template
+    // must not advertise `start:node`, and a portable one must not hide it.
+    const runtimes = declaredRuntimes(template);
+    if (runtimes.length > 1) {
+        console.log(`Runs on ${runtimes.join(', ')}:`);
+        console.log(`  ${run} build`);
+        for (const runtime of runtimes) {
+            console.log(`  ${run} ${runtime === 'gjs' ? 'start' : `start:${runtime}`}`);
+        }
+        console.log('');
+    }
+}
+/** `gjsify.example.runtimes` from the template's manifest; `[]` when unstated. */
+function declaredRuntimes(template) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(template.path, 'package.json'), 'utf-8'));
+        const runtimes = pkg.gjsify?.example?.runtimes;
+        return Array.isArray(runtimes) ? runtimes.filter((r) => typeof r === 'string') : [];
+    }
+    catch {
+        // A template with no readable manifest cannot be scaffolded at all —
+        // `createProject` already failed by here. Nothing to advertise.
+        return [];
+    }
 }

package/lib/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export { createProject, sanitizeProjectName, type CreateProjectOptions } from './create.js';
+export { createProject, sanitizeProjectName, PACKAGE_MANAGERS, type CreateProjectOptions, type PackageManager, } from './create.js';
 export { discoverTemplates, findTemplate, type TemplateInfo } from './discover-templates.js';

package/lib/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { createProject } from './create.js';
+import { createProject, PACKAGE_MANAGERS } from './create.js';
 import { discoverTemplates } from './discover-templates.js';
 import { promptTemplate } from './prompt-template.js';
 const templates = discoverTemplates();
@@ -28,9 +28,16 @@ void yargs(hideBin(process.argv))
         default: false,
     })
         .option('install', {
-        describe: 'Run npm install after scaffolding',
+        describe: 'Install dependencies after scaffolding',
         type: 'boolean',
         default: false,
+    })
+        .option('package-manager', {
+        alias: 'p',
+        describe: 'Package manager to install with, and to name in the printed next steps. `gjsify` is the only one that works on a host with no Node.js.',
+        type: 'string',
+        choices: PACKAGE_MANAGERS,
+        default: 'npm',
     });
 }, async (argv) => {
     const projectName = argv['project-name'];
@@ -51,8 +58,9 @@ void yargs(hideBin(process.argv))
         template,
         force: argv['force'],
         install: argv['install'],
+        packageManager: argv['package-manager'],
     });
 })
     .help().argv;
-export { createProject, sanitizeProjectName } from './create.js';
+export { createProject, sanitizeProjectName, PACKAGE_MANAGERS, } from './create.js';
 export { discoverTemplates, findTemplate } from './discover-templates.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/create-app",
-    "version": "0.30.0",
+    "version": "0.32.0",
     "description": "Create a new Gjsify project",
     "type": "module",
     "main": "lib/create.js",