create-rivet 0.0.0-stage → 0.1.0-alpha.0

package/main.js

@@ -0,0 +1,169 @@
+// The create-rivet command: arguments (node:util parseArgs), questions (./prompt.ts), then ./index.ts does the work.
+//   npm create rivet@latest [dir] [-- --template <id>] [--yes] [--no-install] [--no-git] …
+import { basename, relative, resolve } from "node:path";
+import { parseArgs, styleText } from "node:util";
+import { commands, createProject, detectPackageManager, findTemplate, initGit, installDependencies, isEmptyDir, isFile, ownVersion, PACKAGE_MANAGERS, TEMPLATES, toPackageName, validatePackageName, } from "./index.js";
+import { DEPLOY_TARGETS, deployOverlay, deployProblem, findDeployTarget } from "./deploy.js";
+import { closePrompts, confirm, PromptCancelled, select, text } from "./prompt.js";
+export const HELP = `Create a Rivet app.
+
+Usage:
+  npm create rivet@latest [dir] [-- options]
+  pnpm create rivet [dir] [options]   yarn create rivet [dir] [options]   bun create rivet [dir] [options]
+
+Options:
+  -t, --template <id>     ${TEMPLATES.map((t) => t.id).join(" | ")} (asked when omitted; default static)
+  -d, --deploy <target>   ${DEPLOY_TARGETS.map((t) => t.id).join(" | ")} (default: none = Node server / static files)
+  -n, --name <name>       package.json name (default: the folder name)
+  -y, --yes               accept the defaults, ask nothing
+      --install / --no-install   install dependencies (default: yes)
+      --git / --no-git           git init + first commit (default: yes)
+      --pm <name>         ${PACKAGE_MANAGERS.join(" | ")} (default: the one running create, else npm)
+      --rivet-version <spec>     @rivetjs/* dependency spec (default: this release)
+  -f, --force             write into a folder that is not empty
+  -h, --help              this text
+  -v, --version           create-rivet version
+
+Templates:
+${TEMPLATES.map((t) => `  ${t.id.padEnd(9)} ${t.label}: ${t.hint}`).join("\n")}
+`;
+/** Runs the command; resolves with the exit code (0 ok, 1 error, 130 cancelled). */
+export async function main(argv, io) {
+    let args;
+    try {
+        args = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            allowNegative: true,
+            options: {
+                template: { type: "string", short: "t" },
+                deploy: { type: "string", short: "d" },
+                name: { type: "string", short: "n" },
+                yes: { type: "boolean", short: "y" },
+                install: { type: "boolean" },
+                git: { type: "boolean" },
+                pm: { type: "string" },
+                "rivet-version": { type: "string" },
+                force: { type: "boolean", short: "f" },
+                help: { type: "boolean", short: "h" },
+                version: { type: "boolean", short: "v" },
+            },
+        });
+    }
+    catch (error) {
+        io.error.write(`${error.message}\n\n${HELP}`);
+        return 1;
+    }
+    const { values, positionals } = args;
+    const paint = (format, value) => styleText(format, value, { stream: io.output });
+    if (values.help)
+        return (io.output.write(HELP), 0);
+    if (values.version)
+        return (io.output.write(ownVersion() + "\n"), 0);
+    if (positionals.length > 1)
+        return fail(io, `Expected one folder, got ${positionals.join(" ")}`);
+    if (values.template && !findTemplate(values.template))
+        return fail(io, `Unknown template "${values.template}" (${TEMPLATES.map((t) => t.id).join(", ")})`);
+    if (values.deploy && !findDeployTarget(values.deploy))
+        return fail(io, `Unknown deploy target "${values.deploy}" (${DEPLOY_TARGETS.map((t) => t.id).join(", ")})`);
+    if (values.pm && !PACKAGE_MANAGERS.includes(values.pm))
+        return fail(io, `Unknown package manager "${values.pm}" (${PACKAGE_MANAGERS.join(", ")})`);
+    if (values.name && validatePackageName(values.name))
+        return fail(io, `--name: ${validatePackageName(values.name)}`);
+    // Questions only on a terminal and without --yes; otherwise every missing answer takes its default.
+    const ask = !values.yes && Boolean(io.input.isTTY);
+    try {
+        io.output.write(`\n${paint(["bold", "blue"], "create-rivet")} ${paint("dim", "v" + ownVersion())}\n\n`);
+        let name = values.name;
+        let folder = positionals[0];
+        if (!folder) {
+            const answer = ask
+                ? await text(io, "Project name:", "rivet-app", (value) => validatePackageName(toPackageName(value)) && "Not a usable name")
+                : "rivet-app";
+            folder = answer;
+            name ??= toPackageName(basename(answer));
+        }
+        const dir = resolve(io.cwd, folder);
+        name ??= toPackageName(basename(dir));
+        if (isFile(dir))
+            return fail(io, `${folder} is a file`);
+        if (!isEmptyDir(dir) && !values.force) {
+            if (!ask)
+                return fail(io, `${folder} is not empty (use --force to write into it)`);
+            if (!(await confirm(io, `${folder} is not empty. Write into it anyway (files with the same names are replaced)?`, false)))
+                return cancelled(io);
+        }
+        const template = (values.template
+            ? findTemplate(values.template).id
+            : ask
+                ? await select(io, "Template:", TEMPLATES.map((t) => ({ value: t.id, label: t.label, hint: t.hint })))
+                : "static");
+        let deploy = values.deploy;
+        if (deploy && deployProblem(deploy, template))
+            return fail(io, deployProblem(deploy, template));
+        if (!deploy && ask) {
+            const choices = [
+                { value: "none", label: "None", hint: template === "server" ? "Node server (serve.js, Dockerfile)" : "static files (dist/client)" },
+                ...DEPLOY_TARGETS.filter((t) => !deployProblem(t.id, template)).map((t) => ({ value: t.id, label: t.label, hint: t.hint })),
+            ];
+            const answer = await select(io, "Deploy target:", choices);
+            if (answer !== "none")
+                deploy = answer;
+        }
+        const pm = (values.pm ?? detectPackageManager(io.env["npm_config_user_agent"]));
+        const install = values.install ?? (ask ? await confirm(io, `Install dependencies with ${pm}?`, true) : true);
+        const git = values.git ?? (ask ? await confirm(io, "Initialise a git repository?", true) : true);
+        closePrompts(io);
+        const created = createProject({
+            dir,
+            template,
+            name,
+            ...(values["rivet-version"] ? { rivetVersion: values["rivet-version"] } : {}),
+            ...(deploy ? { overlays: [deployOverlay(deploy, pm)] } : {}),
+        });
+        io.output.write(`${paint("green", "Created")} ${created.name} (${findTemplate(template).label}${deploy ? ", " + findDeployTarget(deploy).label : ""}) in ${dir} — ${created.files.length} files\n`);
+        const run = commands(pm);
+        let installed = false;
+        if (install) {
+            io.output.write(`\n${paint("dim", "$ " + run.install)}\n`);
+            installed = installDependencies(dir, pm);
+            if (!installed)
+                io.error.write(paint("yellow", `\n${run.install} failed; run it yourself in ${folder}.\n`));
+        }
+        if (git) {
+            const result = initGit(dir);
+            if (result === "committed")
+                io.output.write(`${paint("green", "Git")} repository created with a first commit\n`);
+            else if (result === "created")
+                io.output.write(`${paint("green", "Git")} repository created (files staged; no commit: set git user.name / user.email)\n`);
+            else if (result === "inside-repo")
+                io.output.write(`${paint("dim", "Git: already inside a repository, skipped")}\n`);
+            else
+                io.output.write(`${paint("dim", "Git: not available, skipped")}\n`);
+        }
+        const cd = relative(io.cwd, dir) || ".";
+        io.output.write(`\nNext:\n`);
+        if (cd !== ".")
+            io.output.write(`  cd ${cd.includes(" ") ? JSON.stringify(cd) : cd}\n`);
+        if (!installed)
+            io.output.write(`  ${run.install}\n`);
+        io.output.write(`  ${run.run("dev")}\n\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof PromptCancelled)
+            return cancelled(io);
+        return fail(io, error.message);
+    }
+    finally {
+        closePrompts(io);
+    }
+}
+function fail(io, message) {
+    io.error.write(styleText("red", "Error: ", { stream: io.error }) + message + "\n");
+    return 1;
+}
+function cancelled(io) {
+    io.error.write("Cancelled.\n");
+    return 130;
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "create-rivet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Create a Rivet app: npm create rivet@latest",
+  "keywords": [
+    "rivet",
+    "create",
+    "starter",
+    "template",
+    "jsx",
+    "ssr",
+    "resumable"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./deploy": {
+      "types": "./deploy.d.ts",
+      "default": "./deploy.js"
+    }
+  },
+  "bin": {
+    "create-rivet": "./cli.js"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/N1XUS/rivetjs.git",
+    "directory": "libs/create-rivet"
+  },
+  "homepage": "https://github.com/N1XUS/rivetjs/tree/main/libs/create-rivet#readme",
+  "bugs": {
+    "url": "https://github.com/N1XUS/rivetjs/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "cli.d.ts",
+    "cli.js",
+    "deploy.d.ts",
+    "deploy.js",
+    "index.d.ts",
+    "index.js",
+    "main.d.ts",
+    "main.js",
+    "prompt.d.ts",
+    "prompt.js",
+    "templates"
+  ]
+}

package/prompt.d.ts

@@ -0,0 +1,24 @@
+export interface PromptIO {
+    input: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+        setRawMode?: (mode: boolean) => unknown;
+    };
+    output: NodeJS.WritableStream;
+}
+/** Thrown when the user cancels (Ctrl+C, Ctrl+D / end of input). */
+export declare class PromptCancelled extends Error {
+    constructor();
+}
+/** Releases the input stream (end of the prompts: lets the process exit). */
+export declare function closePrompts(io: PromptIO): void;
+/** Free text; `validate` returns an error message to ask again. */
+export declare function text(io: PromptIO, question: string, fallback: string, validate?: (value: string) => string | undefined): Promise<string>;
+/** Yes / no. */
+export declare function confirm(io: PromptIO, question: string, fallback: boolean): Promise<boolean>;
+export interface Choice<T extends string> {
+    value: T;
+    label: string;
+    hint?: string;
+}
+/** One of `choices`: arrow keys + Enter on a TTY, else a number (or a value) typed on a line. */
+export declare function select<T extends string>(io: PromptIO, question: string, choices: readonly Choice<T>[], initial?: number): Promise<T>;

package/prompt.js

@@ -0,0 +1,127 @@
+// Tiny terminal prompts on node:readline (no dependencies): text, yes/no, and a choice list (arrow keys on a
+// TTY, a numbered answer otherwise). Every prompt takes its streams, so tests drive them with PassThrough.
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
+import { styleText } from "node:util";
+/** Thrown when the user cancels (Ctrl+C, Ctrl+D / end of input). */
+export class PromptCancelled extends Error {
+    constructor() {
+        super("cancelled");
+    }
+}
+const color = (format, text, io) => styleText(format, text, { stream: io.output });
+const readers = new WeakMap();
+/** One line reader per input stream (a reader per question would drop lines buffered after the first). */
+function reader(io) {
+    let current = readers.get(io.input);
+    if (current)
+        return current;
+    const rl = createInterface({ input: io.input, terminal: false });
+    const queue = [];
+    const waiters = [];
+    const push = (value) => (waiters.length ? waiters.shift()(value) : queue.push(value));
+    rl.on("line", push);
+    rl.on("close", () => push(null));
+    current = {
+        close: () => (readers.delete(io.input), rl.close()),
+        next: () => (queue.length ? Promise.resolve(queue.shift()) : new Promise((resolve) => waiters.push(resolve))),
+    };
+    readers.set(io.input, current);
+    return current;
+}
+/** Releases the input stream (end of the prompts: lets the process exit). */
+export function closePrompts(io) {
+    readers.get(io.input)?.close();
+}
+/** Reads one line (trimmed). */
+async function line(question, io) {
+    io.output.write(question);
+    const answer = await reader(io).next();
+    if (answer === null)
+        throw new PromptCancelled();
+    return answer.trim();
+}
+/** Free text; `validate` returns an error message to ask again. */
+export async function text(io, question, fallback, validate) {
+    for (;;) {
+        const value = (await line(`${color("cyan", "?", io)} ${question} ${color("dim", `(${fallback})`, io)} `, io)) || fallback;
+        const error = validate?.(value);
+        if (!error)
+            return value;
+        io.output.write(`  ${color("red", error, io)}\n`);
+    }
+}
+/** Yes / no. */
+export async function confirm(io, question, fallback) {
+    for (;;) {
+        const value = (await line(`${color("cyan", "?", io)} ${question} ${color("dim", fallback ? "(Y/n)" : "(y/N)", io)} `, io)).toLowerCase();
+        if (!value)
+            return fallback;
+        if (value === "y" || value === "yes")
+            return true;
+        if (value === "n" || value === "no")
+            return false;
+    }
+}
+/** One of `choices`: arrow keys + Enter on a TTY, else a number (or a value) typed on a line. */
+export async function select(io, question, choices, initial = 0) {
+    const { input, output } = io;
+    if (!input.isTTY || !input.setRawMode) {
+        output.write(`${color("cyan", "?", io)} ${question}\n`);
+        choices.forEach((choice, i) => output.write(`  ${i + 1}. ${choice.label}${choice.hint ? color("dim", ` - ${choice.hint}`, io) : ""}\n`));
+        for (;;) {
+            const value = await line(`  ${color("dim", `number (${initial + 1})`, io)} `, io);
+            if (!value)
+                return choices[initial].value;
+            const byValue = choices.find((choice) => choice.value === value);
+            if (byValue)
+                return byValue.value;
+            const index = Number(value) - 1;
+            if (Number.isInteger(index) && choices[index])
+                return choices[index].value;
+        }
+    }
+    let index = initial;
+    const render = (first) => {
+        if (!first)
+            output.write(`\x1b[${choices.length}A`);
+        choices.forEach((choice, i) => {
+            const active = i === index;
+            const label = active ? color(["cyan", "bold"], `> ${choice.label}`, io) : `  ${choice.label}`;
+            output.write(`\x1b[2K${label}${choice.hint ? color("dim", ` - ${choice.hint}`, io) : ""}\n`);
+        });
+    };
+    // Raw keypresses: the line reader must not consume them.
+    closePrompts(io);
+    output.write(`${color("cyan", "?", io)} ${question} ${color("dim", "(arrow keys, Enter)", io)}\n`);
+    render(true);
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume();
+    try {
+        return await new Promise((resolve, reject) => {
+            const onKey = (_, key = {}) => {
+                if (key.ctrl && (key.name === "c" || key.name === "d"))
+                    return done(() => reject(new PromptCancelled()));
+                if (key.name === "up" || key.name === "k")
+                    index = (index - 1 + choices.length) % choices.length;
+                else if (key.name === "down" || key.name === "j")
+                    index = (index + 1) % choices.length;
+                else if (key.name === "return" || key.name === "enter")
+                    return done(() => resolve(choices[index].value));
+                else
+                    return;
+                render(false);
+            };
+            const done = (settle) => {
+                input.off("keypress", onKey);
+                settle();
+            };
+            input.on("keypress", onKey);
+        });
+    }
+    finally {
+        input.setRawMode(false);
+        input.pause();
+    }
+}

package/templates/starter-minimal/.agents/skills/rivet-add-route/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter-minimal/.agents/skills/rivet-add-route/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: rivet-add-route
+description: "Add a page or endpoint to a Rivet app with file routes, server data (serverLoad), actions, head and layouts. Use when the user asks for a new page, URL, route, endpoint or loader in a Rivet project."
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/add-route.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Add a route to a Rivet app
+
+1. Pick the file under `src/routes/` (URL = path): `about.tsx` → `/about`, `blog/[slug].tsx` → `/blog/:slug`, `docs/[[lang]]/x.tsx` (optional param), `files/[...path].tsx` (rest), `(group)/p.tsx` → `/p` (shares the group's `_layout.tsx`), `api/time.ts` → endpoint (`export const onGet = () => Response.json(…)`). `_layout.tsx` wraps its folder; `_404.tsx` / `_error.tsx` handle misses / errors. Look up details with `get_doc("docs:/guides/routing/file-routes/")`.
+2. Write the page. Server code lives in `server…` exports (stripped from the browser build):
+
+```tsx
+import { notFound, type PageProps, type RequestEvent } from "@rivetjs/router";
+
+export const serverLoad = async ({ params }: RequestEvent<"blog/[slug]">) => {
+  const post = await findPost(params.slug); // server-only: database, files, secrets
+  if (!post) throw notFound();
+  return { post };
+};
+
+export const head = { title: "Post" };
+
+export default function Post({ data }: PageProps<"blog/[slug]">) {
+  return <h1 class="text-2xl">{data.post.title}</h1>;
+}
+```
+
+- Page props `data`, `params`, `url` are plain values; in `_layout.tsx` (`LayoutProps`) they are accessors: `data()`, `params()`, `url()`, plus `children`.
+- Mutations: `export const serverActions = { name: async ({ request }) => … }` + `<form method="post" action="?/name">`; with validation use `@rivetjs/forms` (`action(def, fn)` from `@rivetjs/forms/server`).
+- Access checks: `serverGuard` (throw / return `redirect()`, `deny()`, `notFound()`).
+- Static mode (`rivetRouter({ mode: "static" })`): `serverLoad` runs at build time; dynamic `[param]` pages list their params in `serverEntries`.
+- Server-only helpers go in `*.server.ts` files (browser code cannot import them: RV3008).
+
+3. Link to it: plain `<a href="/blog/hello">` (client navigation), or typed `<Link to="/blog/hello">` from `@rivetjs/router/link`; programmatic `navigate()` from `@rivetjs/router/client`.
+4. Run `npm run check` (`rivet sync` regenerates the typed routes in `.rivet/`, `rivet-check` reports `RV` codes; RV3101 = a link matches no route). Fix every diagnostic (`explain_diagnostic(code)`), then `npm run build`.

package/templates/starter-minimal/.agents/skills/rivet-add-ui-page/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter-minimal/.agents/skills/rivet-add-ui-page/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: rivet-add-ui-page
+description: "Build a page or component from @rivetjs/ui components - correct subpath imports, compound parts, two-way signal props, styles and lucide icons. Use when the user asks for UI built with Rivet UI components (buttons, selects, modals, cards, forms) in a Rivet app."
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/add-ui-page.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Page with @rivetjs/ui components
+
+1. Setup (the `ui` starter has it): dependencies `@rivetjs/ui`, `@rivetjs/kit`, `lucide`; `src/styles.css` = `@import "tailwindcss";` then `@import "@rivetjs/ui/styles";` (other looks: `@rivetjs/ui/theme` presets, variables pasted after it).
+2. For every component: `get_component("Select")` (import path, parts, props, example source) or `get_doc("ui:/components/select/")`. Copy the structure of the docs example, not React component-library code.
+3. Rules that differ from React component libraries:
+   - Subpath imports: `import { Select } from "@rivetjs/ui/select"`, `import { ListBox } from "@rivetjs/ui/list-box"`, `import { Label } from "@rivetjs/ui/label"`.
+   - `class`, not `className`. Events follow React Aria: `onPress`, `onSelectionChange`, `onOpenChange`.
+   - Two-way props take a signal: `isOpen={open}`, `value={selected}`, `selectedKeys={keys}`; a plain value is one-way.
+   - Render props are accessors: `({ isPlaceholder }) => (isPlaceholder() ? … : …)`.
+   - Icons: `<Icon icon={ChevronDown} />` (`@rivetjs/kit/icon` + lucide); never inline SVG paths or Unicode glyphs.
+
+```tsx
+import { signal } from "@rivetjs/reactivity";
+import { Button } from "@rivetjs/ui/button";
+import { Modal } from "@rivetjs/ui/modal";
+
+export default function Page() {
+  const open = signal(false);
+  return (
+    <>
+      <Button onPress={() => open.set(true)}>Open</Button>
+      <Modal.Content isOpen={open}>
+        <Modal.Header>Title</Modal.Header>
+        <Modal.Body>…</Modal.Body>
+        <Modal.Footer>
+          <Button slot="close">Close</Button>
+        </Modal.Footer>
+      </Modal.Content>
+    </>
+  );
+}
+```
+
+4. Custom-styled widget instead: the headless `@rivetjs/cdk/<module>` (same parts, `rv-*` classes + `data-*` state, no styles).
+5. `check_code`, `npm run check`, then look at it in `npm run dev` (overlays render in a portal on the div overlay layer, never native `<dialog>` / `popover`).

package/templates/starter-minimal/.agents/skills/rivet-fix-resumability-error/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter-minimal/.agents/skills/rivet-fix-resumability-error/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: rivet-fix-resumability-error
+description: 'Diagnose and fix Rivet resumability errors - RV2xxx compiler diagnostics, RV1016 handler errors, "is not serializable" / "Cannot resume" build or prerender errors, browser globals during server rendering, state that resets after the first click. Use when a Rivet build, check or page fails with such an error.'
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/fix-resumability-error.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Fix a resumability error
+
+A Rivet page is rendered on the server and resumed in the browser: handlers, bindings and client effects run there with the values they capture, which the server serialized into the HTML. Errors come from code that cannot cross that line.
+
+1. Get the exact diagnostic: `npm run check` (`file:line:col - error RVnnnn`), the Vite overlay (`[RVnnnn] file:line:col`), or `check_code(source, filename)`. For the fix: `explain_diagnostic("RVnnnn")`; `check_code` also returns the quick-fixed source when one applies.
+2. Common codes:
+   - RV2001 browser global (`window`, `document`, `localStorage`) read during server rendering → move it into a handler, `clientEffect(() => …)`, `clientEvent(window, "resize", …)` or `clientOnly(() => import("…"))`.
+   - RV2003 captured class instance (`new Intl.NumberFormat`, an SDK client) → capture plain data; create the object inside the handler or `clientEffect`, or build it with `reconstruct(() => new X(…))` from `@rivetjs/runtime/dom` (the browser runs the factory on first read). A data class declared in the component module (plain fields) resumes as is.
+   - RV2102 captured instance of a module class that cannot resume as data (`#private` field, a decorator, a field arrow using `super`, a base that is not a data class of the module, `window` / `document` / `WebSocket` read while constructing) → create it inside the handler, build it with `reconstruct(() => new X(…))`, keep only plain fields, or add `[serialize]()` + `static [revive](data)` (from `@rivetjs/runtime/resume-format`; package classes: `registerClass(Cls, { id, serialize, revive })` in a module imported by the server code and the resume entry). At render, `RV2102: X has [serialize] but no static [revive]` → add the `static [revive]`.
+   - RV1016 handler expression reads state when it binds (`onClick={a() ? f : g}`) → wrap: `onClick={(e) => (a() ? f(e) : g(e))}`.
+   - RV2002 ref callback must assign a local → `ref={(el) => (local = el)}` or `const el = ref()` + `ref={el}`.
+   - RV2006 JSX inside a handler / effect / computed → render JSX in the component, switch it with a signal.
+   - RV2007 `this` in resumable code → `event.currentTarget`.
+   - RV2009 two module references share a browser name (two imports of different modules under one name) → rename one import (`import { fmt as fmtDate } from …`).
+   - RV2101 (warning, type-aware) a captured value's type does not serialize → as RV2003.
+3. Build / prerender error `Cannot resume <file>#<Component>$<hash>: function is not serializable` (dev server: ``capture `<name>` function is not serializable``; dev build: `capture #<i> …`): a captured function Rivet did not compile (created at runtime by a library such as `memoize(fn)`, a `.bind(…)` written inside an object literal (keep `const inc = add.bind(null, 2)` in a local constant and store `inc`; `.bind(ctx)` of a function using `this` stays RV2007), a method, or held by an object built outside a component: at module level such as `const table = { format: formatEuro }`, or by your own hook / helper such as `function useFormat() { return { format: formatEuro }; }`). Wrap it in an inline arrow, or build the object inside the component (module-level and imported functions used by name there resume by reference). A library object holding functions (a chart, editor, socket client from a package): build it with `reconstruct(() => createChart(…))` from `@rivetjs/runtime/dom` — no value in the page, the browser runs the factory on first read (module level: one server instance per process, never read request state in it). A class instance at render (`X instance is not serializable`): your class → `reconstruct(() => new X(…))` or `[serialize]()` + `static [revive](data)`; a package class → `registerClass(X, { id, serialize, revive })` from `@rivetjs/runtime/resume-format`. `NODE_ENV=development vite build` names the value path. Rules: `get_doc("docs:/best-practices/serializable-captures/")`.
+4. State resets on the first change after resume: a child destructures its props (`function C({ value })`) and is re-created → read `props.value`. Copies of `props.children` in a local are not tracked → render `{props.children}` directly.
+5. `.ts` module importing `@rivetjs/runtime/dom` (bundles the DOM runtime into SSR) → move that code into a `.tsx` file.
+6. Re-run `npm run check` and `npm run build` (prerender exercises serialization); both must be clean.

package/templates/starter-minimal/.agents/skills/rivet-form-in-drawer/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denys Severyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/starter-minimal/.agents/skills/rivet-form-in-drawer/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: rivet-form-in-drawer
+description: 'Build a validated form inside a drawer or dialog on a Rivet live page, so a submit updates the list behind it in place, keeps the overlay open on errors and works without JavaScript. Use for "add/edit X in a drawer/modal/dialog" tasks in a Rivet project.'
+---
+
+<!-- Generated by libs/mcp/ai/sync.ts from libs/mcp/ai/skills/form-in-drawer.md in the Rivet repository: edit the source there and run the script. In an app created from a starter this file is yours to edit. -->
+
+# Form in a drawer with a live page
+
+Reference implementation: `get_doc("docs:/guides/forms/forms-in-overlays/")` (example `docs:/examples/drawer-form/`). Read it first; the steps below are its shape.
+
+1. Define the form once, shared by page and action (any Standard Schema library):
+
+```ts
+// src/forms/customer.ts
+import { defineForm } from "@rivetjs/forms";
+import { z } from "zod";
+export const customerForm = defineForm({ name: "customer", schema: z.object({ name: z.string().min(1), email: z.string().email() }) });
+```
+
+2. Make the page live and add the action:
+
+```tsx
+import type { LivePageProps } from "@rivetjs/router";
+import { actionResult } from "@rivetjs/router/client";
+import { action, invalid } from "@rivetjs/forms/server";
+
+export const live = true; // data is an accessor, refreshed in place after a submit: signals (open drawer, input, focus) survive
+export const serverLoad = ({ url }: { url: URL }) => ({ customers: [...customers], creating: url.searchParams.has("new") });
+export const serverActions = {
+  customer: action(customerForm, (value) => {
+    if (customers.some((c) => c.email === value.email)) return invalid({ email: "Already a customer" });
+    customers.push({ id: customers.length + 1, ...value });
+  }),
+};
+export default function Customers({ data }: LivePageProps<typeof serverLoad>) {
+  /* … */
+}
+```
+
+3. In the component: `const result = actionResult("customer")`, `const open = signal(data().creating || (result?.status ?? 0) >= 400)` (no-JS entry: `<a href="?new" onClick={(e) => { e.preventDefault(); open.set(true); }}>`), `const form = createForm(customerForm, { result })`. Render the list from `data()` with `<For each={data().customers} by={(c) => c.id}>`; never copy `data()` into a signal.
+4. The overlay: `@rivetjs/ui` (`Drawer` / `Modal`, `isOpen={open}`) or cdk `ModalOverlay isDismissable isOpen={open}` + `Modal` + `Dialog` (div overlay layer, two-way `isOpen`). The form inside:
+
+```tsx
+<form id={formId(form)} method="post" action="?/customer" onSubmit={async (event) => (await onSubmit(customerForm, form, event)) && open.set(false)}>
+  <label for={fieldId(form, "email")}>Email</label>
+  <input
+    id={fieldId(form, "email")}
+    name="email"
+    value={defaultValue(form, "email")}
+    aria-invalid={isInvalid(form, "email")}
+    aria-describedby={describedBy(form, "email")}
+  />
+  <FieldError of={form} name="email" />
+  <button aria-disabled={submitting(form) ? "true" : undefined}>Save</button>
+</form>
+```
+
+`onSubmit` resolves true once the server accepted the form and the page data is fresh: close the drawer then. Errors stay in the open drawer. Imports: `createForm, defaultValue, describedBy, fieldId, formId, isInvalid, onSubmit, submitting` from `@rivetjs/forms`, `FieldError` from `@rivetjs/forms/components`.
+
+5. A layout `serverLoad` re-runs too (counts in headers update).
+6. Check: `check_code` on the page, `npm run check`, then try it with JavaScript disabled (plain POST, 400 re-render with the drawer open).