create-nowaki 0.18.3 → 0.19.1

package/package.json

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

package/templates/_shared/AGENTS.md

@@ -26,6 +26,14 @@ After an edit or a failing request, check `recent_errors` first.
 ```
 routes/      file-based routes (pages + API). _layout.tsx, _middleware.ts,
              _404.tsx, _500.tsx, [slug].tsx, api/*.ts
+             (name)/ = route group: no URL segment, its own _layout /
+             _middleware for the files inside it (group middleware skips 404s)
+             @name/ = parallel route slot: the parent dir's _layout gets
+             `slots.name` (the @name file matching the URL, else
+             @name/default.tsx, else null). @name/(.)photo/[id].tsx =
+             intercepting route: client navigation to /photo/1 shows it in
+             the slot (a modal); a reload renders routes/photo/[id].tsx.
+             Close it with history.back()
 islands/     interactive components — THE ONLY things that ship JS and hydrate
 components/  shared server components (no client JS)
 lib/         shared server code
@@ -134,6 +142,17 @@ nowaki.config.mjs   plugins (optional)
     <a href={route("/blog/[slug]", { slug })}>Post</a>      // dynamic, params typed
     ```
     Unknown paths, missing params, and wrong param keys are compile errors.
+11. **Markdoc (optional)** — [Markdoc](https://markdoc.dev) via the official
+    `@nowaki-dev/markdoc` plugin (`npm install @nowaki-dev/markdoc`). Register it
+    in `nowaki.config.mjs` and import `.mdoc` files from routes; they are not
+    routes themselves. Upstream docs: `packages/nowaki-markdoc/README.md`.
+    ```js
+    // nowaki.config.mjs
+    import { markdoc } from "@nowaki-dev/markdoc";
+    export default {
+      plugins: [markdoc({ components: "./markdoc/components.tsx", tags: { /* … */ } })],
+    };
+    ```
 
 ## Security
 
@@ -141,6 +160,11 @@ nowaki.config.mjs   plugins (optional)
   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.
+  To validate them, declare them in `env.ts` at the app root with `defineEnv({ server,
+  public })` from `@nowaki-dev/runtime/env` and a Standard Schema per variable; the
+  build fails on a missing or invalid one. Read server values with
+  `import { env } from "@nowaki-dev/runtime/env/server"` in loaders, actions, and server
+  functions (never in islands: that fails the build).
 - **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

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

@@ -1,5 +1,8 @@
 // Nowaki ambient types, so editors understand CSS / asset / virtual-module imports.
 // No need to edit (it only teaches the type checker the framework's import conventions).
+// Keep this file free of top-level import / export. Either one makes it a module, and then the
+// `declare module "*..."` wildcards below stop being ambient declarations. The preact JSX
+// additions (client:* directives) need a module, so they are in nowaki-jsx.d.ts.
 
 declare module "*.module.css" {
   const classes: Record<string, string>;
@@ -46,36 +49,27 @@ declare module "*.mdx" {
   export default MDXContent;
 }
 
+// Markdoc (@nowaki-dev/markdoc): the default export renders the file; `frontmatter` is its
+// frontmatter and `headings` lists its headings.
+declare module "*.mdoc" {
+  export const frontmatter: Record<string, any>;
+  export const headings: { depth: number; text: string; id: string }[];
+  const MarkdocContent: () => import("preact").JSX.Element;
+  export default MarkdocContent;
+}
+
 // Plugin virtual modules (resolveId/load in nowaki.config). Any export is allowed.
 declare module "virtual:*";
 
-// Extends preact's JSX.IntrinsicAttributes so client:* directives can go on any component.
-// This import makes the file a module, so the global types below are exposed via declare global.
-import "preact";
-declare module "preact" {
-  namespace JSX {
-    interface IntrinsicAttributes {
-      /** Hydrate on page load (default). */
-      "client:load"?: boolean;
-      /** Hydrate when idle, via requestIdleCallback. */
-      "client:idle"?: boolean;
-      /** Hydrate once visible, via IntersectionObserver. */
-      "client:visible"?: boolean;
-      /** Hydrate when the media query matches. e.g. client:media="(min-width: 768px)" */
-      "client:media"?: string;
-      /** Skip SSR and render on the client only (for islands using browser-only APIs). */
-      "client:only"?: boolean;
-    }
-  }
+// import.meta.env (PUBLIC_*, MODE and BASE_URL are inlined at build time). These are global
+// because this file is not a module. `nowaki typegen` adds the types of env.ts's public values
+// in .nowaki/types.d.ts.
+interface ImportMetaEnv {
+  readonly MODE: string;
+  /** nowaki.config `basePath` with a trailing slash ("/app/"), or "/". */
+  readonly BASE_URL: string;
+  readonly [key: `PUBLIC_${string}`]: string | undefined;
 }
-
-declare global {
-  // import.meta.env (PUBLIC_* and MODE are inlined at build time).
-  interface ImportMetaEnv {
-    readonly MODE: string;
-    readonly [key: `PUBLIC_${string}`]: string | undefined;
-  }
-  interface ImportMeta {
-    readonly env: ImportMetaEnv;
-  }
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
 }

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

@@ -0,0 +1,22 @@
+// Nowaki's additions to preact's JSX types. No need to edit.
+// Extends preact's JSX.IntrinsicAttributes so client:* directives can go on any component.
+// The import makes this file a module, which a `declare module "preact"` augmentation needs.
+// The ambient asset declarations are in nowaki-env.d.ts, which must not be a module.
+import "preact";
+
+declare module "preact" {
+  namespace JSX {
+    interface IntrinsicAttributes {
+      /** Hydrate on page load (default). */
+      "client:load"?: boolean;
+      /** Hydrate when idle, via requestIdleCallback. */
+      "client:idle"?: boolean;
+      /** Hydrate once visible, via IntersectionObserver. */
+      "client:visible"?: boolean;
+      /** Hydrate when the media query matches. e.g. client:media="(min-width: 768px)" */
+      "client:media"?: string;
+      /** Skip SSR and render on the client only (for islands using browser-only APIs). */
+      "client:only"?: boolean;
+    }
+  }
+}

package/templates/_shared/package.json

@@ -9,11 +9,11 @@
     "prerender": "nowaki prerender"
   },
   "dependencies": {
-    "@nowaki-dev/runtime": "^0.16.3",
+    "@nowaki-dev/runtime": "^0.17.1",
     "preact": "^11.1.1",
     "preact-render-to-string": "^6.8.2"
   },
   "devDependencies": {
-    "nowaki": "^0.17.3"
+    "nowaki": "^0.18.1"
   }
 }

package/templates/_shared/tsconfig.json

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