create-blokd 0.1.0-beta.2

package/README.md

@@ -0,0 +1,454 @@
+# create-blokd
+
+Create a new Blokd project from the command line.
+
+Blokd is a tiny Hono-native meta-framework for HTML-first applications, with Solid-familiar signals, Web APIs, SSR, file-based routing, and resumable islands.
+
+## Usage
+
+Create a new project with pnpm:
+
+~~~sh
+pnpm create blokd my-app
+~~~
+
+Or use the explicit beta tag:
+
+~~~sh
+pnpm create blokd@beta my-app
+~~~
+
+With npm:
+
+~~~sh
+npm create blokd@beta my-app
+~~~
+
+With yarn:
+
+~~~sh
+yarn create blokd my-app
+~~~
+
+With bun:
+
+~~~sh
+bun create blokd my-app
+~~~
+
+Then start the app:
+
+~~~sh
+cd my-app
+pnpm install
+pnpm dev
+~~~
+
+Open the local URL printed by Vite.
+
+## Options
+
+~~~txt
+Usage:
+  npm create blokd@beta my-app
+  pnpm create blokd my-app
+  yarn create blokd my-app
+  bun create blokd my-app
+
+Options:
+  --template <name>       Template to use. Default: minimal
+  --install               Install dependencies after creating the project
+  --no-install            Do not install dependencies
+  --pm <name>             Package manager: pnpm, npm, yarn, bun
+  -h, --help              Show help
+~~~
+
+## Examples
+
+Create a minimal project:
+
+~~~sh
+pnpm create blokd my-app
+~~~
+
+Create a minimal project and install dependencies:
+
+~~~sh
+pnpm create blokd my-app --install
+~~~
+
+Create a project with an explicit template:
+
+~~~sh
+pnpm create blokd my-app --template minimal
+~~~
+
+Create a project and force npm as the package manager:
+
+~~~sh
+pnpm create blokd my-app --pm npm
+~~~
+
+Create a project without installing dependencies:
+
+~~~sh
+pnpm create blokd my-app --no-install
+~~~
+
+## Templates
+
+### minimal
+
+The default template is `minimal`.
+
+It includes:
+
+- Hono server entry
+- Blokd Vite plugin
+- file-based routes
+- root layout
+- custom 404 page
+- custom error page
+- client entry for resumable islands
+- one interactive signal example
+- one resumable island example
+- one static route
+
+Project structure:
+
+~~~txt
+my-app/
+  package.json
+  tsconfig.json
+  vite.config.ts
+  index.html
+  src/
+    server.ts
+    entry-client.ts
+    resumables/
+      demo.ts
+    routes/
+      _layout.tsx
+      _404.tsx
+      _error.tsx
+      index.tsx
+      about.tsx
+~~~
+
+## Generated project commands
+
+Inside the generated project:
+
+~~~sh
+pnpm dev
+~~~
+
+Starts the development server.
+
+~~~sh
+pnpm build
+~~~
+
+Builds the project.
+
+~~~sh
+pnpm typecheck
+~~~
+
+Runs TypeScript without emitting files.
+
+## Generated project dependencies
+
+The generated minimal starter includes:
+
+~~~json
+{
+  "dependencies": {
+    "blokd": "beta",
+    "hono": ">=4.5 <5"
+  },
+  "devDependencies": {
+    "@types/node": ">=20 <23",
+    "typescript": ">=5.5 <6",
+    "vite": ">=5 <9"
+  }
+}
+~~~
+
+`blokd` is installed from the beta dist-tag because Blokd is currently in public beta.
+
+`hono` is included as an application dependency because Blokd apps use Hono directly for APIs, middleware, routing, cookies, headers, and deployment-specific server behavior.
+
+`vite`, `typescript`, and `@types/node` are development dependencies because the starter uses Vite and TypeScript.
+
+## Beta status
+
+Blokd is currently in public beta.
+
+The beta is intended for:
+
+- experimentation
+- early adopters
+- small websites
+- documentation sites
+- local business websites
+- simple dashboards
+- Hono-backed SSR applications
+- form-driven applications
+- progressively enhanced web apps
+
+The beta is not yet intended for:
+
+- large production migrations
+- highly regulated applications
+- applications requiring long-term API stability
+- complex full-app client routing
+- deep ecosystem integrations
+
+APIs may change before a stable `1.0.0` release.
+
+## What Blokd is optimized for
+
+Blokd is optimized for HTML-first applications.
+
+That means:
+
+- server-rendered pages by default
+- Web APIs instead of framework-specific request abstractions
+- Hono for server composition
+- file-based routing for pages
+- native forms for mutations
+- small client JavaScript payloads
+- resumable islands for focused interactivity
+- no React dependency
+- no virtual DOM dependency
+
+## What Blokd is not
+
+Blokd is not a full replacement for every app framework.
+
+It is not:
+
+- a React framework
+- a full Qwik-compatible resumability system
+- a full client-side app router
+- a batteries-included CMS framework
+- a mature ecosystem equivalent to Next.js, Astro, Remix, or SvelteKit
+
+The goal is a small, explicit, Web Platform-oriented framework.
+
+## Minimal starter walkthrough
+
+The generated app has two public pages:
+
+~~~txt
+src/routes/index.tsx  -> /
+src/routes/about.tsx  -> /about
+~~~
+
+It also has three special route files:
+
+~~~txt
+src/routes/_layout.tsx  -> root document layout
+src/routes/_404.tsx     -> custom not found page
+src/routes/_error.tsx   -> custom error page
+~~~
+
+The root page demonstrates:
+
+- `signal`
+- an inline event handler
+- `Island`
+- `resumable`
+
+The about page demonstrates a static server-rendered page with no client interactivity.
+
+## Hono server entry
+
+The generated app uses Hono as the server foundation:
+
+~~~ts
+import { Hono } from "hono";
+import { createPages } from "blokd/hono";
+import routes from "virtual:blokd/routes";
+
+const app = new Hono();
+
+app.get("/api/health", c => {
+  return c.json({ ok: true });
+});
+
+app.route(
+  "/",
+  createPages({
+    routes,
+    entryClient: "/src/entry-client.ts"
+  })
+);
+
+export default app;
+~~~
+
+Use Hono directly for:
+
+- API routes
+- middleware
+- authentication
+- sessions
+- cookies
+- headers
+- webhooks
+- deployment adapters
+
+## Vite config
+
+The generated app uses the Blokd Vite plugin:
+
+~~~ts
+import { defineConfig } from "vite";
+import { blokd } from "blokd/vite";
+
+export default defineConfig({
+  plugins: [
+    blokd({
+      routesDir: "src/routes",
+      clientEntry: "/src/entry-client.ts"
+    })
+  ]
+});
+~~~
+
+The Vite plugin is responsible for:
+
+- route manifest generation
+- JSX transform
+- static route analysis
+- virtual route module support
+
+## Resumable islands
+
+The starter includes a minimal resumable island:
+
+~~~tsx
+<Island name="demo-island" state={{ message: "Hello from Blokd" }}>
+  <button
+    type="button"
+    data-output
+    onClick={resumable("/src/resumables/demo.ts#sayHello")}
+  >
+    Run resumable handler
+  </button>
+</Island>
+~~~
+
+The corresponding handler is:
+
+~~~ts
+export function sayHello(event: Event, ctx: any) {
+  const button = event.currentTarget as HTMLButtonElement;
+  button.textContent = ctx.state.message;
+}
+~~~
+
+Blokd resumability is island-scoped. It is not full application graph serialization.
+
+## Static route behavior
+
+Blokd can analyze routes to determine whether they need the client entry.
+
+A route with event handlers, signals, effects, `Island`, or `resumable` needs client behavior.
+
+A route without client markers can be server-rendered without framework client JavaScript.
+
+This keeps simple pages small by default.
+
+## Package manager behavior
+
+`create-blokd` detects the package manager from the current npm user agent when possible.
+
+Fallback package manager:
+
+~~~txt
+pnpm
+~~~
+
+You can override this with:
+
+~~~sh
+pnpm create blokd my-app --pm npm
+pnpm create blokd my-app --pm pnpm
+pnpm create blokd my-app --pm yarn
+pnpm create blokd my-app --pm bun
+~~~
+
+## Installing automatically
+
+By default, the CLI creates the project and prints next steps.
+
+To install dependencies immediately:
+
+~~~sh
+pnpm create blokd my-app --install
+~~~
+
+To explicitly skip installation:
+
+~~~sh
+pnpm create blokd my-app --no-install
+~~~
+
+## Directory safety
+
+`create-blokd` refuses to write into a non-empty target directory.
+
+This prevents accidentally overwriting an existing project.
+
+Valid project names may contain:
+
+- letters
+- numbers
+- dots
+- dashes
+- underscores
+
+## Publishing
+
+This package is published as:
+
+~~~txt
+create-blokd
+~~~
+
+The command:
+
+~~~sh
+npm create blokd
+~~~
+
+resolves to the `create-blokd` package.
+
+For beta releases, publish with:
+
+~~~sh
+npm publish --tag beta
+~~~
+
+Do not publish beta releases without the beta dist-tag.
+
+## Related packages
+
+Main framework package:
+
+~~~sh
+pnpm add blokd@beta hono
+~~~
+
+Create package:
+
+~~~sh
+pnpm create blokd@beta my-app
+~~~
+
+## License
+
+MIT

package/bin/create-blokd.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const packageRoot = resolve(__dirname, "..");
+const templatesRoot = join(packageRoot, "templates");
+
+const args = process.argv.slice(2);
+
+const help = `
+create-blokd
+
+Usage:
+  npm create blokd@beta my-app
+  pnpm create blokd my-app
+  yarn create blokd my-app
+
+Options:
+  --template <name>       Template to use. Default: minimal
+  --install               Install dependencies after creating the project
+  --no-install            Do not install dependencies
+  --pm <name>             Package manager: pnpm, npm, yarn, bun
+  -h, --help              Show help
+
+Examples:
+  pnpm create blokd my-app
+  pnpm create blokd my-app --template minimal
+  pnpm create blokd my-app --install
+`;
+
+function main() {
+  if (args.includes("-h") || args.includes("--help")) {
+    console.log(help.trim());
+    process.exit(0);
+  }
+
+  const parsed = parseArgs(args);
+
+  if (!parsed.name) {
+    console.error("Missing project name.");
+    console.error("");
+    console.error("Usage:");
+    console.error("  pnpm create blokd my-app");
+    process.exit(1);
+  }
+
+  const templateName = parsed.template ?? "minimal";
+  const templateDir = join(templatesRoot, templateName);
+
+  if (!existsSync(templateDir)) {
+    console.error(`Unknown template: ${templateName}`);
+    console.error("");
+    console.error("Available templates:");
+    for (const name of listTemplates()) {
+      console.error(`  - ${name}`);
+    }
+    process.exit(1);
+  }
+
+  const targetDir = resolve(process.cwd(), parsed.name);
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+    console.error(`Target directory is not empty: ${targetDir}`);
+    process.exit(1);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  copyDirectory(templateDir, targetDir);
+
+  updatePackageName(join(targetDir, "package.json"), parsed.name);
+
+  console.log("");
+  console.log(`Created ${parsed.name} with the ${templateName} template.`);
+  console.log("");
+
+  const packageManager = parsed.pm || detectPackageManager();
+
+  if (parsed.install) {
+    console.log(`Installing dependencies with ${packageManager}...`);
+    const result = spawnSync(packageManager, ["install"], {
+      cwd: targetDir,
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+
+    if (result.status !== 0) {
+      console.error("");
+      console.error("Dependency installation failed.");
+      console.error(`Run manually: cd ${parsed.name} && ${packageManager} install`);
+      process.exit(result.status ?? 1);
+    }
+
+    console.log("");
+    console.log("Done.");
+    console.log("");
+    console.log(`Next steps:`);
+    console.log(`  cd ${parsed.name}`);
+    console.log(`  ${packageManager} dev`);
+    return;
+  }
+
+  console.log("Next steps:");
+  console.log(`  cd ${parsed.name}`);
+  console.log(`  ${packageManager} install`);
+  console.log(`  ${packageManager} dev`);
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    name: "",
+    template: "minimal",
+    install: false,
+    pm: undefined
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === "--template") {
+      parsed.template = argv[++i];
+      continue;
+    }
+
+    if (arg.startsWith("--template=")) {
+      parsed.template = arg.slice("--template=".length);
+      continue;
+    }
+
+    if (arg === "--install") {
+      parsed.install = true;
+      continue;
+    }
+
+    if (arg === "--no-install") {
+      parsed.install = false;
+      continue;
+    }
+
+    if (arg === "--pm") {
+      parsed.pm = argv[++i];
+      continue;
+    }
+
+    if (arg.startsWith("--pm=")) {
+      parsed.pm = arg.slice("--pm=".length);
+      continue;
+    }
+
+    if (!arg.startsWith("-") && !parsed.name) {
+      parsed.name = arg;
+      continue;
+    }
+  }
+
+  if (!parsed.name) parsed.name = "my-blokd-app";
+
+  validateProjectName(parsed.name);
+
+  if (parsed.pm && !["pnpm", "npm", "yarn", "bun"].includes(parsed.pm)) {
+    console.error(`Unsupported package manager: ${parsed.pm}`);
+    process.exit(1);
+  }
+
+  return parsed;
+}
+
+function validateProjectName(name) {
+  if (name === "." || name === "./") return;
+
+  const base = name.split(/[\\/]/).filter(Boolean).pop() ?? name;
+
+  if (!/^[a-zA-Z0-9._-]+$/.test(base)) {
+    console.error(`Invalid project name: ${name}`);
+    console.error("Use letters, numbers, dots, dashes, or underscores.");
+    process.exit(1);
+  }
+}
+
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? "";
+
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("bun")) return "bun";
+  if (ua.startsWith("npm")) return "npm";
+
+  return "pnpm";
+}
+
+function listTemplates() {
+  if (!existsSync(templatesRoot)) return [];
+  return readdirSync(templatesRoot).filter(name => {
+    const full = join(templatesRoot, name);
+    return statSync(full).isDirectory();
+  });
+}
+
+function copyDirectory(from, to) {
+  mkdirSync(to, { recursive: true });
+
+  for (const entry of readdirSync(from)) {
+    const source = join(from, entry);
+    const target = join(to, entry);
+
+    const stat = statSync(source);
+
+    if (stat.isDirectory()) {
+      copyDirectory(source, target);
+      continue;
+    }
+
+    const content = readFileSync(source);
+    writeFileSync(target, content);
+  }
+}
+
+function updatePackageName(packageJsonPath, projectName) {
+  if (!existsSync(packageJsonPath)) return;
+
+  const json = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  const baseName = projectName.split(/[\\/]/).filter(Boolean).pop() ?? projectName;
+
+  json.name = sanitizePackageName(baseName);
+
+  writeFileSync(packageJsonPath, `${JSON.stringify(json, null, 2)}\n`);
+}
+
+function sanitizePackageName(name) {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]/g, "-")
+    .replace(/^[._-]+/, "")
+    .replace(/[._-]+$/, "") || "my-blokd-app";
+}
+
+main();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "create-blokd",
+  "version": "0.1.0-beta.2",
+  "description": "Create a new Blokd project.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "create-blokd": "./bin/create-blokd.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "blokd",
+    "create-blokd",
+    "starter",
+    "template",
+    "hono",
+    "vite",
+    "ssr"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  }
+}

package/templates/minimal/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Blokd App</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <p>This file is used by Vite during development.</p>
+  </body>
+</html>

package/templates/minimal/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "blokd-minimal-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.0.0",
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "blokd": "0.1.0-beta.2",
+    "hono": ">=4.5 <5"
+  },
+  "devDependencies": {
+    "@types/node": ">=20 <23",
+    "typescript": ">=5.5 <6",
+    "vite": ">=6 <9"
+  }
+}

package/templates/minimal/src/blokd-env.d.ts

@@ -0,0 +1,4 @@
+declare module "virtual:blokd/routes" {
+  const routes: import("blokd/hono").RouteEntry[];
+  export default routes;
+}

package/templates/minimal/src/entry-client.ts

@@ -0,0 +1,3 @@
+import { startResumability } from "blokd/client";
+
+startResumability();

package/templates/minimal/src/resumables/demo.ts

@@ -0,0 +1,4 @@
+export function sayHello(event: Event, ctx: any) {
+  const button = event.currentTarget as HTMLButtonElement;
+  button.textContent = ctx.state.message;
+}

package/templates/minimal/src/routes/_404.tsx

@@ -0,0 +1,11 @@
+export default function NotFound() {
+  return (
+    <section>
+      <h1>Page not found</h1>
+      <p>The page you requested does not exist.</p>
+      <p>
+        <a href="/">Return home</a>
+      </p>
+    </section>
+  );
+}

package/templates/minimal/src/routes/_error.tsx

@@ -0,0 +1,17 @@
+type ErrorPageProps = {
+  error?: {
+    message?: string;
+  };
+};
+
+export default function ErrorPage(props: ErrorPageProps) {
+  return (
+    <section>
+      <h1>Something went wrong</h1>
+      <p>
+        {props.error?.message ??
+          "The application encountered an unexpected error."}
+      </p>
+    </section>
+  );
+}

package/templates/minimal/src/routes/_layout.tsx

@@ -0,0 +1,34 @@
+type LayoutProps = {
+  children?: unknown;
+  meta?: {
+    title?: string;
+    description?: string;
+  };
+};
+
+export default function Layout(props: LayoutProps) {
+  return (
+    <html lang="en">
+      <head>
+        <title>{props.meta?.title ?? "Blokd App"}</title>
+        <meta
+          name="description"
+          content={props.meta?.description ?? "A minimal Blokd application."}
+        />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+      </head>
+
+      <body>
+        <header>
+          <nav>
+            <a href="/">Home</a>
+            {" · "}
+            <a href="/about">About</a>
+          </nav>
+        </header>
+
+        <main>{props.children}</main>
+      </body>
+    </html>
+  );
+}

package/templates/minimal/src/routes/about.tsx

@@ -0,0 +1,17 @@
+export const meta = () => ({
+  title: "About | Blokd App",
+  description: "About this minimal Blokd application."
+});
+
+export default function About() {
+  return (
+    <section>
+      <h1>About</h1>
+
+      <p>
+        This route has no event handlers or islands, so Blokd can treat it as a
+        static/server-rendered route.
+      </p>
+    </section>
+  );
+}

package/templates/minimal/src/routes/index.tsx

@@ -0,0 +1,34 @@
+import { signal, Island, resumable } from "blokd";
+
+export const meta = () => ({
+  title: "Blokd App",
+  description: "A minimal Blokd application."
+});
+
+export default function Home() {
+  const [count, setCount] = signal(0);
+
+  return (
+    <section>
+      <h1>Blokd App</h1>
+
+      <p>
+        This page demonstrates Solid-familiar signals and a resumable island.
+      </p>
+
+      <button onClick={() => setCount(c => c + 1)}>
+        Count: {count()}
+      </button>
+
+      <Island name="demo-island" state={{ message: "Hello from Blokd" }}>
+        <button
+          type="button"
+          data-output
+          onClick={resumable("/src/resumables/demo.ts#sayHello")}
+        >
+          Run resumable handler
+        </button>
+      </Island>
+    </section>
+  );
+}

package/templates/minimal/src/server.ts

@@ -0,0 +1,19 @@
+import { Hono } from "hono";
+import { createPages } from "blokd/hono";
+import routes from "virtual:blokd/routes";
+
+const app = new Hono();
+
+app.get("/api/health", c => {
+  return c.json({ ok: true });
+});
+
+app.route(
+  "/",
+  createPages({
+    routes,
+    entryClient: "/src/entry-client.ts"
+  })
+);
+
+export default app;

package/templates/minimal/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "jsxImportSource": "blokd",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "strict": true,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/minimal/vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "vite";
+import { blokd } from "blokd/vite";
+
+export default defineConfig({
+  plugins: [
+    blokd({
+      routesDir: "src/routes",
+      clientEntry: "/src/entry-client.ts"
+    })
+  ]
+});