create-hum 0.0.0-stage → 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const TEMPLATE_DIR = fileURLToPath(new URL("../templates/basic", import.meta.url));
+/**
+ * Template files whose name is only valid once they land in the new project
+ * (a `_package.json` inside this package would confuse tooling).
+ */
+const RENAMES = {
+    "_gitignore": ".gitignore",
+    "_package.json": "package.json",
+    "_README.md": "README.md",
+};
+const USAGE = `create-hum <project-directory>
+
+Scaffolds a new Hum project into <project-directory>.
+
+  pnpm dlx create-hum my-app
+  npm create hum@latest my-app
+`;
+async function walk(dir) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...await walk(full));
+        }
+        else {
+            out.push(full);
+        }
+    }
+    return out;
+}
+async function copyTemplate(target, name) {
+    for (const file of await walk(TEMPLATE_DIR)) {
+        const rel = file
+            .slice(TEMPLATE_DIR.length)
+            .replace(/\\/g, "/")
+            .replace(/^\//, "");
+        const parts = rel.split("/");
+        const fileName = parts[parts.length - 1];
+        parts[parts.length - 1] = RENAMES[fileName] ?? fileName;
+        const dest = join(target, ...parts);
+        await mkdir(join(dest, ".."), { recursive: true });
+        // `replaceAll` is a no-op for the files that do not use the placeholder,
+        // so every file can be treated the same way.
+        const raw = await readFile(file, "utf8");
+        await writeFile(dest, raw.replaceAll("{{name}}", name), "utf8");
+    }
+}
+async function isEmptyDir(dir) {
+    if (!existsSync(dir))
+        return true;
+    return (await readdir(dir)).length === 0;
+}
+const arg = process.argv[2];
+if (arg === undefined || arg === "--help" || arg === "-h") {
+    console.log(USAGE);
+    process.exit(arg === undefined ? 1 : 0);
+}
+const target = resolve(process.cwd(), arg);
+if (!await isEmptyDir(target)) {
+    console.error(`create-hum: "${arg}" already exists and is not empty.`);
+    process.exit(1);
+}
+const name = basename(target);
+await mkdir(target, { recursive: true });
+await copyTemplate(target, name);
+console.log(`\nCreated "${name}" in ${target}\n`);
+console.log("Next steps:");
+console.log(`  cd ${arg}`);
+console.log("  npm install");
+console.log("  npm run dev\n");
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "create-hum",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Scaffolds a new Hum project",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oaly2000/hum.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "create-hum": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.6.5"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/templates/basic/_README.md

@@ -0,0 +1,62 @@
+# {{name}}
+
+A [Hum](https://github.com/) app: static HTML first, islands for interaction.
+
+```bash
+npm install
+npm run dev      # Custom Hono server with Vite SSR + HMR middleware
+npm run build    # client + server bundles into _hum/
+npm start        # run the built server
+```
+
+The production server bundle includes its npm dependencies, so the runtime
+deployment does not need the project's `node_modules`. The generated `_hum/`
+directory can move or even be renamed — it locates itself next to the server
+bundle — as long as its internal structure is kept and `server/server.js` is the
+entry point. Client assets stay reachable under `/_hum/`, the URL recorded in
+the build manifest. Node.js 20 or newer is still required.
+
+## Hono server
+
+`server.ts` exports a Hono app. Configure middleware and API routes with the
+normal Hono API; Hum mounts its file-based routes directly onto that app and
+handles unmatched requests with its `_404` page.
+Hum page errors use `_error`; API errors keep using the app's Hono `onError`.
+Vite owns the development listener, preserving SSR and HMR. In production the
+generated entry starts the exported app. The example includes a `/api/health`
+route.
+
+## Layout
+
+```
+routes/
+  _app.tsx      document shell (html/head/body)
+  _404.tsx      not found page
+  index.tsx     /
+  seo.tsx       /seo
+  blog/[id].tsx /blog/:id
+islands/
+  Counter.tsx   interactive component
+client/
+  main.ts       client entry; imports global CSS
+  style.css     Tailwind CSS entry point
+server.ts       Hono app with middleware and API routes
+```
+
+## Tailwind CSS
+
+The basic template includes Tailwind CSS v4. Global styles are imported from
+`client/main.ts`; add or edit utility classes in your routes and islands.
+
+## Head
+
+Route files export `head` — either a JSX fragment or a function of the route
+props. `_app.tsx` provides the defaults, pages override them by tag.
+
+```tsx
+export const head = <title>Home</title>;
+
+export function head({ params }: RouteProps) {
+  return <title>Blog {params.id}</title>;
+}
+```

package/templates/basic/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+_hum
+.hum
+*.log

package/templates/basic/_package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "start": "node _hum/server/server.js"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.4",
+    "@humjs/core": "^0.0.1",
+    "@humjs/vite-plugin": "^0.0.1",
+    "@preact/signals": "^2.11.3",
+    "hono": "^4.13.13",
+    "preact": "^11.0.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^26.6.5",
+    "tailwindcss": "^4.3.3",
+    "vite": "^8.3.4"
+  }
+}

package/templates/basic/client/main.ts

@@ -0,0 +1,3 @@
+import "./style.css";
+
+export {};

package/templates/basic/client/style.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/basic/client/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/basic/islands/Counter.tsx

@@ -0,0 +1,14 @@
+import { useSignal } from "@preact/signals";
+
+/** Interactive island: everything around it stays static HTML. */
+export default function Counter({ start = 0 }: { start?: number }) {
+  const count = useSignal(start);
+
+  return (
+    <div class="counter">
+      <button type="button" onClick={() => count.value--}>-</button>
+      <output>{count.value}</output>
+      <button type="button" onClick={() => count.value++}>+</button>
+    </div>
+  );
+}

package/templates/basic/routes/_404.tsx

@@ -0,0 +1,3 @@
+export default function NotFound() {
+  return <h1>404 — not found</h1>;
+}

package/templates/basic/routes/_app.tsx

@@ -0,0 +1,22 @@
+import type { ComponentChildren } from "preact";
+import { define } from "@humjs/core";
+
+/** Application wide head tags. Pages override them by tag. */
+export const head = define.head(
+  <>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{ name }}</title>
+  </>,
+);
+
+/** Document shell. Hum injects the merged head tags into `<head>`. */
+export default function App({ children }: { children?: ComponentChildren }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/basic/routes/blog/[id].tsx

@@ -0,0 +1,19 @@
+import { define, type Handlers, page, type RouteProps } from "@humjs/core";
+
+interface BlogPageData {
+  post: { id: string; title: string };
+}
+
+export const head = define.head(({ params }) => <title>Blog {params.id}
+</title>);
+
+export const handlers: Handlers = {
+  GET: (c) => {
+    const id = c.req.param("id");
+    return page({ post: { id, title: `Post ${id}` } });
+  },
+};
+
+export default define.page<BlogPageData>(({ data }) => (
+  <h1>Blog post {data.post.title}</h1>
+));

package/templates/basic/routes/index.tsx

@@ -0,0 +1,14 @@
+import { define } from "@humjs/core";
+import Counter from "../islands/Counter.js";
+
+export const head = define.head(<title>{{ name }}</title>);
+
+export default function Home() {
+  return (
+    <section class="mx-auto max-w-3xl space-y-6 p-8">
+      <h1 class="text-3xl font-bold">{{ name }}</h1>
+      {/* Only this island ships JavaScript; the rest stays static HTML. */}
+      <Counter start={0} />
+    </section>
+  );
+}

package/templates/basic/routes/partials.tsx

@@ -0,0 +1,36 @@
+import { define, Partial, type RouteProps } from "@humjs/core";
+
+const TOPICS: Record<string, string> = {
+  "": "Pick a topic from the list.",
+  a: "You are reading topic A.",
+  b: "You are reading topic B.",
+  c: "You are reading topic C.",
+};
+
+export const head = define.head(({ url }) => (
+  <title>Partials — {url.searchParams.get("topic") || "home"}</title>
+));
+
+/**
+ * `f-client-nav` on the wrapper makes every link/submit inside it a client side
+ * navigation: the browser does not do a full reload, only the `<Partial>` regions
+ * of the target page are fetched and swapped in. The target page reuses the same
+ * partial `name`, so the region updates without touching the rest of the layout.
+ */
+export default function PartialsPage(props: RouteProps) {
+  const topic = props.url.searchParams.get("topic") ?? "";
+  return (
+    <div f-client-nav>
+      <p>Client side navigation swaps only the partial region below.</p>
+      <nav>
+        <a href="/partials">Home</a>
+        <a href="/partials?topic=a">A</a>
+        <a href="/partials?topic=b">B</a>
+        <a href="/partials?topic=c">C</a>
+      </nav>
+      <Partial name="content">
+        <p>{TOPICS[topic] ?? "Unknown topic."}</p>
+      </Partial>
+    </div>
+  );
+}

package/templates/basic/routes/seo.tsx

@@ -0,0 +1,14 @@
+import { define } from "@humjs/core";
+
+/** `head` as a plain JSX fragment: no props needed. */
+export const head = define.head(
+  <>
+    <title>SEO</title>
+    <meta name="description" content="head exported as a JSX fragment" />
+    <link rel="canonical" href="/seo" />
+  </>,
+);
+
+export default function Seo() {
+  return <h1>SEO</h1>;
+}

package/templates/basic/server.ts

@@ -0,0 +1,16 @@
+import { Hono } from "hono";
+
+const app = new Hono();
+
+configure(app);
+
+export default app;
+
+function configure(app: Hono) {
+  app.use("*", async (c, next) => {
+    c.header("x-powered-by", "Hum + Hono");
+    await next();
+  });
+
+  app.get("/api/health", (c) => c.json({ status: "ok" }));
+}

package/templates/basic/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}

package/templates/basic/vite.config.ts

@@ -0,0 +1,7 @@
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "vite";
+import { hum } from "@humjs/vite-plugin";
+
+export default defineConfig({
+  plugins: [hum(), tailwindcss()],
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.