create-nowaki 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nowaki",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Scaffold a new Nowaki app",
   "license": "MIT",
   "author": "VorEdge <dev@voredge.com>",

package/templates/_shared/AGENTS.md

@@ -12,6 +12,7 @@ npm run dev        # nowaki dev   — dev server with hot reload (http://localho
 npm run build      # nowaki build — production build (dist/client + dist/server)
 npm run start      # nowaki start — serve the production build
 npm run prerender  # nowaki prerender — static export
+npx nowaki upgrade # update nowaki (CLI) + @nowaki-dev/runtime to latest
 ```
 
 ## Project layout
@@ -38,16 +39,23 @@ nowaki.config.mjs   plugins (optional)
    `onClick`/hooks in route or `components/` files.
 3. **Use explicit file extensions in relative imports**:
    `import Counter from "../islands/Counter.tsx"` (not `"../islands/Counter"`).
-4. **Routes** are components with an optional server-only `loader` and `action`:
+4. **Routes** are components with an optional server-only `loader` and `action`.
+   Optional types come from `@nowaki-dev/runtime` — `PageProps<typeof loader>`
+   infers the page's `data`, `LoaderContext` types `params`/cookies/headers:
    ```tsx
    // routes/blog/[slug].tsx
-   export const loader = async ({ params }) => ({ post: await db.post(params.slug) }); // server-only
-   export async function action(ctx) {            // runs on non-GET requests
+   import type { LoaderContext, PageProps } from "@nowaki-dev/runtime";
+   export const loader = async ({ params }: LoaderContext) => ({ post: await db.post(params.slug) }); // server-only
+   export async function action(ctx: LoaderContext) {  // runs on non-GET requests
      const form = await ctx.formData();
      return ctx.redirect("/blog");                 // Post/Redirect/Get
    }
-   export default function Post({ data }) { return <article><h1>{data.post.title}</h1></article>; }
+   export default function Post({ data }: PageProps<typeof loader>) { return <article><h1>{data.post.title}</h1></article>; }
    ```
+   A catch-all segment `routes/files/[...path].tsx` matches `/files/a/b/c`;
+   `params.path` is the array `["a","b","c"]`. Add `export const revalidate = 60`
+   (seconds) to a route for ISR: the HTML is cached and regenerated in the
+   background when stale (don't put per-user data on an ISR page).
 5. **API routes** are `routes/api/*.ts` with per-method exports; return a value
    (JSON-encoded) or a `Response`:
    ```ts
@@ -63,13 +71,24 @@ nowaki.config.mjs   plugins (optional)
      return <button onClick={() => setN(n + 1)}>count: {n}</button>;
    }
    ```
+   **Lazy hydration** (Astro-style `client:*` directives) controls *when* an
+   island hydrates — add a directive where you use it:
+   ```tsx
+   <Counter client:load />              // default — hydrate on load
+   <Counter client:idle />              // hydrate on requestIdleCallback
+   <Counter client:visible />           // hydrate when scrolled into view
+   <Chart client:media="(min-width: 768px)" />  // hydrate when the query matches
+   <Map client:only />                  // skip SSR, render only on the client
+   ```
+   Prefer `client:visible` / `client:idle` for below-the-fold or non-critical
+   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()`:
    ```ts
    // actions/todos.ts
    "use server";
-   import { getContext } from "@nowaki-dev/runtime/server/functions.mjs";
+   import { getContext } from "@nowaki-dev/runtime";
    export async function addTodo(text: string) { /* runs on the server */ }
    ```
    Call it from an island like a normal async function:
@@ -77,6 +96,21 @@ nowaki.config.mjs   plugins (optional)
 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.
+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
+   `error.tsx`, mark the message element `data-nowaki-error` and the retry button
+   `data-nowaki-reset`. Visited pages are kept in a ~30s Router Cache, so
+   back/forward is instant. These are server components, not islands.
+10. **Typed navigation** — `dev`/`build` generate `.nowaki/types.d.ts` from your
+    routes (run `nowaki typegen` to refresh manually). Build links type-safely
+    from `@nowaki-dev/runtime/navigation`:
+    ```tsx
+    import { route, Link } from "@nowaki-dev/runtime/navigation";
+    <Link href="/about">About</Link>                       // static path, checked
+    <a href={route("/blog/[slug]", { slug })}>Post</a>      // dynamic, params typed
+    ```
+    Unknown paths, missing params, and wrong param keys are compile errors.
 
 ## Don't
 

package/templates/_shared/README.md

@@ -15,6 +15,18 @@ Other scripts: `npm run build`, `npm run start`, `npm run prerender`.
 Pass `--host` to expose dev on your LAN, `--open` to open the browser:
 `npm run dev -- --host --open`.
 
+## Update
+
+```bash
+npx nowaki upgrade        # bumps nowaki (CLI) and @nowaki-dev/runtime to latest
+```
+
+`nowaki upgrade` detects your package manager and updates both packages,
+rewriting the `package.json` ranges. (A plain `npm update` won't cross a
+`0.x` minor, so prefer `nowaki upgrade` — or install `@latest` by hand.)
+Pin a version with `--to`, e.g. `npx nowaki upgrade --to 0.11.0`. Pre-1.0,
+check the release notes before upgrading; minors can include breaking changes.
+
 ## Structure
 
 ```

package/templates/_shared/_gitignore

@@ -1,6 +1,8 @@
 node_modules/
 dist/
 .cache/
+.nowaki/
+.vercel/
 
 # env (keep secrets out of git; only PUBLIC_* reaches the client)
 .env

package/templates/_shared/nowaki-env.d.ts

@@ -32,11 +32,34 @@ declare module "*.pdf" { const url: string; export default url; }
 // プラグインの仮想モジュール（nowaki.config の resolveId/load）。任意の export を許す。
 declare module "virtual:*";
 
-// import.meta.env（PUBLIC_* と MODE がビルド時に inline される）。
-interface ImportMetaEnv {
-  readonly MODE: string;
-  readonly [key: `PUBLIC_${string}`]: string | undefined;
+// 遅延ハイドレーション指令（Astro 互換の client:*）を任意のコンポーネントに付けられるよう、
+// preact の JSX.IntrinsicAttributes を拡張する。<Counter client:visible /> 等が型チェックを通る。
+// （この import で本ファイルはモジュールになる＝下のグローバル型は declare global で公開する。）
+import "preact";
+declare module "preact" {
+  namespace JSX {
+    interface IntrinsicAttributes {
+      /** ページ読み込み時にハイドレート（既定）。 */
+      "client:load"?: boolean;
+      /** requestIdleCallback でアイドル時にハイドレート。 */
+      "client:idle"?: boolean;
+      /** IntersectionObserver で可視になったらハイドレート。 */
+      "client:visible"?: boolean;
+      /** 指定メディアクエリが一致したらハイドレート。例: client:media="(min-width: 768px)" */
+      "client:media"?: string;
+      /** SSR せず、クライアントだけで描画（ブラウザ専用 API を使う島向け）。 */
+      "client:only"?: boolean;
+    }
+  }
 }
-interface ImportMeta {
-  readonly env: ImportMetaEnv;
+
+declare global {
+  // import.meta.env（PUBLIC_* と MODE がビルド時に inline される）。
+  interface ImportMetaEnv {
+    readonly MODE: string;
+    readonly [key: `PUBLIC_${string}`]: string | undefined;
+  }
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
 }

package/templates/_shared/package.json

@@ -9,11 +9,11 @@
     "prerender": "nowaki prerender"
   },
   "dependencies": {
-    "@nowaki-dev/runtime": "^0.9.0",
+    "@nowaki-dev/runtime": "^0.11.0",
     "preact": "^10.25.4",
     "preact-render-to-string": "^6.5.13"
   },
   "devDependencies": {
-    "nowaki": "^0.10.0"
+    "nowaki": "^0.12.0"
   }
 }

package/templates/_shared/tsconfig.json

@@ -23,6 +23,7 @@
   },
   "include": [
     "nowaki-env.d.ts",
+    ".nowaki/types.d.ts",
     "nowaki.config.*",
     "routes",
     "islands",

package/templates/basics/routes/index.tsx

@@ -1,3 +1,4 @@
+import type { PageProps } from "@nowaki-dev/runtime";
 import Counter from "../islands/Counter.tsx";
 
 const CSS = `
@@ -32,9 +33,7 @@ export const head = `<style>${CSS}</style>`;
 
 export const loader = async () => ({ greeting: "Welcome to Nowaki" });
 
-type Data = Awaited<ReturnType<typeof loader>>;
-
-export default function Home({ data }: { data: Data }) {
+export default function Home({ data }: PageProps<typeof loader>) {
   return (
     <main class="wrap">
       <div class="brand">