@rshono/create 1.0.0-rc.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@rshono/create",
+  "version": "1.0.0-rc.0",
+  "description": "Scaffold a new rshono app — Hono + Rspack + React Server Components",
+  "author": "Lasse <lasse@lassetange.com> (https://www.lassetange.com)",
+  "license": "ISC",
+  "keywords": [
+    "create",
+    "scaffold",
+    "starter",
+    "rshono",
+    "react-server-components",
+    "hono",
+    "rspack"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rshono/rshono.git",
+    "directory": "packages/create"
+  },
+  "bugs": {
+    "url": "https://github.com/rshono/rshono/issues"
+  },
+  "homepage": "https://github.com/rshono/rshono",
+  "type": "module",
+  "bin": {
+    "create-rshono": "./bin/create-rshono.mjs"
+  },
+  "exports": {
+    ".": "./dist/api.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/codegen.mjs && node scripts/build.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "codegen": "node scripts/codegen.mjs",
+    "typecheck": "node scripts/codegen.mjs && tsc --noEmit",
+    "test": "npm run build && node --test --test-concurrency=1 \"test/*.test.mjs\"",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@rspack/core": "2.1.5",
+    "@types/node": "^26.1.1",
+    "@rshono/core": "workspace:*",
+    "typescript": "^7.0.2"
+  }
+}

package/templates/base/README.md

@@ -0,0 +1,42 @@
+# **PROJECT_NAME**
+
+A [rshono](https://github.com/rshono/rshono) app — [Hono](https://hono.dev) + [Rspack](https://rspack.rs) + [React Server Components](https://react.dev/reference/rsc/server-components).
+
+```bash
+__PM_RUN__ dev        # dev server with HMR, http://localhost:3000
+__PM_RUN__ build      # production build for __DEPLOY_TARGET__
+__PM_RUN__ typecheck  # tsc --noEmit
+```
+
+`package.json` has the rest, including whatever your formatter and linter added.
+
+## Layout
+
+```
+rshono.config.ts   deploy target, security and build settings
+public/            served verbatim at the web root (favicon.svg → /favicon.svg)
+src/
+  routes.ts        the route table — the one file rshono requires
+  server.ts        a Hono app: middleware, API routes, redirects, error reporting
+  actions.ts       'use server' functions the browser can call
+  components/      pages and components
+  lib/             everything else
+  styles.css       imported by the layout, so it loads with the page
+```
+
+Pages are **server components**: they render the whole document, may be `async`, and await data directly.
+Interactive parts are `'use client'` components a page imports — only those ship JavaScript.
+
+## Environment
+
+`.env` holds committed defaults; `.env.local` overrides it and is gitignored. Only `PUBLIC_`-prefixed
+variables reach the browser — everything else is server-only, and a stray read of it in client code
+compiles to `undefined` rather than shipping. `src/lib/env.ts` is where both sides are read.
+
+## Deploying
+
+This app is built for `__DEPLOY_TARGET__`: after `__PM_RUN__ build`, **DEPLOY_HINT**.
+
+Change `deploy` in `rshono.config.ts` to target somewhere else, or build for one place without editing the
+file: `rshono build --deploy vercel`, or `RSHONO_DEPLOY=vercel` in CI. `dev` always runs the Node dev
+server, whatever the target — it is a property of the build, not of developing.

package/templates/base/_env

@@ -0,0 +1,9 @@
+# Committed defaults — safe to share, and the values a fresh clone starts with.
+#
+# Secrets go in `.env.local`, which is gitignored and loaded first, so a value there wins over this
+# file. The real environment wins over both.
+#
+# Only `PUBLIC_`-prefixed variables are compiled into the browser bundle. Anything else is server-only:
+# a stray read of it in client code compiles to `undefined` rather than shipping.
+
+PUBLIC_APP_NAME="__PROJECT_NAME__"

package/templates/base/_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.DS_Store
+
+# Secrets. `.env` is committed with defaults; `.env.local` overrides it and stays out of git.
+.env.local
+.env.*.local

package/templates/base/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><title>Lightning bolt</title><text y=".9em" font-size="90">⚡</text></svg>

package/templates/base/public/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Allow: /

package/templates/base/rshono.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig } from '@rshono/core';
+
+/**
+ * Every field is optional — delete this file to accept all the defaults. The commented lines are the
+ * defaults, kept as documentation of what is there to change.
+ *
+ * The framework settings are compiled into the server bundle at build time, so changing one means a
+ * rebuild; there is no env-var interface for them. `--port`/`PORT` and `HOST` are the two exceptions,
+ * and they win over what is written here.
+ */
+export default defineConfig({
+  /** Where `build` targets. Overridable per build with `--deploy` or `RSHONO_DEPLOY`. */
+  deploy: '__DEPLOY_TARGET__',
+
+  // The public origin, baked into prerendered pages' absolute URLs. Set it if you use `render: 'static'`
+  // and build canonical tags, `og:url` or absolute links — there is no request to read a Host from.
+  // siteUrl: 'https://example.com',
+
+  // port: 3000,          // default for dev/start
+  // host: '0.0.0.0',     // bind address for start
+
+  // trustProxy: false,   // honour X-Forwarded-Host/-Proto — only behind a proxy you control
+  // checkOrigin: true,   // CSRF origin check on server-action POSTs
+  // allowedOrigins: [],  // extra origins allowed to post actions
+  // csp: false,          // strict per-request-nonce Content-Security-Policy
+  // cspDirectives: {},   // widen it, e.g. { 'img-src': "'self' https://cdn.example.com" }
+  // bodySizeLimit: '1mb',// request body cap before a 413; false disables it
+  // renderTimeout: 10_000, // ms deadline for a request (action + flight + SSR)
+  // compress: true,      // gzip; turn off behind a proxy that already does it
+
+  // Escape hatch: mutate the generated Rspack config just before it compiles. Called once per compiler.
+  // rspack(config, { isServer, isDev }) {
+  //   return config;
+  // },
+});

package/templates/base/src/actions.ts

@@ -0,0 +1,19 @@
+'use server';
+
+/**
+ * A server action: an ordinary async function the browser can call. React hands the client an id for
+ * this export and posts to it, so **every `'use server'` export is a public HTTP endpoint** —
+ * authenticate, authorize and validate the arguments exactly as you would in a route handler. The
+ * framework's CSRF check proves a request came from your own site; it says nothing about who sent it.
+ *
+ * The signature is the one `useActionState` expects: previous state first, then the form data.
+ */
+export async function greet(_previous: string | null, formData: FormData): Promise<string> {
+  const name = String(formData.get('name') ?? '').trim();
+  if (!name) return 'Type a name first.';
+
+  // Where real work goes — a database write, an email, a queue push.
+  await new Promise((resolve) => setTimeout(resolve, 300));
+
+  return `Hello, ${name}. This ran on the server.`;
+}

package/templates/base/src/components/404.tsx

@@ -0,0 +1,17 @@
+import type { PageProps } from '@rshono/core';
+import { Layout } from './layout';
+
+/** Declared as `notFound` in routes.ts. Answers unmatched paths, and any `notFound()` call, with a 404. */
+export default function NotFound({ url }: PageProps) {
+  return (
+    <Layout title="Not found">
+      <h1>404</h1>
+      <p>
+        Nothing at <code>{url.pathname}</code>.
+      </p>
+      <p>
+        <a href="/">Back home</a>
+      </p>
+    </Layout>
+  );
+}

package/templates/base/src/components/500.tsx

@@ -0,0 +1,21 @@
+import type { ErrorPageProps } from '@rshono/core';
+import { Layout } from './layout';
+
+/**
+ * Declared as `error` in routes.ts. Answers a request that threw, with a 500.
+ *
+ * `error.message` is the real message in development and a generic `'Internal Server Error'` in
+ * production, where `error.stack` is absent — so this component can show it without leaking anything.
+ */
+export default function ServerError({ error }: ErrorPageProps) {
+  return (
+    <Layout title="Something went wrong">
+      <h1>500</h1>
+      <p>{error.message}</p>
+      {error.stack && <pre>{error.stack}</pre>}
+      <p>
+        <a href="/">Back home</a>
+      </p>
+    </Layout>
+  );
+}

package/templates/base/src/components/greet-form.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { useActionState } from 'react';
+import { greet } from '../actions';
+
+/**
+ * The client half. `'use client'` is the boundary: this module ships to the browser and hydrates, while
+ * everything that only renders it stays on the server.
+ *
+ * Wiring the action to `<form action>` means it works before hydration and with JavaScript switched off
+ * — the browser posts the form, the server runs the action and answers with a fresh page. That is what
+ * progressive enhancement buys, and it costs nothing here.
+ */
+export function GreetForm() {
+  const [message, action, pending] = useActionState(greet, null);
+
+  return (
+    <form action={action}>
+      <label htmlFor="name">Your name</label>
+      <input id="name" name="name" placeholder="Ada" autoComplete="off" />
+      <button type="submit" disabled={pending}>
+        {pending ? 'Saying hello…' : 'Say hello'}
+      </button>
+      {message && <output>{message}</output>}
+    </form>
+  );
+}

package/templates/base/src/components/home.tsx

@@ -0,0 +1,50 @@
+import type { PageProps } from '@rshono/core';
+import { publicEnv } from '../lib/env';
+import type { AppEnv } from '../server';
+import { GreetForm } from './greet-form';
+import { Layout } from './layout';
+
+/**
+ * A page is a React **server component**: it runs on the server only, may be `async`, and can await data
+ * directly — no loaders, no client bundle for any of this.
+ *
+ * The `AppEnv` type argument is what types `ctx.var` key by key; without it `ctx.var` is an open record.
+ */
+export default function Home({ url, ctx }: PageProps<'/', AppEnv>) {
+  return (
+    <Layout description="A new rshono app.">
+      <h1>{publicEnv.appName}</h1>
+      <p>
+        Edit <code>src/components/home.tsx</code> and save. The page re-renders in place — the form below keeps whatever you have typed in it.
+      </p>
+
+      <h2>Server actions</h2>
+      <p>
+        This form calls a <code>'use server'</code> function in <code>src/actions.ts</code>. It works before hydration and with JavaScript disabled.
+      </p>
+      <GreetForm />
+
+      <h2>Where things are</h2>
+      <ul>
+        <li>
+          <code>src/routes.ts</code> — the route table, the one file rshono requires
+        </li>
+        <li>
+          <code>src/server.ts</code> — a Hono app for middleware and API routes, mounted ahead of the pages
+        </li>
+        <li>
+          <code>src/components/</code> — pages and components; <code>src/lib/</code> — everything else
+        </li>
+        <li>
+          <code>rshono.config.ts</code> — deploy target, security and build settings
+        </li>
+      </ul>
+
+      <p>
+        {/* `ctx` is the request context — cookies, headers, env, middleware variables — handed to the page as a
+            prop, so reading it needs no import. It is server-only and never crosses into a client component. */}
+        Rendered on the server for <code>{url.pathname}</code>, request <code>{ctx.var.requestId}</code>.
+      </p>
+    </Layout>
+  );
+}

package/templates/base/src/components/layout.tsx

@@ -0,0 +1,45 @@
+import { NavigationProgress } from '@rshono/core/client';
+import type { ReactNode } from 'react';
+import { publicEnv } from '../lib/env';
+import '../styles.css';
+
+/**
+ * A page renders the whole document, so the shell lives in one component every page wraps its content
+ * in. Importing the stylesheet here is what attaches it to each of those pages.
+ */
+export function Layout({ title, description, children }: { title?: string; description?: string; children: ReactNode }) {
+  const heading = title ? `${title} · ${publicEnv.appName}` : publicEnv.appName;
+
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{heading}</title>
+        {description && <meta name="description" content={description} />}
+        <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+      </head>
+      <body>
+        {/* Paints during a soft navigation, so a slow page still feels answered. */}
+        <NavigationProgress />
+        <header>
+          <nav>
+            <a href="/">
+              <strong>{publicEnv.appName}</strong>
+            </a>
+            {/* `data-prefetch` warms a page on hover; `data-native` opts a link out of soft navigation. */}
+            <a href="/api/health" data-native>
+              /api/health
+            </a>
+          </nav>
+        </header>
+        <main>{children}</main>
+        <footer>
+          <p>
+            Built with <a href="https://github.com/rshono/rshono">rshono</a> — Hono + Rspack + React Server Components.
+          </p>
+        </footer>
+      </body>
+    </html>
+  );
+}

package/templates/base/src/env.d.ts

@@ -0,0 +1,2 @@
+// Importing a stylesheet is a build-time concern the compiler knows nothing about on its own.
+declare module '*.css';

package/templates/base/src/lib/env.ts

@@ -0,0 +1,26 @@
+/**
+ * Environment access in one place, on the right side of the client/server line.
+ *
+ * The boundary is the RSC directives, not filenames. In a `'use client'` module — and in its SSR pass —
+ * `process.env` is replaced at build time with a literal holding `NODE_ENV` and the `PUBLIC_`-prefixed
+ * variables only, so a secret read there compiles to `undefined` and cannot ship. Server components and
+ * `'use server'` actions read the real environment.
+ */
+
+/** Safe anywhere: `PUBLIC_` variables are the ones compiled into the browser bundle. */
+export const publicEnv = {
+  appName: process.env.PUBLIC_APP_NAME ?? '__PROJECT_NAME__',
+};
+
+/**
+ * Server-only. Throws rather than handing back `undefined`, so a missing secret fails at the point of
+ * use with a name in the message instead of turning into a confusing error further down.
+ *
+ * Calling this from a client component would always throw — that view of `process.env` holds nothing but
+ * `NODE_ENV` and the `PUBLIC_` set. Read secrets in server code and pass derived values down as props.
+ */
+export function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing environment variable ${name} — add it to .env.local`);
+  return value;
+}

package/templates/base/src/routes.ts

@@ -0,0 +1,32 @@
+import { defineRoutes } from '@rshono/core';
+
+/**
+ * The one file rshono requires. It only ever runs on the server, so importing server-only modules from
+ * it — inside `staticPaths`, say — is safe.
+ *
+ * Write each page as the inline `component: () => import('…')` thunk you see below: the build detects
+ * that exact form and attaches the page's own JS and CSS to it, which is what makes assets code-split
+ * per route.
+ */
+export const routes = defineRoutes({
+  routes: [
+    { path: '/', component: () => import('./components/home') },
+
+    // A page with params. `PageProps<'/posts/:slug'>` types `params.slug` for the component.
+    // { path: '/posts/:slug', component: () => import('./components/post') },
+
+    // Prerendered at build time, one file per param set, served from disk.
+    // {
+    //   path: '/docs/:slug',
+    //   render: 'static',
+    //   component: () => import('./components/doc'),
+    //   staticPaths: async () => [{ slug: 'getting-started' }],
+    // },
+
+    // A raw Hono handler instead of a page — for anything that isn't HTML. The other place for these
+    // is src/server.ts, which is the better home for a group of them.
+    // { type: 'endpoint', path: '/api/posts', server: () => import('./api/posts') },
+  ],
+  notFound: { component: () => import('./components/404') },
+  error: { component: () => import('./components/500') },
+});

package/templates/base/src/server.ts

@@ -0,0 +1,59 @@
+import { onServerError } from '@rshono/core/server';
+import { Hono } from 'hono';
+import { trimTrailingSlash } from 'hono/trailing-slash';
+
+/**
+ * What this app's middleware puts on the Hono context. Pass it to `PageProps<path, AppEnv>` (or
+ * `getContext<AppEnv>()`) and `ctx.var` is typed key by key instead of an open record — see
+ * `components/home.tsx`.
+ */
+export type AppEnv = { Variables: { requestId: string } };
+
+const server = new Hono<AppEnv>();
+const startedAt = Date.now();
+
+/**
+ * Where an error tracker goes. Registered at module load — this file is imported as the server starts —
+ * so every error the framework catches reaches one place: a thrown action, a failed render, SSR falling
+ * over. Swap the log for `Sentry.captureException(error)` or whatever you use.
+ */
+onServerError((error, { source, request }) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[error] ${source} ${new URL(request.url).pathname}: ${message}`);
+});
+
+/** `/about/` and `/about` should not be two pages. */
+server.use(trimTrailingSlash({ alwaysRedirect: true }));
+
+/**
+ * This sub-app is mounted at `/` *ahead of* the page routes, so middleware registered here wraps page
+ * requests too — auth, logging, headers. The flip side: a terminal handler at the same path as a page
+ * route shadows the page.
+ */
+server.use('*', async (c, next) => {
+  c.set('requestId', crypto.randomUUID());
+  const start = performance.now();
+  await next();
+  c.res.headers.set('X-Response-Time', `${(performance.now() - start).toFixed(1)} ms`);
+});
+
+/** Old paths that should keep working. One place to add to, rather than a handler each. */
+const REDIRECTS: Record<string, string> = {
+  '/home': '/',
+};
+
+for (const [from, to] of Object.entries(REDIRECTS)) {
+  server.get(from, (c) => c.redirect(to, 301));
+}
+
+server.get('/api/health', (c) => {
+  return c.json({ status: 'ok', uptime: (Date.now() - startedAt) / 1000, requestId: c.var.requestId });
+});
+
+export default server;
+
+/**
+ * End-to-end types for a client that calls this app: `hc<AppType>('/')` from `hono/client` gives typed
+ * paths, params and responses, checked against the handlers above.
+ */
+export type AppType = typeof server;

package/templates/base/src/styles.css

@@ -0,0 +1,178 @@
+/*
+ * Deliberately element-level: nothing here names a class, so the markup in src/components stays plain
+ * HTML you can restyle or replace wholesale without hunting for selectors.
+ *
+ * Rspack compiles this natively — there is no PostCSS anywhere in the framework. If you want a plugin
+ * chain, add the loader in `rshono.config.ts`'s `rspack` hook; that, plus the packages, is all the
+ * Tailwind setup is.
+ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+:root {
+  --bg: #fcfcfd;
+  --surface: #fff;
+  --text: #18181b;
+  --muted: #71717a;
+  --border: #e4e4e7;
+  --accent: #2563eb;
+  --radius: 8px;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #09090b;
+    --surface: #131316;
+    --text: #f4f4f5;
+    --muted: #a1a1aa;
+    --border: #27272a;
+    --accent: #60a5fa;
+  }
+}
+
+body {
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    sans-serif;
+  line-height: 1.6;
+  color: var(--text);
+  background: var(--bg);
+  -webkit-font-smoothing: antialiased;
+}
+
+header,
+main,
+footer {
+  max-width: 44rem;
+  margin-inline: auto;
+  padding-inline: 1.5rem;
+}
+
+header {
+  padding-block: 1.25rem;
+}
+
+nav {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+main {
+  padding-block: 1rem 4rem;
+}
+
+footer {
+  padding-block: 2rem;
+  border-top: 1px solid var(--border);
+  color: var(--muted);
+  font-size: 0.875rem;
+}
+
+h1 {
+  font-size: 2.25rem;
+  letter-spacing: -0.02em;
+  margin-block-end: 0.5rem;
+}
+
+h2 {
+  font-size: 1.125rem;
+  margin-block: 2.5rem 0.5rem;
+}
+
+p,
+ul {
+  margin-block-end: 1rem;
+}
+
+ul {
+  padding-inline-start: 1.25rem;
+}
+
+li {
+  margin-block-end: 0.25rem;
+}
+
+a {
+  color: var(--accent);
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
+}
+
+code {
+  font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+  font-size: 0.875em;
+  padding: 0.1em 0.35em;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--surface);
+}
+
+pre {
+  overflow-x: auto;
+  padding: 1rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+  font-size: 0.8125rem;
+}
+
+form {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 1rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+}
+
+label {
+  flex-basis: 100%;
+  font-size: 0.875rem;
+  color: var(--muted);
+}
+
+input {
+  flex: 1 1 12rem;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--bg);
+  color: inherit;
+  font: inherit;
+}
+
+button {
+  padding: 0.5rem 1rem;
+  border: 0;
+  border-radius: 6px;
+  background: var(--accent);
+  color: #fff;
+  font: inherit;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+button:disabled {
+  opacity: 0.6;
+  cursor: progress;
+}
+
+output {
+  flex-basis: 100%;
+  font-size: 0.9375rem;
+  color: var(--muted);
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "types": ["node", "react"],
+    // `@/…` resolves to `src/…` in both compilers; this is what makes the editor agree. Relative to this
+    // file, since TypeScript 7 removed `baseUrl`.
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["src", "rshono.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}