create-blokd 0.1.0-beta.2 → 0.1.0-beta.9

package/README.md

@@ -110,7 +110,6 @@ It includes:
 - custom 404 page
 - custom error page
 - client entry for resumable islands
-- one interactive signal example
 - one resumable island example
 - one static route
 
@@ -239,11 +238,21 @@ The goal is a small, explicit, Web Platform-oriented framework.
 
 ## Minimal starter walkthrough
 
-The generated app has two public pages:
+Available templates:
+
+~~~txt
+minimal    Balanced starter with islands, native forms, and static routes
+forms      Native form actions with no client runtime
+dashboard  Route-local islands plus static dashboard pages
+marketing  Static marketing pages with zero client budgets
+~~~
+
+The generated app has three public pages:
 
 ~~~txt
 src/routes/index.tsx  -> /
 src/routes/about.tsx  -> /about
+src/routes/contact.tsx -> /contact
 ~~~
 
 It also has three special route files:
@@ -257,11 +266,11 @@ 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.
+The contact page demonstrates a native POST form action that re-renders success or validation UI without client JavaScript.
 
 ## Hono server entry
 
@@ -330,11 +339,11 @@ The Vite plugin is responsible for:
 The starter includes a minimal resumable island:
 
 ~~~tsx
-<Island name="demo-island" state={{ message: "Hello from Blokd" }}>
+<Island name="demo-island" state={{ text: "Hello from Blokd" }}>
   <button
     type="button"
     data-output
-    onClick={resumable("/src/resumables/demo.ts#sayHello")}
+    onClick={on("/src/resumables/demo.ts#show")}
   >
     Run resumable handler
   </button>
@@ -344,10 +353,15 @@ The starter includes a minimal resumable island:
 The corresponding handler is:
 
 ~~~ts
-export function sayHello(event: Event, ctx: any) {
-  const button = event.currentTarget as HTMLButtonElement;
-  button.textContent = ctx.state.message;
-}
+import { defineAction } from "blokd/resume";
+
+type MessageState = {
+  text: string;
+};
+
+export const show = defineAction<MessageState>(({ state, el }) => {
+  el.text(state.text);
+});
 ~~~
 
 Blokd resumability is island-scoped. It is not full application graph serialization.
@@ -356,12 +370,22 @@ Blokd resumability is island-scoped. It is not full application graph serializat
 
 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 with event handlers, signals, effects, `Island`, `on`, 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.
 
+Static starter routes also declare:
+
+~~~ts
+export const budget = {
+  client: "0kb"
+};
+~~~
+
+This fails the build if client behavior is accidentally added to those routes.
+
 ## Package manager behavior
 
 `create-blokd` detects the package manager from the current npm user agent when possible.

package/bin/create-blokd.js

@@ -22,7 +22,7 @@ Usage:
   yarn create blokd my-app
 
 Options:
-  --template <name>       Template to use. Default: minimal
+  --template <name>       Template to use: minimal, forms, dashboard, marketing. Default: minimal
   --install               Install dependencies after creating the project
   --no-install            Do not install dependencies
   --pm <name>             Package manager: pnpm, npm, yarn, bun
@@ -31,6 +31,9 @@ Options:
 Examples:
   pnpm create blokd my-app
   pnpm create blokd my-app --template minimal
+  pnpm create blokd my-app --template forms
+  pnpm create blokd my-app --template dashboard
+  pnpm create blokd my-app --template marketing
   pnpm create blokd my-app --install
 `;
 
@@ -240,4 +243,4 @@ function sanitizePackageName(name) {
     .replace(/[._-]+$/, "") || "my-blokd-app";
 }
 
-main();
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-blokd",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.9",
   "description": "Create a new Blokd project.",
   "type": "module",
   "license": "MIT",

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

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

package/templates/dashboard/scripts/dev.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { createServer as createViteServer } from "vite";
+
+const host = process.env.HOST ?? "0.0.0.0";
+const port = Number(process.env.PORT ?? 5173);
+
+let handleRequest = (_req, res) => {
+  res.statusCode = 503;
+  res.end("Dev server is starting");
+};
+
+const httpServer = createServer((req, res) => {
+  handleRequest(req, res);
+});
+
+const vite = await createViteServer({
+  appType: "custom",
+  server: {
+    middlewareMode: true,
+    hmr: {
+      server: httpServer
+    }
+  }
+});
+
+handleRequest = async (req, res) => {
+  vite.middlewares(req, res, async () => {
+    try {
+      const mod = await vite.ssrLoadModule("/src/server.ts");
+      const app = mod.default;
+
+      if (!app || typeof app.fetch !== "function") {
+        throw new Error("src/server.ts must default-export a Hono app.");
+      }
+
+      const request = toWebRequest(req);
+      const response = await app.fetch(request);
+
+      await writeWebResponse(res, response);
+    } catch (error) {
+      vite.ssrFixStacktrace(error);
+
+      res.statusCode = 500;
+      res.setHeader("content-type", "text/plain; charset=utf-8");
+      res.end(error instanceof Error ? error.stack ?? error.message : String(error));
+    }
+  });
+};
+
+httpServer.listen(port, host, () => {
+  const displayHost = host === "0.0.0.0" ? "localhost" : host;
+
+  console.log("");
+  console.log(`  Blokd dev server`);
+  console.log(`  Local:   http://${displayHost}:${port}/`);
+  console.log("");
+});
+
+function toWebRequest(req) {
+  const protocol = req.headers["x-forwarded-proto"] ?? "http";
+  const hostHeader = req.headers.host ?? `${host}:${port}`;
+  const url = `${protocol}://${hostHeader}${req.url ?? "/"}`;
+
+  const headers = new Headers();
+
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(key, item);
+    } else if (value !== undefined) {
+      headers.set(key, value);
+    }
+  }
+
+  const init = {
+    method: req.method ?? "GET",
+    headers
+  };
+
+  if (init.method !== "GET" && init.method !== "HEAD") {
+    init.body = Readable.toWeb(req);
+    init.duplex = "half";
+  }
+
+  return new Request(url, init);
+}
+
+async function writeWebResponse(res, response) {
+  res.statusCode = response.status;
+  res.statusMessage = response.statusText;
+
+  response.headers.forEach((value, key) => {
+    res.setHeader(key, value);
+  });
+
+  if (!response.body) {
+    res.end();
+    return;
+  }
+
+  const stream = Readable.fromWeb(response.body);
+  stream.pipe(res);
+}

package/templates/dashboard/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/dashboard/src/entry-client.ts

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

package/templates/dashboard/src/resumables/counter.ts

@@ -0,0 +1,10 @@
+import { defineAction } from "blokd/resume";
+
+type CounterState = {
+  count: number;
+};
+
+export const increment = defineAction<CounterState>(({ state, el }) => {
+  state.count += 1;
+  el.text(`Count: ${state.count}`);
+});

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

@@ -0,0 +1,9 @@
+import { defineAction } from "blokd/resume";
+
+type MessageState = {
+  text: string;
+};
+
+export const show = defineAction<MessageState>(({ state, el }) => {
+  el.text(state.text);
+});

package/templates/dashboard/src/resumables/status.ts

@@ -0,0 +1,10 @@
+import { defineAction } from "blokd/resume";
+
+type StatusState = {
+  text: string;
+};
+
+export const refresh = defineAction<StatusState>(({ state, el }) => {
+  state.text = state.text === "Queue healthy" ? "Queue checked" : "Queue healthy";
+  el.text(state.text);
+});

package/templates/dashboard/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/dashboard/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/dashboard/src/routes/_layout.tsx

@@ -0,0 +1,36 @@
+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="/reports">Reports</a>
+            {" · "}
+            <a href="/contact">Contact</a>
+          </nav>
+        </header>
+
+        <main>{props.children}</main>
+      </body>
+    </html>
+  );
+}

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

@@ -0,0 +1,23 @@
+export const meta = () => ({
+  title: "About | Blokd App",
+  description: "About this minimal Blokd application."
+});
+
+export const runtime = "none";
+
+export const budget = {
+  client: "0kb"
+};
+
+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/dashboard/src/routes/contact.tsx

@@ -0,0 +1,58 @@
+type ContactData = {
+  ok?: boolean;
+  email?: string;
+  error?: string;
+};
+
+type ContactProps = {
+  data?: ContactData;
+};
+
+export const meta = () => ({
+  title: "Contact | Blokd App",
+  description: "A native form route in a minimal Blokd application."
+});
+
+export const runtime = "none";
+
+export const budget = {
+  client: "0kb"
+};
+
+export async function action({ request }: { request: Request }) {
+  const form = await request.formData();
+  const email = String(form.get("email") ?? "").trim();
+
+  if (!email.includes("@")) {
+    return {
+      ok: false,
+      error: "Enter a valid email."
+    };
+  }
+
+  return {
+    ok: true,
+    email
+  };
+}
+
+export default function Contact(props: ContactProps) {
+  return (
+    <section>
+      <h1>Contact</h1>
+
+      <p>This form submits with native browser POST and no client JavaScript.</p>
+
+      {props.data?.error ? <p role="alert">{props.data.error}</p> : null}
+      {props.data?.ok ? <p>{`Subscribed ${props.data.email}`}</p> : null}
+
+      <form method="post">
+        <label>
+          Email
+          <input name="email" type="email" required />
+        </label>
+        <button>Subscribe</button>
+      </form>
+    </section>
+  );
+}

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

@@ -0,0 +1,46 @@
+import { Island, on } from "blokd";
+
+export const meta = () => ({
+  title: "Dashboard | Blokd App",
+  description: "A dashboard starter using route-local islands."
+});
+
+export default function Home() {
+  return (
+    <section>
+      <h1>Dashboard</h1>
+
+      <p>
+        Interactive controls are isolated to the dashboard route. Static routes
+        still ship no client runtime.
+      </p>
+
+      <Island name="counter" state={{ count: 0 }}>
+        <button
+          type="button"
+          onClick={on("/src/resumables/counter.ts#increment")}
+        >
+          Count: 0
+        </button>
+      </Island>
+
+      <Island name="demo-island" state={{ text: "Hello from Blokd" }}>
+        <button
+          type="button"
+          onClick={on("/src/resumables/demo.ts#show")}
+        >
+          Run resumable handler
+        </button>
+      </Island>
+
+      <Island name="status" state={{ text: "Queue healthy" }}>
+        <button
+          type="button"
+          onClick={on("/src/resumables/status.ts#refresh")}
+        >
+          Refresh status
+        </button>
+      </Island>
+    </section>
+  );
+}

package/templates/dashboard/src/routes/reports.tsx

@@ -0,0 +1,37 @@
+export const meta = () => ({
+  title: "Reports | Blokd App",
+  description: "A static dashboard report route."
+});
+
+export const runtime = "none";
+
+export const budget = {
+  client: "0kb"
+};
+
+export default function Reports() {
+  return (
+    <section>
+      <h1>Reports</h1>
+      <p>This route is static and keeps the dashboard client runtime out.</p>
+      <table>
+        <thead>
+          <tr>
+            <th>Metric</th>
+            <th>Value</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>Open tasks</td>
+            <td>12</td>
+          </tr>
+          <tr>
+            <td>Response time</td>
+            <td>42ms</td>
+          </tr>
+        </tbody>
+      </table>
+    </section>
+  );
+}

package/templates/dashboard/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/dashboard/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/dashboard/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"
+    })
+  ]
+});

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

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