create-nowaki 0.14.0 → 0.16.0

package/index.js

@@ -141,6 +141,9 @@ await cp(path.join(templatesDir, template), dest, { recursive: true });
 try {
   await rename(path.join(dest, "_gitignore"), path.join(dest, ".gitignore"));
 } catch {}
+try {
+  await rename(path.join(dest, "env.example"), path.join(dest, ".env.example"));
+} catch {}
 
 try {
   const pkgPath = path.join(dest, "package.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nowaki",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Scaffold a new Nowaki app",
   "license": "MIT",
   "author": "Tettu0530",

package/templates/_shared/AGENTS.md

@@ -84,18 +84,35 @@ nowaki.config.mjs   plugins (optional)
    islands to cut work on first load. The directives are typed (no prop leaks).
 7. **Server functions** — a module with a top-of-file `"use server"` directive
    becomes RPC; the client gets a tiny fetch proxy, the implementation stays on
-   the server. Validate arguments; read auth via `getContext()`:
+   the server. Validate the input with `serverFn(schema, impl)` (any Standard
+   Schema library: zod, valibot, arktype); `nowaki build` warns about exports that
+   take arguments without it. Read auth via `getContext()`, and throw
+   `ServerFnError` for messages the client may see (other errors are a generic
+   500 in production):
    ```ts
    // actions/todos.ts
    "use server";
-   import { getContext } from "@nowaki-dev/runtime";
-   export async function addTodo(text: string) { /* runs on the server */ }
+   import { z } from "zod";
+   import { getContext, serverFn, ServerFnError } from "@nowaki-dev/runtime";
+   export const addTodo = serverFn(z.string().min(1).max(200), async (text) => {
+     if (!getContext()?.cookies?.user) throw new ServerFnError("Sign in first", { status: 401 });
+     /* runs on the server with a validated string */
+   });
    ```
+   The **basics** template includes `actions/echo.ts` as a minimal validated example.
    Call it from an island like a normal async function:
    `import { addTodo } from "../actions/todos.ts";`
 8. **Jetstream islands** (server-reactive, zero client JS) — give an island
    `export const live = { state, on }`; buttons use `data-live="handler"` instead
    of `onClick`. State lives on the server; the server pushes HTML patches.
+   Forms use `data-live-submit="handler"` (gets the fields as an object), inputs
+   `data-live-input` (debounced; `data-live-debounce="ms"`) or `data-live-change`;
+   give list rows `data-key`. Read the request with `getContext()` and guard
+   events with `live.authorize`; `live.subscribe` + `live.load` + `publish(topic)`
+   push server-side changes. `live.room(props)` + `live.shared()` share one state
+   between everyone in a room (`data-nowaki-presence="<room>"` shows who's there).
+   Rooms, `publish`, and presence live in one server process (`nowaki start`);
+   on the deploy adapters live islands work per event over POST, without push.
 9. **Loading / error UI** (client navigation) — `routes/loading.tsx` renders
    while a navigation is in flight; `routes/error.tsx` (props `{ error, reset }`,
    type `ErrorPageProps`) renders if it fails. Both nest by directory. In
@@ -112,6 +129,28 @@ nowaki.config.mjs   plugins (optional)
     ```
     Unknown paths, missing params, and wrong param keys are compile errors.
 
+## Security
+
+- **`nowaki dev` is for local development.** Do not expose it to untrusted networks.
+  Use `nowaki start` or a deploy adapter output in production.
+- **Secrets stay server-side.** Only `PUBLIC_*` (and `MODE`) reach the browser. Copy
+  `.env.example` to `.env` and keep database URLs, API keys, and tokens unprefixed.
+- **Server functions and API routes are public endpoints.** Validate and bound every
+  argument; authorize with `getContext()` (cookies/headers) before mutating data.
+  Use `serverFn(schema, impl)` for `"use server"` exports that take arguments (see
+  `actions/echo.ts` in the **basics** template).
+- **Cross-site writes.** Page `action`s reject cross-site non-GET requests by default.
+  **`routes/_middleware.ts` runs before that check** — do not perform sensitive
+  mutations in middleware unless you validate the caller yourself. API routes log a
+  warning and still accept cross-site POSTs unless you `export const csrf = true` on
+  the route (recommended for cookie-authenticated APIs).
+- **Production checklist** (when you deploy): set `NOWAKI_LIVE_SECRET` if the app
+  uses Jetstream live islands; try `NOWAKI_CSP=report-only` before `enforce`; behind
+  a reverse proxy on `nowaki start`, set `NOWAKI_TRUST_PROXY=1` and forward the public
+  host as `x-forwarded-host`. See the upstream [SECURITY.md](https://github.com/Tettu0530/nowaki/blob/main/SECURITY.md).
+- **Do not embed secrets** in client islands, loaders returned to the page, or static
+  prerender output. ISR pages must not include per-user secrets.
+
 ## Don't
 
 - Don't add a build tool (Vite/webpack/Babel) or a `tsconfig` paths setup — the

package/templates/_shared/README.md

@@ -8,6 +8,7 @@ components under `islands/` ship JavaScript and hydrate.
 
 ```bash
 npm install
+cp .env.example .env   # optional — only PUBLIC_* vars belong in client bundles
 npm run dev      # http://localhost:3000
 ```
 
@@ -43,6 +44,15 @@ actions/     "use server" RPC modules (optional)
   `preact/compat`, so many React libraries work.)
 - Use **explicit file extensions** in relative imports: `../islands/Counter.tsx`.
 - A route's `loader` runs only on the server; `action` handles non-GET requests.
-- `AGENTS.md` documents the conventions for AI coding agents.
+- The **basics** template adds `routes/_404.tsx`, `routes/api/health.ts`, and
+  `actions/echo.ts`; **minimal** is a single page with no islands.
+- `AGENTS.md` documents conventions (including security) for AI coding agents.
+
+## Production
+
+Use `npm run build` then `npm run start` (or a deploy adapter). Do not run
+`nowaki dev` on the public internet. Cookie-authenticated API routes should export
+`csrf = true`; live islands need a stable `NOWAKI_LIVE_SECRET`. See `AGENTS.md`
+§ Security and [nowaki.dev/docs](https://nowaki.dev/docs).
 
 Docs: <https://nowaki.dev/docs>

package/templates/_shared/env.example

@@ -0,0 +1,7 @@
+# Copy to `.env` for local development. Never commit `.env` (see `.gitignore`).
+#
+# Only variables prefixed with PUBLIC_ are inlined into client bundles.
+# Everything else stays on the server (loaders, actions, server functions).
+#
+# PUBLIC_SITE_NAME=My App
+# DATABASE_URL=postgres://...   # server-only — do not prefix with PUBLIC_

package/templates/_shared/package.json

@@ -9,11 +9,11 @@
     "prerender": "nowaki prerender"
   },
   "dependencies": {
-    "@nowaki-dev/runtime": "^0.12.0",
+    "@nowaki-dev/runtime": "^0.14.0",
     "preact": "^10.25.4",
     "preact-render-to-string": "^6.8.2"
   },
   "devDependencies": {
-    "nowaki": "^0.13.0"
+    "nowaki": "^0.15.0"
   }
 }

package/templates/basics/actions/echo.ts

@@ -0,0 +1,22 @@
+"use server";
+
+import { getContext, serverFn } from "@nowaki-dev/runtime";
+
+// Hand-written Standard Schema (no zod/valibot) — same pattern as examples/hello/actions/todos.ts.
+const message = {
+  "~standard": {
+    version: 1 as const,
+    vendor: "example",
+    validate: (v: unknown) =>
+      typeof v === "string" && v.length <= 120
+        ? { value: v.trim() }
+        : { issues: [{ message: "message must be a string of at most 120 characters" }] },
+  },
+};
+
+/** Example server function — validated input and getContext() for auth in real apps. */
+export const echo = serverFn(message, async (text) => ({
+  ok: true,
+  echo: text,
+  hasRequest: getContext() != null,
+}));

package/templates/basics/routes/_404.tsx

@@ -0,0 +1,13 @@
+export const title = "404 — Not found";
+
+export default function NotFound({ url }: { url: URL }) {
+  return (
+    <main>
+      <h1>404</h1>
+      <p>
+        Page not found: <code>{url.pathname}</code>
+      </p>
+      <a href="/">Back to home</a>
+    </main>
+  );
+}

package/templates/basics/routes/api/health.ts

@@ -0,0 +1,6 @@
+// Example API route (server-only). No secrets in responses; validate inputs on real endpoints.
+type Ctx = { json: (data: unknown) => unknown };
+
+export function GET(ctx: Ctx) {
+  return ctx.json({ ok: true });
+}