create-youtiao 0.1.0

package/index.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+
+import { resolve, basename } from "node:path";
+import { cp, readFile, stat, writeFile } from "node:fs/promises";
+
+const projectName = process.argv[2];
+
+if (!projectName) {
+  console.log(`Usage: bunx create-youtiao <project-name>`);
+  process.exit(1);
+}
+
+const dest = resolve(process.cwd(), projectName);
+const templateDir = resolve(import.meta.dir, "template");
+
+try {
+  await stat(dest);
+  console.error(`Destination already exists: ${dest}`);
+  process.exit(1);
+} catch (err) {
+  const errno = err as NodeJS.ErrnoException;
+  if (errno.code !== "ENOENT") {
+    throw err;
+  }
+}
+
+console.log(`Creating ${projectName}...`);
+
+// Copy template
+await cp(templateDir, dest, { recursive: true });
+
+// Update package.json name
+const pkgPath = resolve(dest, "package.json");
+const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+pkg.name = basename(projectName);
+await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+
+console.log(`
+Done! To get started:
+
+  cd ${projectName}
+  bun install
+  bunx youtiao dev
+`);

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "create-youtiao",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-youtiao": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "template"
+  ]
+}

package/template/CLAUDE.md

@@ -0,0 +1,116 @@
+## Stack
+
+- **Bun** — Runtime, bundler, test runner, package manager
+- **Youtiao** — Svelte 5 + Bun web framework with filesystem routing, SSR, and hydration
+- **GraphPC** — RPC framework (like tRPC with a graph). Docs: `node_modules/graphpc/docs/llm.md`
+- **Svelte 5** — Uses runes (`$props`, `$state`, `$derived`, etc.)
+- **Zod** — Schema validation
+
+## Commands
+
+- `bun install` — Install dependencies
+- `bunx youtiao dev` — Start the dev server
+- `bunx youtiao build` — Create a production build
+- `bun test` — Run tests
+- `bunx tsc` — Type-check
+
+## Project Layout
+
+- `src/routes/` — Filesystem-routed Svelte pages
+- `src/server.ts` — GraphPC API definition, auto-loaded by the framework for SSR + WebSocket RPC
+- `youtiao.config.ts` — Framework config (routes dir, output dir, server port, etc.)
+
+## Routing
+
+Pages are `.svelte` files in `src/routes/`. Special files:
+- `+index.svelte` — Directory index page
+- `+layout.svelte` — Layout wrapper (nests with parent layouts)
+- `+error.svelte` — Error boundary
+- `[param].svelte` — Dynamic route segment
+- `[*].svelte` — Catch-all route
+
+Pages receive `rpc` and `params` as props.
+
+## RPC
+
+`src/server.ts` exports a GraphPC server. Pages access it via the `rpc` prop — calls run directly during SSR, over WebSocket on the client. Read `node_modules/graphpc/docs/llm.md` for the full GraphPC API.
+
+## Svelte + GraphPC Patterns
+
+Your API is an object graph. Navigate it with dot notation, `await` to read, call methods to act. It feels like working with local objects — the network is invisible.
+
+### Navigate and read
+Edges (`@edge`) traverse the graph synchronously — no network call, just returns a stub. `await stub` fetches the node's data (public properties and getters). Wrap in `$derived` for reactivity, or use plain `await` for data that won't change during the component's lifetime.
+
+```svelte
+<script>
+  const post = rpc.posts.get(Number(params.id));  // edge traversal, sync
+  const data = $derived(await $post);              // reactive read — re-runs when post updates
+  const author = await post.author;                // one-time read — fine for static data
+</script>
+```
+
+### Mutate
+Methods (`@method`) are actions — always async, always hit the server. When a method returns `ref()`, the cache updates automatically and any `$derived` watching that node re-runs. No manual refresh needed.
+
+```svelte
+<script>
+  async function handleLike() {
+    await post.like();
+    // like() returns ref(Post, id) → cache updates → $derived(await $post) re-fires
+  }
+</script>
+```
+
+For structural changes (adding/removing items from a collection), `invalidate()` the container so it re-fetches its list:
+
+```svelte
+<script>
+  async function deletePost(id) {
+    await rpc.posts.remove(id);
+    invalidate(page);
+  }
+</script>
+```
+
+### Compose with subtrees
+Pass components the narrowest slice of the graph they need. Edge traversal within the component produces observable stubs automatically — each component manages its own data.
+
+```svelte
+<PostCard post={rpc.posts.get(id)} />       <!-- PostCard does $derived(await $post) -->
+<CommentThread comments={post.comments} />   <!-- manages its own CRUD internally -->
+<StatsSidebar stats={rpc.stats} />           <!-- reads aggregates, consumes streams -->
+```
+
+### Collections
+Model collections as page nodes entered via `@edge`. The page's items are a data field — one `await` gives you everything. See `node_modules/graphpc/docs/patterns.md` for pagination.
+
+```svelte
+<script>
+  const page = rpc.posts.page;
+  const items = $derived(await $page.items());
+</script>
+```
+
+### Streams
+`@stream` async generators push live data to the client. They're inert during SSR — consume them in `$effect` with a cleanup function.
+
+```svelte
+<script>
+  let events = $state([]);
+  $effect(() => {
+    const stream = stats.liveActivity();
+    let active = true;
+    (async () => {
+      for await (const event of stream) {
+        if (!active) break;
+        events = [event, ...events].slice(0, 20);
+      }
+    })();
+    return () => { active = false; };
+  });
+</script>
+```
+
+### Pitfall: invalidation loops
+Avoid `$derived(await $stub.method())` when the method returns refs that are descendants of the subscribed path — this creates an infinite loop. The page edge pattern sidesteps this by design.

package/template/README.md

@@ -0,0 +1,140 @@
+# my-youtiao-app
+
+Built with [Youtiao](https://github.com/zenazn/youtiao) — a Svelte 5 + Bun web framework.
+
+## Getting Started
+
+```bash
+bun install
+bunx youtiao dev
+```
+
+Open http://localhost:3000. The dev server recompiles on every request.
+
+## Project Structure
+
+```
+src/
+  routes/
+    +index.svelte       # Home page (/)
+    about.svelte        # /about
+    +layout.svelte      # Root layout (optional)
+    +error.svelte       # Error boundary (optional)
+  server.ts             # GraphPC API
+```
+
+## Pages
+
+Pages are `.svelte` files in `src/routes/`. Every page receives `rpc` and `params` as props:
+
+```svelte
+<script>
+  let { rpc, params } = $props();
+</script>
+```
+
+### Routing
+
+| File | Route |
+|------|-------|
+| `+index.svelte` | Directory index |
+| `about.svelte` | `/about` |
+| `posts/[id].svelte` | `/posts/:id` (dynamic) |
+| `files/[*].svelte` | `/files/*` (catch-all) |
+| `+layout.svelte` | Wraps all pages in that directory (nests) |
+| `+error.svelte` | Catches errors from child pages |
+
+### Layouts
+
+A `+layout.svelte` wraps all pages in its directory and below. Layouts nest.
+
+```svelte
+<script>
+  let { children } = $props();
+</script>
+
+<nav>...</nav>
+<main>{@render children()}</main>
+```
+
+## RPC
+
+Your API lives in `src/server.ts`, built with [GraphPC](https://github.com/zenazn/graphpc) — a typed RPC library where the API is a navigable object graph. Define classes extending `Node`, decorate methods and edges, export `createRpcRoot(ctx)` for SSR, and optionally export `getRequestContext(req)` when you need auth or request-scoped context.
+
+```ts
+import { Node, edge, method, createServer } from "graphpc";
+import { z } from "zod";
+
+class Post extends Node {
+  id: string;
+  title: string;
+
+  constructor(id: string) {
+    super();
+    Object.assign(this, db.posts.get(id));
+  }
+
+  @method(z.string())
+  async updateTitle(title: string) {
+    await db.posts.update(this.id, { title });
+  }
+}
+
+class Posts extends Node {
+  @edge(Post, z.string())
+  get(id: string) { return new Post(id); }
+
+  @method
+  async count() { return db.posts.count(); }
+}
+
+export class Api extends Node {
+  @edge(Posts)
+  get posts() { return new Posts(); }
+}
+
+export function getRequestContext(_req: Request) {
+  return {};
+}
+
+export function createRpcRoot(_ctx: {}) {
+  return new Api();
+}
+
+export const server = createServer({}, createRpcRoot);
+```
+
+Then use it in any page — edge navigation is synchronous, data access and methods are awaited:
+
+```svelte
+<script>
+  let { rpc } = $props();
+  const post = rpc.posts.get("1");   // sync — no network call
+  const { id, title } = await post;  // fetches data
+  // await post.updateTitle("New");   // calls method
+</script>
+
+<h1>{title}</h1>
+```
+
+During SSR, RPC calls execute against `createRpcRoot(ctx)`. For WebSocket connections, `getRequestContext(req)` derives context from the upgrade request, which is then passed to `createRpcRoot(ctx)`. On the client, RPC calls use a WebSocket to `/rpc`, and hydration data is embedded in the HTML so the client doesn't re-fetch on load.
+
+### Validation
+
+GraphPC uses [Standard Schema](https://standardschema.dev/) for parameter validation — pass schemas to `@method()` and `@edge()`. [Zod](https://zod.dev/) is included, but any Standard Schema-compatible library works (valibot, arktype, etc.).
+
+## Production Build
+
+```bash
+bunx youtiao build
+./dist/app
+```
+
+Compiles all routes, generates optimized client assets, and produces a single binary.
+
+## Learn More
+
+- [Youtiao docs](https://github.com/zenazn/youtiao#readme)
+- [GraphPC docs](https://github.com/zenazn/graphpc#readme)
+- [Svelte 5 docs](https://svelte.dev/docs)
+- [Bun docs](https://bun.sh/docs)

package/template/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "my-youtiao-app",
+  "version": "0.0.1",
+  "type": "module",
+  "dependencies": {
+    "youtiao": "^0.1.0",
+    "graphpc": "^0.9.3",
+    "svelte": "^5.53.13",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/template/src/routes/+index.svelte

@@ -0,0 +1,16 @@
+<script>
+  let { rpc } = $props();
+  const greeting = await rpc.hello("world");
+</script>
+
+<h1>Welcome to Youtiao</h1>
+<p>{greeting}</p>
+
+<nav>
+  <a href="/about">About</a>
+</nav>
+
+<style>
+  h1 { color: #e65100; }
+  nav { margin-top: 1rem; }
+</style>

package/template/src/routes/about.svelte

@@ -0,0 +1,6 @@
+<h1>About</h1>
+<p>Built with <a href="https://github.com/zenazn/youtiao">Youtiao</a> — a Svelte 5 + Bun web framework.</p>
+
+<nav>
+  <a href="/">Home</a>
+</nav>

package/template/src/server.ts

@@ -0,0 +1,18 @@
+import { createServer, Node, method } from "graphpc";
+
+export class Api extends Node {
+  @method
+  async hello(name: string): Promise<string> {
+    return `Hello, ${name}!`;
+  }
+}
+
+export function getRequestContext(_req: Request) {
+  return {};
+}
+
+export function createRpcRoot(_ctx: {}) {
+  return new Api();
+}
+
+export const server = createServer({}, createRpcRoot);

package/template/svelte.config.js

@@ -0,0 +1,5 @@
+export default {
+  compilerOptions: {
+    experimental: { async: true },
+  },
+};

package/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "allowJs": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}

package/template/youtiao.config.ts

@@ -0,0 +1,11 @@
+// import type { YoutiaConfig } from "youtiao";
+
+// export default {
+//   routes: "src/routes",
+//   output: "dist",
+//   rpc: "src/server.ts",
+//   binaryName: "app",
+//   server: {
+//     port: 3000,
+//   },
+// } satisfies YoutiaConfig;