create-zoijs 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to `create-zoijs` are documented here.
 
+## 0.1.3 — 2026-06-26
+
+Three new templates (now five total). No change to existing templates or the CLI
+API; `app` stays the default.
+
+- **`typescript`** — the counter as **type-checked JavaScript**: `// @ts-check` +
+  a strict `tsconfig.json` + `npm run typecheck` (`tsc --noEmit`) give full
+  TypeScript safety using `@zoijs/core`'s shipped types, with **no build step** (the
+  browser runs the `.js` as-is). Keeps the dev server on 7310.
+- **`minimal`** — the smallest scaffold: two flat files (`index.html` + `app.js`)
+  loading `@zoijs/core` from a CDN. No `package.json`, no install, no dev server —
+  run with `npx serve . -l 7310`.
+- **`library`** — a starter for authoring a Zoijs-based package: `src/index.js` +
+  hand-written `index.d.ts`, an `exports`/`types` `package.json` with a peer
+  dependency on `@zoijs/core`, and a `node:test` suite — the shape the official
+  optional packages use.
+- The scaffolder now treats `.ts`/`.d.ts` as text (token substitution), and the
+  CLI's own `npm test` targets its own test file so it no longer runs the
+  templates' bundled test files.
+
 ## 0.1.2 — 2026-06-26
 
 Dev-server output polish. No CLI API changes; same zero-dependency server on the

package/README.md

@@ -56,15 +56,24 @@ one.
 ## Templates
 
 ```bash
-npm create zoijs@latest my-app                    # default: the "app" template
-npm create zoijs@latest my-app --template basic   # a minimal counter
-npm create zoijs@latest my-app --template app     # a polished project dashboard
+npm create zoijs@latest my-app                       # default: the "app" template
+npm create zoijs@latest my-app --template app        # a polished project dashboard
+npm create zoijs@latest my-app --template basic      # a basic counter
+npm create zoijs@latest my-app --template typescript # type-checked JS, no build step
+npm create zoijs@latest my-app --template minimal    # two flat files, CDN, no install
+npm create zoijs@latest my-app --template library    # author a Zoijs-based package
 ```
 
 - **`app`** (default) — a polished project dashboard (hero, stat cards, filters,
   empty state) showing `html`, `mount`, `createState`, `computed`, `each`,
   conditional rendering, and parent⇄child component communication.
-- **`basic`** — a minimal counter, the smallest possible Zoijs app.
+- **`basic`** — a basic counter, a small local app with a dev server.
+- **`typescript`** — the counter as type-checked JavaScript (`// @ts-check` +
+  strict `tsconfig.json` + `npm run typecheck`). Full TS safety, **no build step**.
+- **`minimal`** — the smallest scaffold: two flat files loading `@zoijs/core` from a
+  CDN. No install, no dev server — run with `npx serve . -l 7310`.
+- **`library`** — a starter for authoring a Zoijs-based package: `src` + `.d.ts`,
+  `exports`/`types`, a peer dep on `@zoijs/core`, and a `node:test` suite.
 
 ## What it does
 

package/bin/create-zoijs.js

@@ -17,7 +17,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-export const TEMPLATES = ["basic", "app"];
+export const TEMPLATES = ["basic", "app", "typescript", "minimal", "library"];
 export const DEFAULT_TEMPLATE = "app";
 const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
 
@@ -75,7 +75,7 @@ export function ensureTargetAvailable(targetDir) {
   }
 }
 
-const TEXT_EXT = new Set([".js", ".mjs", ".html", ".css", ".json", ".md", ".txt", ".svg"]);
+const TEXT_EXT = new Set([".js", ".ts", ".mjs", ".html", ".css", ".json", ".md", ".txt", ".svg"]);
 const isText = (file) => file === "_gitignore" || TEXT_EXT.has(path.extname(file));
 
 function applyTokens(content, tokens) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zoijs",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Create a new Zoijs app with one command. Plain HTML, CSS, and JavaScript — no build step.",
   "type": "module",
   "bin": {
@@ -38,6 +38,6 @@
     "no-jsx"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test tests/create.test.js"
   }
 }

package/templates/library/README.md

@@ -0,0 +1,48 @@
+# {{APP_NAME}}
+
+A small library built on [Zoijs](https://zoijs.dev) — plain JavaScript, types
+shipped as `.d.ts`, **no build step.**
+
+This is the same shape the official optional packages (`@zoijs/forms`,
+`@zoijs/storage`, …) use: one tiny module that imports **only** the core's public
+API, with hand-written type definitions and a test suite.
+
+## Develop
+
+```bash
+npm install
+npm test            # behavior (node --test)
+npm run test:types  # type-check src against the .d.ts (tsc --noEmit)
+```
+
+There's nothing to compile — consumers import your `src/index.js` directly via an
+import map or a bundler of their choosing.
+
+## Layout
+
+```
+{{APP_NAME}}/
+  package.json        name, exports, types, peer dep on @zoijs/core
+  tsconfig.json       strict, checkJs, noEmit (type-check only)
+  src/
+    index.js          your library (imports only @zoijs/core's public API)
+    index.d.ts        hand-written types (imports core types so they never drift)
+  tests/
+    index.test.js     node:test
+```
+
+## What's inside
+
+`src/index.js` ships one example helper — `counter(initial)` — to show the
+pattern: a factory that returns reader methods plus the raw reactive cell.
+**Replace it with your own.** Keep the package small and single-purpose; depend
+only on `@zoijs/core`.
+
+## Publishing
+
+```bash
+npm publish --access public
+```
+
+Add a `LICENSE`, fill in the `description`/`keywords` in `package.json`, and you're
+done. Learn more at [zoijs.dev](https://zoijs.dev).

package/templates/library/_gitignore

@@ -0,0 +1 @@
+node_modules

package/templates/library/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.1.0",
+  "description": "A small library built on @zoijs/core.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:types": "tsc --noEmit -p tsconfig.json"
+  },
+  "keywords": [
+    "zoijs"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@zoijs/core": "^1.2.0"
+  },
+  "devDependencies": {
+    "@zoijs/core": "^1.2.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/library/src/index.d.ts

@@ -0,0 +1,24 @@
+// Type definitions for {{APP_NAME}}.
+//
+// Authored in plain JavaScript; these declarations add editor autocomplete and
+// optional type-checking without requiring TypeScript. Core types are imported
+// from @zoijs/core so shapes never drift.
+
+import type { State } from "@zoijs/core";
+
+/** A reactive counter created by {@link counter}. */
+export interface Counter {
+  /** The current value (reactive inside a binding). */
+  value(): number;
+  /** Add `by` (default 1). */
+  increment(by?: number): void;
+  /** Subtract `by` (default 1). */
+  decrement(by?: number): void;
+  /** Reset to the initial value. */
+  reset(): void;
+  /** The underlying reactive cell — advanced / direct access. */
+  state: State<number>;
+}
+
+/** Create a reactive counter built on `@zoijs/core`. */
+export function counter(initial?: number): Counter;

package/templates/library/src/index.js

@@ -0,0 +1,30 @@
+// {{APP_NAME}} — a small library built on @zoijs/core.
+//
+// Optional Zoijs packages are tiny and import ONLY the core's public API — never
+// each other's internals. This example helper does the same; replace it with your
+// own. Run `npm test` (behavior) and `npm run test:types` (the .d.ts) as you go.
+
+import { createState } from "@zoijs/core";
+
+/**
+ * A reactive counter built on `createState`. A small, illustrative helper showing
+ * the shape an optional package takes: a factory that returns reader methods plus
+ * the raw reactive cell for advanced use.
+ *
+ * @param {number} [initial]
+ */
+export function counter(initial = 0) {
+  const state = createState(initial);
+  return {
+    /** The current value (reactive inside a binding). */
+    value: () => state.get(),
+    /** Add `by` (default 1). */
+    increment: (by = 1) => state.set(state.get() + by),
+    /** Subtract `by` (default 1). */
+    decrement: (by = 1) => state.set(state.get() - by),
+    /** Reset to the initial value. */
+    reset: () => state.set(initial),
+    /** The underlying reactive cell — advanced / direct access. */
+    state,
+  };
+}

package/templates/library/tests/index.test.js

@@ -0,0 +1,29 @@
+// Tests for {{APP_NAME}}. Pure logic — no DOM needed. Run with `npm test`.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { counter } from "../src/index.js";
+
+test("counts up and down", () => {
+  const c = counter(0);
+  assert.equal(c.value(), 0);
+  c.increment();
+  assert.equal(c.value(), 1);
+  c.increment(5);
+  assert.equal(c.value(), 6);
+  c.decrement(2);
+  assert.equal(c.value(), 4);
+});
+
+test("reset restores the initial value", () => {
+  const c = counter(10);
+  c.increment();
+  c.reset();
+  assert.equal(c.value(), 10);
+});
+
+test("exposes the raw reactive cell", () => {
+  const c = counter(3);
+  assert.equal(typeof c.state.get, "function");
+  assert.equal(c.state.peek(), 3);
+});

package/templates/library/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "checkJs": true,
+    "strict": true,
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM"],
+    "skipLibCheck": true,
+    "types": []
+  },
+  "include": ["src/**/*"]
+}

package/templates/minimal/README.md

@@ -0,0 +1,34 @@
+# {{APP_TITLE}}
+
+The smallest possible [Zoijs](https://zoijs.dev) app — **two files, no install, no
+build step.** A blank canvas.
+
+## Run it
+
+Any static file server works. The simplest:
+
+```bash
+npx serve . -l 7310
+```
+
+Then open <http://localhost:7310>.
+
+## What's here
+
+- `index.html` — loads `@zoijs/core` from a CDN (pinned to the `v1` major) and
+  mounts `app.js`.
+- `app.js` — a counter: state, markup, and one `mount` call.
+
+That's the whole project. Edit `app.js` and reload — there is nothing to build.
+
+## Growing up
+
+When you want local packages instead of the CDN, or a few components to organize,
+scaffold a fuller starter:
+
+```bash
+npm create zoijs@latest my-app                  # the app dashboard
+npm create zoijs@latest my-app --template basic # a basic counter
+```
+
+Learn more at [zoijs.dev](https://zoijs.dev).

package/templates/minimal/app.js

@@ -0,0 +1,18 @@
+import { html, mount, createState } from "@zoijs/core";
+
+// A complete Zoijs app in one file. No install, no build step.
+function App() {
+  const count = createState(0);
+
+  return html`
+    <main>
+      <h1>{{APP_TITLE}}</h1>
+      <p>Edit <code>app.js</code> and reload.</p>
+      <button onclick=${() => count.set(count.get() + 1)}>
+        Clicked ${() => count.get()} times
+      </button>
+    </main>
+  `;
+}
+
+mount(App, "#app");

package/templates/minimal/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_TITLE}}</title>
+    <!-- Zero install, zero build: load @zoijs/core straight from a CDN.
+         Pin the major version (@1) so your app never breaks unexpectedly. -->
+    <script type="importmap">
+      { "imports": { "@zoijs/core": "https://esm.sh/@zoijs/core@1" } }
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

package/templates/typescript/README.md

@@ -0,0 +1,57 @@
+# {{APP_TITLE}}
+
+A [Zoijs](https://zoijs.dev) app with **TypeScript-grade safety and no build step.**
+
+The source is plain JavaScript the browser runs as-is — but every file starts with
+`// @ts-check`, and together with the type definitions shipped in `@zoijs/core` you
+get full type-checking, autocomplete, and inline errors. There is **no compile
+step**: you never turn `.ts` into `.js`, because there's no `.ts` to begin with.
+
+## Develop
+
+```bash
+npm install
+npm run dev
+```
+
+```text
+  Zoijs dev server
+
+  - Local:  http://localhost:7310
+```
+
+Open the printed URL (it falls back to 7311–7313 if the port is busy).
+
+## Type-check
+
+```bash
+npm run typecheck
+```
+
+Runs `tsc --noEmit` against `src/**/*.js` using `@zoijs/core`'s types — no output
+files, just type errors if any. Wire it into CI or your editor.
+
+## How the typing works
+
+- `// @ts-check` at the top of a file turns on type-checking for that file.
+- `@typedef` / `@type` JSDoc comments add your own types (see `src/app.js`).
+- `@zoijs/core` ships `.d.ts`, so `createState`, `html`, `each`, etc. are fully
+  typed — e.g. `createState<Todo[]>(…)` gives you a typed list.
+
+Prefer authoring real `.ts`? You can, but it would require adding a `tsc` compile
+step — the one thing Zoijs avoids. This template keeps the no-build promise.
+
+## Project layout
+
+```
+{{APP_NAME}}/
+  index.html            import map + #app mount point
+  tsconfig.json         strict, checkJs, noEmit (type-check only)
+  dev-server.mjs        tiny zero-dependency static server (npm run dev)
+  src/
+    app.js              your app, typed with @ts-check
+    style.css           plain CSS
+```
+
+No bundler, no build step. Open the files and read them. Learn more at
+[zoijs.dev](https://zoijs.dev).

package/templates/typescript/_gitignore

@@ -0,0 +1 @@
+node_modules

package/templates/typescript/dev-server.mjs

@@ -0,0 +1,74 @@
+// dev-server.mjs — a tiny static file server for this Zoijs app.
+//
+// Zero dependencies (Node built-ins only), no build step, no bundler. It serves
+// the project files so the import map in index.html can load @zoijs/core from
+// node_modules. Tries port 7310, then 7311 / 7312 / 7313 if one is busy.
+//
+//   node dev-server.mjs      (this is what `npm run dev` runs)
+
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { extname, join, normalize } from "node:path";
+
+const PORTS = [7310, 7311, 7312, 7313];
+const ROOT = process.cwd();
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".png": "image/png",
+  ".woff2": "font/woff2",
+};
+
+const server = createServer(async (req, res) => {
+  let pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+  if (pathname === "/") pathname = "/index.html";
+
+  // Resolve inside ROOT and refuse anything that climbs out of it.
+  const filePath = join(ROOT, normalize(pathname));
+  if (!filePath.startsWith(ROOT)) {
+    res.writeHead(403).end("Forbidden");
+    return;
+  }
+  try {
+    const body = await readFile(filePath);
+    res.writeHead(200, { "Content-Type": TYPES[extname(filePath)] || "application/octet-stream" });
+    res.end(body);
+  } catch {
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" }).end("Not found");
+  }
+});
+
+function start(i = 0) {
+  if (i >= PORTS.length) {
+    console.error(`\nAll dev ports are busy (${PORTS.join(", ")}). Free one and try again.\n`);
+    process.exit(1);
+  }
+  // Paired once-listeners: each attempt removes its sibling so a failed bind
+  // can't leave a stale "listening" handler that prints the wrong port later.
+  const onError = (err) => {
+    server.removeListener("listening", onListening);
+    if (err.code === "EADDRINUSE") start(i + 1);
+    else {
+      console.error(err);
+      process.exit(1);
+    }
+  };
+  const onListening = () => {
+    server.removeListener("error", onError);
+    const lines = ["", "  Zoijs dev server", "", `  - Local:  http://localhost:${PORTS[i]}`];
+    if (i > 0) lines.push(`  (ports ${PORTS.slice(0, i).join(", ")} were busy)`);
+    lines.push("");
+    console.log(lines.join("\n"));
+  };
+  server.once("error", onError);
+  server.once("listening", onListening);
+  server.listen(PORTS[i]);
+}
+
+start();

package/templates/typescript/index.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_TITLE}}</title>
+    <link rel="stylesheet" href="./src/style.css" />
+    <!-- No build step: an import map points the @zoijs/core name at the package
+         installed in node_modules. `npm install` puts it there. -->
+    <script type="importmap">
+      {
+        "imports": {
+          "@zoijs/core": "./node_modules/@zoijs/core/src/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/app.js"></script>
+  </body>
+</html>

package/templates/typescript/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node dev-server.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zoijs/core": "^1.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/templates/typescript/src/app.js

@@ -0,0 +1,64 @@
+// @ts-check
+// TypeScript-grade safety with NO build step. This is plain JavaScript the
+// browser runs as-is — but `@ts-check` + the shipped `@zoijs/core` types give you
+// full type-checking and autocomplete. Run `npm run typecheck` (tsc --noEmit).
+import { html, mount, createState, each } from "@zoijs/core";
+
+/** @typedef {{ id: number; text: string; done: boolean }} Todo */
+
+function App() {
+  /** @type {import("@zoijs/core").State<Todo[]>} */
+  const todos = createState([
+    { id: 1, text: "Edit src/app.js", done: false },
+    { id: 2, text: "Run npm run typecheck", done: false },
+  ]);
+  const draft = createState("");
+  let nextId = 3;
+
+  /** @param {Event} e */
+  const add = (e) => {
+    e.preventDefault();
+    const text = draft.get().trim();
+    if (!text) return;
+    todos.set([...todos.get(), { id: nextId++, text, done: false }]);
+    draft.set("");
+  };
+
+  /** @param {number} id */
+  const toggle = (id) =>
+    todos.set(todos.get().map((t) => (t.id === id ? { ...t, done: !t.done } : t)));
+
+  return html`
+    <main>
+      <h1>{{APP_TITLE}}</h1>
+      <p>Typed with <code>@ts-check</code> — no build step. Run <code>npm run typecheck</code>.</p>
+
+      <form onsubmit=${add}>
+        <input
+          aria-label="New todo"
+          placeholder="Add a todo…"
+          value=${() => draft.get()}
+          oninput=${(/** @type {Event} */ e) =>
+            draft.set(/** @type {HTMLInputElement} */ (e.target).value)} />
+        <button type="submit">Add</button>
+      </form>
+
+      <ul>
+        ${each(
+          () => todos.get(),
+          (t) => t.id,
+          (t) => html`
+            <li>
+              <label>
+                <input type="checkbox" checked=${() => t.done} onchange=${() => toggle(t.id)} />
+                ${() => t.text}
+              </label>
+            </li>
+          `
+        )}
+      </ul>
+    </main>
+  `;
+}
+
+mount(App, "#app");

package/templates/typescript/src/style.css

@@ -0,0 +1,33 @@
+:root {
+  color-scheme: light dark;
+  font-family: system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+  display: grid;
+  place-items: center;
+  min-height: 100vh;
+}
+
+main {
+  text-align: center;
+  padding: 2rem;
+}
+
+h1 {
+  margin: 0 0 0.5rem;
+}
+
+button {
+  font: inherit;
+  padding: 0.6rem 1.2rem;
+  border: 1px solid currentColor;
+  border-radius: 8px;
+  background: transparent;
+  cursor: pointer;
+}
+
+button:hover {
+  background: rgba(127, 127, 127, 0.12);
+}

package/templates/typescript/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "checkJs": true,
+    "allowJs": true,
+    "strict": true,
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "types": []
+  },
+  "include": ["src/**/*.js"]
+}