create-yerd 0.0.0-stage → 0.2.2

package/templates/full/src/routes/auth.tsx

@@ -0,0 +1,71 @@
+import { ActionForm, ValidationFailed, action, get, inject, layout, post, query, redirect, route, session, type Session } from "@toyz/yerd";
+import { safeNext, verifyPassword } from "@toyz/yerd/auth";
+import { Field } from "../components.js";
+import { Narrow } from "../layouts.js";
+import { DEMO_ACCOUNT, LoginForm, Users, auth, type User } from "../users.js";
+
+interface LoginState {
+  error?: string;
+  name?: string;
+}
+
+@route("/login", { meta: { title: "Sign in" } })
+@layout(Narrow)
+export class LoginPage {
+  @inject(Users) accessor users!: Users;
+  @auth.maybeUser accessor me: User | undefined;
+  @session accessor session!: Session;
+  @query("next") accessor next: string | undefined;
+
+  @get page() {
+    // safeNext: same-site paths only, so ?next=https://evil.example can't bounce anyone off-site.
+    if (this.me) return redirect(safeNext(this.next));
+    const state = (this.session.flash("login") ?? {}) as LoginState;
+    return (
+      <>
+        <h1>Sign in</h1>
+        <form action={this.submit}>
+          <Field name="name" label="Username" value={state.name} autocomplete="username" />
+          <Field name="password" label="Password" type="password" autocomplete="current-password" />
+          <p class="form-error" data-yx-error role="alert">{state.error}</p>
+          <button>Sign in</button>
+        </form>
+        <p class="hint">
+          Demo account: <code>{DEMO_ACCOUNT.name}</code> / <code>{DEMO_ACCOUNT.password}</code>
+        </p>
+      </>
+    );
+  }
+
+  @action async submit(_: {}, form: ActionForm) {
+    let input: LoginForm;
+    try {
+      input = form.parse(LoginForm);
+    } catch (error) {
+      if (!(error instanceof ValidationFailed)) throw error;
+      return this.#fail("Enter your username and password.", form.get("name"));
+    }
+    const user = this.users.byName(input.name);
+    // Spends a full hash even for unknown names, so timing doesn't reveal who has an account.
+    if (!(await verifyPassword(input.password, user?.passwordHash)) || !user) {
+      return this.#fail("Wrong username or password.", input.name);
+    }
+    // Rotates the session id and keeps a guest's data: the cart comes along.
+    await auth.login(user);
+    return redirect(safeNext(this.next));
+  }
+
+  /** Back to the form with a message, with or without JavaScript. */
+  #fail(error: string, name: string | undefined) {
+    this.session.flash("login", { error, name } satisfies LoginState);
+    return redirect(`/login${this.next ? `?next=${encodeURIComponent(this.next)}` : ""}`);
+  }
+}
+
+@route("/logout")
+export class Logout {
+  @post async leave() {
+    await auth.logout();
+    return redirect("/");
+  }
+}

package/templates/full/src/routes/cart.tsx

@@ -0,0 +1,66 @@
+import { Region, action, get, inject, route, session, type Session } from "@toyz/yerd";
+import { Cart, priceCart } from "../cart.js";
+import { Catalog } from "../catalog.js";
+import { Price } from "../components.js";
+import { CartBadge } from "../layouts.js";
+
+@route("/cart", { meta: { title: "Your cart" } })
+export class CartPage {
+  @inject(Catalog) accessor catalog!: Catalog;
+  @session(Cart) accessor cart!: Session<Cart>;
+
+  @get page() {
+    return (
+      <>
+        <h1>Your cart</h1>
+        {this.lines()}
+      </>
+    );
+  }
+
+  /** The lines and the total: one Region, so the remove action can send it back. */
+  lines() {
+    const { lines, total } = priceCart(this.cart.lines, this.catalog);
+    if (lines.length === 0) {
+      return (
+        <Region id="cart">
+          <p class="empty">
+            Your cart is empty. <a href="/">Go shopping</a>.
+          </p>
+        </Region>
+      );
+    }
+    return (
+      <Region id="cart">
+        <ul class="lines">
+          {lines.map(({ product, qty, subtotal }) => (
+            <li key={product.id}>
+              <a href={`/products/${product.id}`}>{product.name}</a>
+              <span>x {qty}</span>
+              <Price cents={subtotal} />
+              {/* The id is signed into the action: the browser can't change which line goes. */}
+              <form action={() => this.remove({ id: product.id })}>
+                <button class="link" aria-label={`Remove ${product.name}`}>Remove</button>
+              </form>
+            </li>
+          ))}
+        </ul>
+        <p class="total">
+          Total <Price cents={total} />
+        </p>
+        <a class="button" href="/checkout">Check out</a>
+      </Region>
+    );
+  }
+
+  @action remove({ id }: { id: number }) {
+    this.cart.remove(id);
+    // Every Region the change touches.
+    return (
+      <>
+        {this.lines()}
+        <CartBadge count={this.cart.count} />
+      </>
+    );
+  }
+}

package/templates/full/src/routes/checkout.tsx

@@ -0,0 +1,101 @@
+import { ActionForm, NotFound, ValidationFailed, action, currentContext, get, group, inject, param, redirect, route, session, toInt, type Session } from "@toyz/yerd";
+import { Cart, priceCart } from "../cart.js";
+import { Catalog } from "../catalog.js";
+import { Field, Price } from "../components.js";
+import { Narrow } from "../layouts.js";
+import { CheckoutForm, Orders } from "../orders.js";
+import { auth, type User } from "../users.js";
+
+/** Everything here needs a signed-in user, in a narrow column. No URL prefix. */
+@group("/", { guards: [auth.required], layout: Narrow })
+export class Account {}
+
+/** What a failed plain (no JavaScript) post leaves for the page it goes back to. */
+interface CheckoutState {
+  errors?: Record<string, string>;
+  draft?: Record<string, string | undefined>;
+}
+
+@route("/checkout", { group: Account, meta: { title: "Check out" } })
+export class CheckoutPage {
+  @inject(Catalog) accessor catalog!: Catalog;
+  @inject(Orders) accessor orders!: Orders;
+  @auth.user accessor me!: User;
+  @session(Cart) accessor cart!: Session<Cart>;
+  @session accessor session!: Session;
+
+  @get page() {
+    const { lines, total } = priceCart(this.cart.lines, this.catalog);
+    if (lines.length === 0) return redirect("/cart");
+    const { errors = {}, draft = { name: this.me.name } } = (this.session.flash("checkout") ?? {}) as CheckoutState;
+    return (
+      <>
+        <h1>Check out</h1>
+        <ul class="summary">
+          {lines.map(({ product, qty, subtotal }) => (
+            <li>
+              {qty} x {product.name} <Price cents={subtotal} />
+            </li>
+          ))}
+        </ul>
+        <p class="total">
+          Total <Price cents={total} />
+        </p>
+        <form action={this.place}>
+          <Field name="name" label="Name" value={draft.name} error={errors.name} autocomplete="name" />
+          <Field name="email" label="Email" type="email" value={draft.email} error={errors.email} autocomplete="email" />
+          <Field name="address" label="Address" value={draft.address} error={errors.address} autocomplete="street-address" />
+          <p class="form-error" data-yx-error role="alert"></p>
+          <button>Place order</button>
+        </form>
+      </>
+    );
+  }
+
+  @action place(_: {}, form: ActionForm) {
+    let details: CheckoutForm;
+    try {
+      details = form.parse(CheckoutForm);
+    } catch (error) {
+      // From the runtime (it sends a `yx` header): rethrow, and each issue lands in its field's box.
+      if (!(error instanceof ValidationFailed) || currentContext().headers.yx !== undefined) throw error;
+      // A plain form post: keep the messages and the input for the page we send it back to.
+      const errors: Record<string, string> = {};
+      for (const { path, message } of error.issues) errors[path] ??= message;
+      const draft = { name: form.get("name"), email: form.get("email"), address: form.get("address") };
+      this.session.flash("checkout", { errors, draft } satisfies CheckoutState);
+      return redirect("/checkout");
+    }
+    const order = this.orders.place(this.me, details, this.cart.lines);
+    this.cart.empty();
+    return redirect(`/orders/${order.id}`);
+  }
+}
+
+@route("/orders/:id", { group: Account, meta: { title: "Thank you" } })
+export class OrderPage {
+  @inject(Orders) accessor orders!: Orders;
+  @auth.user accessor me!: User;
+  @param("id", { transform: toInt }) accessor id!: number;
+
+  @get page() {
+    const order = this.orders.get(this.id, this.me);
+    if (!order) throw new NotFound("No such order");
+    return (
+      <>
+        <h1>Order {order.id} is in</h1>
+        <p>A receipt is on its way to {order.email}.</p>
+        <ul class="summary">
+          {order.lines.map((line) => (
+            <li>
+              {line.qty} x {line.name} <Price cents={line.price * line.qty} />
+            </li>
+          ))}
+        </ul>
+        <p class="total">
+          Total <Price cents={order.total} />
+        </p>
+      </>
+    );
+  }
+}

package/templates/full/src/routes/products.tsx

@@ -0,0 +1,79 @@
+import { Conflict, Region, action, get, inject, param, query, route, session, setMeta, toInt, trim, type Session } from "@toyz/yerd";
+import { Cart } from "../cart.js";
+import { Catalog } from "../catalog.js";
+import { Price, ProductCard } from "../components.js";
+import { CartBadge } from "../layouts.js";
+
+/** The front page: every product, narrowed by ?q=. */
+@route("/", { meta: { title: "Shop" } })
+export class ProductList {
+  @inject(Catalog) accessor catalog!: Catalog;
+  @query("q", { transform: trim }) accessor q = "";
+
+  @get page() {
+    const products = this.catalog.search(this.q);
+    return (
+      <>
+        {/* A GET form: the search is a URL you can share and reload. */}
+        <form class="search" method="get" role="search">
+          <input type="search" name="q" value={this.q} placeholder="Search" aria-label="Search" />
+          <button>Search</button>
+        </form>
+        {products.length === 0 ? (
+          <p class="empty">Nothing matches "{this.q}".</p>
+        ) : (
+          <ul class="products">{products.map((p) => <ProductCard product={p} />)}</ul>
+        )}
+      </>
+    );
+  }
+}
+
+/** Stock left, as a Region: the add action sends a fresh one. */
+function Stock({ stock }: { stock: number }) {
+  return (
+    <Region id="stock" as="p" class="stock">
+      {stock === 0 ? "Sold out" : `${stock} in stock`}
+    </Region>
+  );
+}
+
+/** One product. An unknown id is the catalog's ProductNotFound: a 404. */
+@route("/products/:id")
+export class ProductPage {
+  @inject(Catalog) accessor catalog!: Catalog;
+  @param("id", { transform: toInt }) accessor id!: number;
+  @session(Cart) accessor cart!: Session<Cart>;
+
+  @get page() {
+    const product = this.catalog.find(this.id);
+    setMeta({ title: product.name, description: product.description });
+    return (
+      <article class="product">
+        <h1>{product.name}</h1>
+        <p>{product.description}</p>
+        <Price cents={product.price} />
+        <Stock stock={product.stock} />
+        <form action={this.add}>
+          <button disabled={product.stock === 0}>Add to cart</button>
+        </form>
+      </article>
+    );
+  }
+
+  /** @param works in actions too: this.id is the product on the page. */
+  @action add() {
+    const product = this.catalog.find(this.id);
+    const inCart = this.cart.lines.find((line) => line.id === product.id)?.qty ?? 0;
+    // A 409: the runtime shows its message. Checkout checks the stock again anyway.
+    if (inCart >= product.stock) throw new Conflict(product.stock === 0 ? "Sold out." : `Only ${product.stock} in stock.`);
+    this.cart.add(product.id);
+    // With the runtime, these morph in; without it, the browser is sent back to the page.
+    return (
+      <>
+        <CartBadge count={this.cart.count} />
+        <Stock stock={product.stock} />
+      </>
+    );
+  }
+}

package/templates/full/src/styles.css

@@ -0,0 +1,72 @@
+/* Linked with <Stylesheet href="src/styles.css" />; hashed by `vite build`. */
+:root {
+  --bg: #faf8f4;
+  --surface: #ffffff;
+  --text: #1f1d1a;
+  --muted: #6d675e;
+  --line: #e4dfd6;
+  --accent: #2f5d8a;
+  --accent-ink: #ffffff;
+  --danger: #b3261e;
+  --radius: 10px;
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #161513;
+    --surface: #201e1b;
+    --text: #f0ece5;
+    --muted: #a29b90;
+    --line: #35322d;
+    --accent: #8ab6e6;
+    --accent-ink: #10161d;
+    --danger: #ff8a80;
+    color-scheme: dark;
+  }
+}
+
+*, *::before, *::after { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 16px/1.5 ui-sans-serif, system-ui, sans-serif; }
+a { color: var(--accent); }
+button, input { font: inherit; color: inherit; }
+button, .button {
+  display: inline-block; padding: 6px 14px; border: 0; border-radius: var(--radius);
+  background: var(--accent); color: var(--accent-ink); text-decoration: none; cursor: pointer;
+}
+button:disabled { opacity: 0.4; cursor: not-allowed; }
+button.link { background: none; color: var(--accent); padding: 0; text-decoration: underline; }
+input { padding: 6px 10px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); }
+
+.top { display: flex; align-items: center; gap: 16px; max-width: 760px; margin: 0 auto; padding: 20px 16px; }
+.brand { font-weight: 700; font-size: 1.2rem; color: var(--text); text-decoration: none; margin-right: auto; }
+.cart-badge { text-decoration: none; }
+.badge { display: inline-block; min-width: 1.6em; padding: 0 6px; border-radius: 99px; background: var(--accent); color: var(--accent-ink); text-align: center; }
+.account { display: flex; gap: 8px; align-items: center; margin: 0; }
+main { max-width: 760px; margin: 0 auto; padding: 0 16px 48px; }
+.narrow { max-width: 420px; }
+
+.search { display: flex; gap: 8px; margin-bottom: 16px; }
+.search input { flex: 1; }
+.products { list-style: none; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 12px; }
+.card { display: grid; align-content: start; gap: 4px; padding: 14px; background: var(--surface); border: 1px solid var(--line); border-radius: var(--radius); }
+.price { font-variant-numeric: tabular-nums; }
+.sold-out, .empty, .hint { color: var(--muted); }
+
+.product { display: grid; gap: 8px; justify-items: start; }
+.product h1 { margin: 0; }
+.stock { margin: 0; color: var(--muted); }
+
+.lines { list-style: none; padding: 0; display: grid; gap: 8px; }
+.lines li { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; padding: 10px 0; border-bottom: 1px solid var(--line); }
+.lines li > a { flex: 1; }
+.lines form { margin: 0; }
+.total { font-weight: 700; }
+.summary { padding-left: 1.2em; }
+
+.field { display: grid; gap: 4px; margin: 0 0 12px; }
+.field-error, .form-error { color: var(--danger); font-size: 0.9rem; }
+.field-error:empty, .form-error:empty { display: none; }
+[aria-invalid="true"] { border-color: var(--danger); }
+
+.error-page .status { font-size: 3rem; font-weight: 700; margin: 0; color: var(--muted); }

package/templates/full/src/users.ts

@@ -0,0 +1,41 @@
+import { is, lower, onBoot, resolve, service, trim } from "@toyz/yerd";
+import { createAuth, hashPassword } from "@toyz/yerd/auth";
+
+export interface User {
+  id: string;
+  name: string;
+  passwordHash: string;
+}
+
+/** Listed on the sign-in page. */
+export const DEMO_ACCOUNT = { name: "ada", password: "analytical-engine" };
+
+export class LoginForm {
+  @is.string({ transform: [trim, lower] }) name!: string;
+  @is.string() password!: string;
+}
+
+/** Accounts, in memory. Swap in a database when you have one. */
+@service
+export class Users {
+  #users: User[] = [];
+
+  /** Hashing is async, so the demo account is made at boot, before the first request. */
+  @onBoot async seed() {
+    this.#users.push({ id: "u1", name: DEMO_ACCOUNT.name, passwordHash: await hashPassword(DEMO_ACCOUNT.password) });
+  }
+
+  get(id: string): User | undefined {
+    return this.#users.find((u) => u.id === id);
+  }
+
+  byName(name: string): User | undefined {
+    return this.#users.find((u) => u.name === name);
+  }
+}
+
+/** Session sign-in: `app.use(auth)`, `guards: [auth.required]`, `@auth.user`. */
+export const auth = createAuth<User>({
+  load: (id) => resolve(Users).get(id),
+  loginPath: "/login",
+});

package/templates/full/test/shop.test.ts

@@ -0,0 +1,130 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { parse, ValidationFailed } from "@toyz/yerd";
+import { createApp } from "../src/app.js";
+import { CheckoutForm } from "../src/orders.js";
+import { DEMO_ACCOUNT } from "../src/users.js";
+import "../src/routes/products.js";
+import "../src/routes/cart.js";
+import "../src/routes/checkout.js";
+import "../src/routes/auth.js";
+import "../src/routes/api.js";
+
+// The app main.ts serves, with the routes this file imports. No port is opened.
+const app = createApp({ handleSignals: false });
+beforeAll(() => app.boot());
+afterAll(() => app.stop());
+
+const page = { accept: "text/html" };
+const address = { name: "Ada Lovelace", email: "ada@example.com", address: "12 St James's Square, London" };
+
+/** A client with a Pocket notebook (id 2) in the cart, signed in as the demo account. */
+async function shopper() {
+  const client = app.client();
+  await client.action("/products/2", {});
+  await client.action("/login?next=/checkout", DEMO_ACCOUNT);
+  return client;
+}
+
+describe("the catalog", () => {
+  it("lists every product, and searches", async () => {
+    const res = await app.request("/", { headers: page });
+    expect(res.status).toBe(200);
+    expect((await res.text()).match(/class="card"/g)).toHaveLength(5);
+
+    const html = await (await app.request("/?q=notebook", { headers: page })).text();
+    expect(html).toContain("Pocket notebook");
+    expect(html).not.toContain("Fountain pen");
+  });
+
+  it("is a 404 for an unknown product: the error page for browsers, JSON for the rest", async () => {
+    const html = await app.request("/products/99", { headers: page });
+    expect(html.status).toBe(404);
+    expect(await html.text()).toContain("Not on the shelves");
+
+    const json = await app.request("/products/99");
+    expect(json.status).toBe(404);
+    expect(await json.json()).toEqual({ error: "No product 99", code: "not_found", id: 99 });
+  });
+});
+
+describe("the cart", () => {
+  it("adds to the cart and sends back the badge", async () => {
+    const client = app.client();
+    const res = await client.action("/products/2", {});
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain('<span class="badge">1</span>');
+    expect(await client.page("/cart")).toContain("Pocket notebook");
+  });
+
+  it("refuses a sold-out product", async () => {
+    const res = await app.client().action("/products/5", {});
+    expect(res.status).toBe(409);
+    expect(await res.json()).toEqual({ error: "Sold out.", code: "conflict" });
+  });
+
+  it("removes a line", async () => {
+    const client = app.client();
+    await client.action("/products/2", {});
+    const res = await client.action("/cart", {});
+    const html = await res.text();
+    expect(html).toContain("Your cart is empty.");
+    expect(html).toContain('<span class="badge">0</span>');
+  });
+});
+
+describe("sign in and checkout", () => {
+  it("sends guests to sign in first", async () => {
+    const res = await app.request("/checkout", { headers: page });
+    expect(res.status).toBe(303);
+    expect(res.headers.get("location")).toBe("/login?next=%2Fcheckout");
+  });
+
+  it("refuses a wrong password", async () => {
+    const client = app.client();
+    await client.action("/login", { name: "ada", password: "nope" });
+    expect(await client.page("/login")).toContain("Wrong username or password.");
+  });
+
+  it("reports every invalid field at once", async () => {
+    const client = await shopper();
+    const res = await client.action("/checkout", { name: "A", email: "nope", address: "" });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({
+      issues: [{ path: "name" }, { path: "email", message: "Expected an email address" }, { path: "address" }],
+    });
+  });
+
+  it("places the order and empties the cart", async () => {
+    const client = await shopper();
+    const res = await client.action("/checkout", address);
+    const location = res.headers.get("yx-location");
+    expect(location).toMatch(/^\/orders\/\d+$/);
+
+    const receipt = await client.page(location!);
+    expect(receipt).toContain("A receipt is on its way to ada@example.com.");
+    expect(receipt).toContain('<span class="badge">0</span>');
+  });
+
+  it("validates the form without a request", () => {
+    expect(() => parse(CheckoutForm, { name: "A", email: "nope", address: "" })).toThrow(ValidationFailed);
+    expect(parse(CheckoutForm, { ...address, name: "  Ada  " }).name).toBe("Ada");
+  });
+});
+
+describe("the JSON API", () => {
+  it("lists and shows products, with no session cookie", async () => {
+    const res = await app.request("/api/products?q=lamp");
+    expect(res.headers.get("set-cookie")).toBeNull();
+    expect(await res.json()).toMatchObject([{ id: 3, name: "Desk lamp" }]);
+
+    const missing = await app.request("/api/products/99");
+    expect(missing.status).toBe(404);
+    expect(await missing.json()).toMatchObject({ code: "not_found", id: 99 });
+  });
+
+  it("answers health checks with 204", async () => {
+    const res = await app.request("/api/health");
+    expect(res.status).toBe(204);
+    expect(await res.text()).toBe("");
+  });
+});

package/templates/full/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["ES2023", "esnext.decorators", "DOM"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@toyz/yerd"
+  },
+  "include": ["src", "test", "e2e", "*.config.ts"]
+}

package/templates/full/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vite";
+import yerd from "@toyz/yerd/vite";
+
+export default defineConfig({
+  // `client`: files `vite build` hashes; <Stylesheet> links them through the manifest.
+  plugins: [yerd({ entry: "/src/main.ts", client: ["src/styles.css"] })],
+});

package/templates/minimal/README.md

@@ -0,0 +1,26 @@
+# {{name}}
+
+A [yerd](https://toyz.github.io/yerd/) app: one page, a layout and an action.
+
+```sh
+{{run_dev}}      # dev server with reloads, on http://localhost:5173
+{{run_test}}     # vitest, in-process: no port, no browser
+{{run_check}}    # type-check (Vite doesn't)
+{{run_build}}    # production build: dist/client and dist/server/server.js
+{{run_start}}    # node dist/server/server.js, on PORT or 3000
+```
+
+Copy `.env.example` to `.env` and set `YERD_SECRET` before you deploy: it
+signs forms and seals the session cookie.
+
+| File | What |
+| --- | --- |
+| `src/main.ts` | the Vite entry: the app with every route under `src/routes/` |
+| `src/app.ts` | `createApp()`: layout, error page, sessions; shared with the tests |
+| `src/layouts.tsx` | `RootLayout`, the document; `ErrorPage` for 404s and crashes |
+| `src/routes/home.tsx` | `GET /` and its `click` action |
+| `src/styles.css` | linked with `<Stylesheet>`, hashed in the build |
+| `test/app.test.ts` | `app.request()` and `app.client()` tests |
+
+Next: [your first app](https://toyz.github.io/yerd/#/guide/your-first-app)
+walks through routes, pages, forms and sessions.

package/templates/minimal/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#c2410c"/><path d="M9 9l7 9 7-9M16 18v6" fill="none" stroke="#fff" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/templates/minimal/src/app.ts

@@ -0,0 +1,7 @@
+import { yerd, type YerdOptions } from "@toyz/yerd";
+import { ErrorPage, RootLayout } from "./layouts.js";
+
+/** The app without routes: main.ts discovers them, tests import the ones they need. */
+export function createApp(options?: YerdOptions) {
+  return yerd(options).layout(RootLayout).errorPage(ErrorPage).sessions();
+}

package/templates/minimal/src/layouts.tsx

@@ -0,0 +1,32 @@
+import { Scripts, Stylesheet, type ErrorPageProps, type LayoutProps } from "@toyz/yerd";
+
+/** The document around every HTML response, error pages included. */
+export function RootLayout({ children, meta }: LayoutProps) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+        <title>{meta.title ? `${meta.title} · {{name}}` : "{{name}}"}</title>
+        <Stylesheet href="src/styles.css" />
+        <Scripts />
+      </head>
+      <body>
+        <main>{children}</main>
+      </body>
+    </html>
+  );
+}
+
+/** app.errorPage(): 404s and crashes render here, inside RootLayout. */
+export function ErrorPage({ status, message }: ErrorPageProps) {
+  return (
+    <section class="error">
+      <p class="status">{status}</p>
+      <h1>{status === 404 ? "Page not found" : "Something went wrong"}</h1>
+      <p>{message}</p>
+      <a href="/">Home</a>
+    </section>
+  );
+}

package/templates/minimal/src/main.ts

@@ -0,0 +1,5 @@
+/// <reference types="vite/client" />
+import { createApp } from "./app.js";
+
+// The Vite entry. The plugin serves it in dev and the build's server.js listens: no listen() here.
+export default createApp().discover(import.meta.glob("./routes/**/*.{ts,tsx}", { eager: true }));