create-zoijs 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `create-zoijs` are documented here.
+
+## 0.1.0 — 2026-06-25
+
+Initial release of the Zoijs starter CLI.
+
+- `npm create zoijs@latest my-app` — scaffold a new Zoijs app in one command.
+- Uses the provided folder name as the project name; derives `package.json`
+  `name` (lowercased) and a readable `index.html` `<title>` from it.
+- Two templates: `app` (default — a small task dashboard demonstrating
+  `html` / `mount` / `createState` / `computed` / `each` and parent⇄child
+  communication) and `basic` (a minimal counter). Select with `--template`.
+- Validates the project name (npm-safe) and refuses to overwrite a non-empty
+  directory.
+- Generated apps are plain HTML/CSS/JS with **no build step** and depend only on
+  `@zoijs/core` (served via an import map from `node_modules`).
+- Zero runtime dependencies; the CLI is a single small file.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zoijs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+<div align="center">
+
+# create-zoijs
+
+**Create a new [Zoijs](https://zoijs.dev) app with one command.** Plain HTML, CSS, and JavaScript — no build step.
+
+[![npm](https://img.shields.io/npm/v/create-zoijs.svg)](https://www.npmjs.com/package/create-zoijs)
+[![license](https://img.shields.io/npm/l/create-zoijs.svg)](LICENSE)
+
+</div>
+
+---
+
+## Usage
+
+```bash
+npm create zoijs@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Or with `npx`:
+
+```bash
+npx create-zoijs my-app
+```
+
+> **A note on the name.** npm maps `npm create zoijs` to the package
+> `create-zoijs` (that's npm's convention for `npm create <name>`), which is why
+> this package is `create-zoijs` rather than `@zoijs/create`.
+
+## Naming your app
+
+The folder name you pass becomes the project name:
+
+```bash
+npm create zoijs@latest task-manager
+```
+
+produces a `package.json` with `"name": "task-manager"` and an `index.html`
+with `<title>Task Manager</title>`. If you don't pass a name, the CLI asks for
+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 small task dashboard
+```
+
+- **`app`** (default) — a small task dashboard showing `html`, `mount`,
+  `createState`, `computed`, `each`, and parent⇄child component communication.
+- **`basic`** — a minimal counter, the smallest possible Zoijs app.
+
+## What it does
+
+- Copies a template, fills in the app name, and prints the next three commands.
+- Validates the name (npm-safe) and won't overwrite a non-empty folder.
+
+## What it does **not** do
+
+By design, to keep Zoijs simple: no build system, no bundler, no compiler, no
+JSX transform, no code generation, no plugin system, no template DSL, and no
+complex prompts. The generated app is plain files you can read.
+
+## You don't need this tool
+
+Zoijs works without the CLI — it's only a convenience. You can create an app by
+hand with an import map and a `<script type="module">`, or with
+`npm install @zoijs/core`. See the [Start guide](https://zoijs.dev/start).
+
+## License
+
+[MIT](LICENSE) © Zoijs contributors

package/bin/create-zoijs.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// create-zoijs — a tiny scaffolder for new Zoijs apps. No build step, no
+// dependencies. It copies a template, fills in the app name, and prints the
+// three commands to get going. That's the whole tool — read it top to bottom.
+//
+// Usage:
+//   npm create zoijs@latest my-app          (npm maps this to create-zoijs)
+//   npx create-zoijs my-app --template basic
+//
+// The pure functions below are exported so they can be unit-tested; main() only
+// runs when this file is executed directly (not when imported).
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const TEMPLATES = ["basic", "app"];
+export const DEFAULT_TEMPLATE = "app";
+const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+
+// ---- argument parsing --------------------------------------------------------
+
+/** Parse argv into { name, template }. The first non-flag arg is the app name. */
+export function parseArgs(argv) {
+  let name;
+  let template = DEFAULT_TEMPLATE;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--template" || a === "-t") template = argv[++i];
+    else if (a.startsWith("--template=")) template = a.slice("--template=".length);
+    else if (!a.startsWith("-") && name === undefined) name = a;
+  }
+  return { name, template };
+}
+
+// ---- naming ------------------------------------------------------------------
+
+/** A readable Title Case form of a project name: "task-manager" → "Task Manager". */
+export function toTitle(name) {
+  return String(name)
+    .replace(/[-_]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+/** Validate a project name. Returns { valid, problems[] }. Keeps it npm-safe. */
+export function validateName(name) {
+  const problems = [];
+  if (!name || !name.trim()) {
+    problems.push("Project name cannot be empty.");
+    return { valid: false, problems };
+  }
+  if (name.trim() !== name) problems.push("Project name cannot have leading or trailing spaces.");
+  if (name.length > 214) problems.push("Project name must be 214 characters or fewer.");
+  if (/^[._]/.test(name)) problems.push("Project name cannot start with a dot or underscore.");
+  if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+    problems.push("Project name may only contain letters, numbers, dashes, dots, and underscores.");
+  }
+  return { valid: problems.length === 0, problems };
+}
+
+// ---- filesystem --------------------------------------------------------------
+
+/** Throw if the target directory exists and already has files in it. */
+export function ensureTargetAvailable(targetDir) {
+  if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+    throw new Error(`Directory "${path.basename(targetDir)}" already exists and is not empty.`);
+  }
+}
+
+const TEXT_EXT = new Set([".js", ".html", ".css", ".json", ".md", ".txt", ".svg"]);
+const isText = (file) => file === "_gitignore" || TEXT_EXT.has(path.extname(file));
+
+function applyTokens(content, tokens) {
+  return content.replaceAll("{{APP_NAME}}", tokens.APP_NAME).replaceAll("{{APP_TITLE}}", tokens.APP_TITLE);
+}
+
+function copyDir(srcDir, destDir, tokens, written) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    // npm strips a literal ".gitignore" from published packages, so templates
+    // ship it as "_gitignore" and we rename it on copy.
+    const destName = entry.name === "_gitignore" ? ".gitignore" : entry.name;
+    const destPath = path.join(destDir, destName);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, tokens, written);
+    } else if (isText(entry.name)) {
+      fs.writeFileSync(destPath, applyTokens(fs.readFileSync(srcPath, "utf8"), tokens));
+      written.push(destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      written.push(destPath);
+    }
+  }
+}
+
+/**
+ * Copy a template into targetDir, substituting the app name. Pure FS work — the
+ * caller decides the name/template/dirs, which makes this easy to test.
+ */
+export function scaffold({ name, template = DEFAULT_TEMPLATE, targetDir, templatesDir = TEMPLATES_DIR }) {
+  const tplDir = path.join(templatesDir, template);
+  if (!TEMPLATES.includes(template) || !fs.existsSync(tplDir)) {
+    throw new Error(`Unknown template "${template}". Available templates: ${TEMPLATES.join(", ")}.`);
+  }
+  const tokens = { APP_NAME: name.toLowerCase(), APP_TITLE: toTitle(name) };
+  const written = [];
+  copyDir(tplDir, targetDir, tokens, written);
+  return { written, tokens };
+}
+
+// ---- the CLI -----------------------------------------------------------------
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); }));
+}
+
+const fail = (message) => { console.error(`\n✖ ${message}\n`); process.exit(1); };
+
+async function main(argv) {
+  const { name: argName, template } = parseArgs(argv);
+
+  let name = argName;
+  if (!name) name = await ask("Project name: ");
+
+  const { valid, problems } = validateName(name);
+  if (!valid) fail(problems.join("\n  "));
+
+  const targetDir = path.resolve(process.cwd(), name);
+  try {
+    ensureTargetAvailable(targetDir);
+  } catch (err) {
+    fail(err.message);
+  }
+
+  let result;
+  try {
+    result = scaffold({ name, template, targetDir });
+  } catch (err) {
+    fail(err.message);
+  }
+
+  console.log(`\n✔ Created ${name} (${template} template) — ${result.written.length} files\n`);
+  console.log("Next steps:");
+  console.log(`  cd ${name}`);
+  console.log("  npm install");
+  console.log("  npm run dev\n");
+  console.log("Zoijs works without this tool, too — it's only a convenience. See https://zoijs.dev/start\n");
+}
+
+// Run only when executed directly (resolve symlinks so the npm bin shim works).
+function invokedDirectly() {
+  try {
+    return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+  }
+}
+
+if (invokedDirectly()) main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-zoijs",
+  "version": "0.1.0",
+  "description": "Create a new Zoijs app with one command. Plain HTML, CSS, and JavaScript — no build step.",
+  "type": "module",
+  "bin": {
+    "create-zoijs": "bin/create-zoijs.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Zoijs contributors (https://zoijs.dev)",
+  "license": "MIT",
+  "homepage": "https://zoijs.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zoijs/zoijs.git",
+    "directory": "create"
+  },
+  "bugs": {
+    "url": "https://github.com/Zoijs/zoijs/issues"
+  },
+  "keywords": [
+    "zoijs",
+    "create",
+    "create-zoijs",
+    "scaffold",
+    "starter",
+    "cli",
+    "no-build",
+    "no-jsx"
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/templates/app/README.md

@@ -0,0 +1,38 @@
+# {{APP_TITLE}}
+
+A small task dashboard built with [Zoijs](https://zoijs.dev) — plain HTML, CSS,
+and JavaScript. **No build step.**
+
+## Develop
+
+```bash
+npm install
+npm run dev
+```
+
+Then open the printed URL.
+
+## Project layout
+
+```
+{{APP_NAME}}/
+  index.html              import map + #app mount point
+  src/
+    app.js                owns the task list; renders the page
+    style.css             plain CSS
+    components/
+      Header.js           parent → child: receives title + count
+      TaskItem.js         child → parent: reports toggle/delete via callbacks
+```
+
+## What it shows
+
+- **`createState`** — the task list and the input draft.
+- **`computed`** — the "tasks left" count, derived from the list.
+- **`each`** — keyed rendering of the task list.
+- **Parent → child** — `App` passes data down to `Header` as arguments.
+- **Child → parent** — `TaskItem` reports events up through callbacks; `App`
+  owns the state and performs the changes.
+
+No bundler, no build step. Open the files and read them. Learn more at
+[zoijs.dev](https://zoijs.dev).

package/templates/app/_gitignore

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

package/templates/app/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/app/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "npx serve ."
+  },
+  "dependencies": {
+    "@zoijs/core": "^1.1.0"
+  }
+}

package/templates/app/src/app.js

@@ -0,0 +1,55 @@
+import { html, mount, createState, computed, each } from "@zoijs/core";
+import { Header } from "./components/Header.js";
+import { TaskItem } from "./components/TaskItem.js";
+
+// The App owns the task list. Children receive data as arguments (parent → child)
+// and report events back through callbacks (child → parent). No store, no context.
+function App() {
+  const tasks = createState([
+    { id: 1, text: "Read the Zoijs docs", done: true },
+    { id: 2, text: "Build something small", done: false },
+    { id: 3, text: "Share it", done: false },
+  ]);
+  let nextId = 4;
+
+  // computed: derived, cached, reactive.
+  const remaining = computed(() => tasks.get().filter((t) => !t.done).length);
+
+  const addTask = (text) => tasks.set([...tasks.get(), { id: nextId++, text, done: false }]);
+  const toggle = (id) => tasks.set(tasks.get().map((t) => (t.id === id ? { ...t, done: !t.done } : t)));
+  const remove = (id) => tasks.set(tasks.get().filter((t) => t.id !== id));
+
+  const draft = createState("");
+  const onSubmit = (e) => {
+    e.preventDefault();
+    const text = draft.get().trim();
+    if (!text) return;
+    addTask(text);
+    draft.set("");
+  };
+
+  return html`
+    <main>
+      ${/* parent → child: pass plain data (title) and a reader (remaining) down */ ""}
+      ${Header({ title: "{{APP_TITLE}}", remaining: () => remaining.get() })}
+
+      <form onsubmit=${onSubmit}>
+        <input
+          placeholder="Add a task…"
+          value=${() => draft.get()}
+          oninput=${(e) => draft.set(e.target.value)} />
+        <button type="submit">Add</button>
+      </form>
+
+      <ul class="tasks">
+        ${each(
+          () => tasks.get(),
+          (t) => t.id,
+          (t) => TaskItem({ task: t, onToggle: toggle, onDelete: remove })
+        )}
+      </ul>
+    </main>
+  `;
+}
+
+mount(App, "#app");

package/templates/app/src/components/Header.js

@@ -0,0 +1,14 @@
+import { html } from "@zoijs/core";
+
+// Parent → child communication: Header receives plain data (`title`) and a
+// reader function (`remaining`) as arguments. It owns no state of its own.
+export function Header({ title, remaining }) {
+  return html`
+    <header>
+      <h1>${title}</h1>
+      <p class="count">
+        ${() => remaining()} task${() => (remaining() === 1 ? "" : "s")} left
+      </p>
+    </header>
+  `;
+}

package/templates/app/src/components/TaskItem.js

@@ -0,0 +1,18 @@
+import { html } from "@zoijs/core";
+
+// Child → parent communication: TaskItem owns no state. It reports toggle and
+// delete events upward by calling the callbacks the parent passed in.
+export function TaskItem({ task, onToggle, onDelete }) {
+  return html`
+    <li class=${() => (task.done ? "done" : "")}>
+      <label>
+        <input
+          type="checkbox"
+          checked=${() => task.done}
+          onchange=${() => onToggle(task.id)} />
+        <span>${() => task.text}</span>
+      </label>
+      <button class="delete" title="Delete" onclick=${() => onDelete(task.id)}>✕</button>
+    </li>
+  `;
+}

package/templates/app/src/style.css

@@ -0,0 +1,91 @@
+:root {
+  color-scheme: light dark;
+  font-family: system-ui, sans-serif;
+  line-height: 1.5;
+}
+
+body {
+  margin: 0;
+  display: grid;
+  place-items: start center;
+  min-height: 100vh;
+}
+
+main {
+  width: min(34rem, 92vw);
+  padding: 2rem 1rem;
+}
+
+header h1 {
+  margin: 0 0 0.25rem;
+}
+
+.count {
+  margin: 0 0 1rem;
+  color: gray;
+}
+
+form {
+  display: flex;
+  gap: 0.5rem;
+  margin-bottom: 1rem;
+}
+
+input[type="text"],
+form input {
+  flex: 1;
+  font: inherit;
+  padding: 0.5rem 0.7rem;
+  border: 1px solid rgba(127, 127, 127, 0.5);
+  border-radius: 8px;
+  background: transparent;
+}
+
+button {
+  font: inherit;
+  padding: 0.5rem 0.9rem;
+  border: 1px solid currentColor;
+  border-radius: 8px;
+  background: transparent;
+  cursor: pointer;
+}
+
+.tasks {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: 0.4rem;
+}
+
+.tasks li {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  padding: 0.5rem 0.7rem;
+  border: 1px solid rgba(127, 127, 127, 0.25);
+  border-radius: 8px;
+}
+
+.tasks li.done span {
+  text-decoration: line-through;
+  opacity: 0.6;
+}
+
+.tasks label {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  cursor: pointer;
+}
+
+.delete {
+  border: none;
+  padding: 0.2rem 0.5rem;
+  opacity: 0.6;
+}
+
+.delete:hover {
+  opacity: 1;
+}

package/templates/basic/README.md

@@ -0,0 +1,23 @@
+# {{APP_TITLE}}
+
+A [Zoijs](https://zoijs.dev) app — plain HTML, CSS, and JavaScript. **No build step.**
+
+## Develop
+
+```bash
+npm install
+npm run dev
+```
+
+Then open the printed URL.
+
+## How it works
+
+- **`index.html`** — an import map points `@zoijs/core` at `node_modules`, then loads `src/app.js`.
+- **`src/app.js`** — your app: `createState` for state, `html` for markup, `mount` to render.
+- **`src/style.css`** — plain CSS.
+
+There's no bundler and no build step. Open the files and read them — that's the
+whole app. Edit `src/app.js` and reload.
+
+Learn more at [zoijs.dev](https://zoijs.dev).

package/templates/basic/_gitignore

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

package/templates/basic/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/basic/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "npx serve ."
+  },
+  "dependencies": {
+    "@zoijs/core": "^1.1.0"
+  }
+}

package/templates/basic/src/app.js

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

package/templates/basic/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);
+}