@viglet/create-shio-app 2026.3.2

package/template/README.md

@@ -0,0 +1,108 @@
+# {{projectName}}
+
+A [Next.js](https://nextjs.org) (App Router) site powered by **Shio CMS** via the
+Content Delivery API — headless, TypeScript-first, **zero Java**.
+
+## Getting started
+
+1. Set your connection details in `.env.local`:
+
+   ```bash
+   SHIO_URL=https://your-shio-instance
+   SHIO_SITE_ID=<your site id>
+   SHIO_CDA_TOKEN=<your CDA token>
+   ```
+
+2. Run the dev server:
+
+   ```bash
+   npm run dev
+   ```
+
+3. Open [http://localhost:3000](http://localhost:3000).
+
+## How it works
+
+- [`lib/shio.ts`](lib/shio.ts) creates a shared [`@viglet/shio-client`](https://www.npmjs.com/package/@viglet/shio-client) instance from the environment.
+- [`app/page.tsx`](app/page.tsx) lists the site's published posts (`shio.query`).
+- [`app/[...slug]/page.tsx`](app/[...slug]/page.tsx) resolves any path to a post via `shio.getPostByUrl(siteId, "/the/path")` — friendly-URL routing straight from the CDA, with `generateStaticParams` (SSG) + `revalidate` (ISR).
+
+All content comes from the Shio CDA (`/api/v2/cda/**`). You never touch the Java backend — just edit React/TypeScript.
+
+## Rendering modes
+
+This starter ships all three Next.js rendering modes against the CDA. Pick per
+route — they compose freely.
+
+### SSG — static at build time
+
+`generateStaticParams` in [`app/[...slug]/page.tsx`](app/[...slug]/page.tsx)
+pre-renders every published post's friendly URL at `next build`. Fastest
+possible response; ideal for content that changes rarely.
+
+### ISR — incremental static regeneration
+
+`export const revalidate = 60` caches a rendered page and re-generates it at most
+once per minute on the next request. Pages not covered by `generateStaticParams`
+are rendered on-demand and then cached the same way. Tune the window per route.
+
+### On-demand revalidation — instant updates
+
+Instead of waiting out the ISR window, Shio can push the moment content is
+published. [`app/api/revalidate/route.ts`](app/api/revalidate/route.ts) receives
+a signed webhook and calls `revalidatePath` so the affected page re-renders on
+its next hit — staleness drops from minutes to seconds.
+
+1. Set `SHIO_WEBHOOK_SECRET` in `.env.local`.
+2. In Shio, add a publish webhook for this site pointing at
+   `https://your-site/api/revalidate` with the same secret (HMAC-SHA256).
+
+The webhook body is `{ event, siteId, postId, url, tags? }`, signed as
+`x-shio-signature: sha256=<hex>`. See the full contract in
+[docs/recipes/nextjs-rendering.md](https://github.com/openviglet/shio/blob/main/docs/recipes/nextjs-rendering.md).
+
+### SSR draft preview
+
+Editors can preview unpublished content before it goes live, using a
+PREVIEW-env CDA token (which serves draft-preferred content):
+
+1. Set `SHIO_PREVIEW_TOKEN` (a PREVIEW-env token) and `SHIO_PREVIEW_SECRET`.
+2. Open `/api/preview?secret=<SHIO_PREVIEW_SECRET>&url=/the/path` — this turns on
+   Next.js Draft Mode and the page renders dynamically (SSR) through the preview
+   client. A banner with an "Exit preview" link appears.
+
+When Draft Mode is off (the default for visitors), everything is plain SSG/ISR.
+
+## Customizing
+
+The post's fields arrive as `post.attrs` (a JSON object keyed by your post-type
+attribute names). The catch-all page renders a `content`/`body`/`text`/`html`
+field if present, and otherwise dumps `attrs` so you can see the shape. Adapt the
+rendering to your own post types.
+
+## Typed content (`post.attrs.*` autocomplete)
+
+`post.attrs` is `Record<string, unknown>` by default. Generate TypeScript
+declarations from your live post-types so you get autocomplete and type-checking:
+
+```bash
+npm run shio:types   # reads SHIO_URL / SHIO_CDA_TOKEN, writes lib/shio-types.d.ts
+```
+
+This emits one `Post` interface per post-type plus a `ShioPostTypes` name→type
+map. Cast a fetched post to its generated type to unlock typed `attrs`:
+
+```ts
+import type { ArticlePost } from "@/lib/shio-types";
+
+const post = (await client.getPostByUrl(SITE_ID, url)) as ArticlePost | null;
+post?.attrs.title; // string — autocompleted
+```
+
+Re-run after changing a post-type. The output is auto-generated — don't edit it
+by hand.
+
+## Learn more
+
+- [Shio CMS](https://github.com/openviglet/shio)
+- [Next.js Docs](https://nextjs.org/docs)

package/template/app/[...slug]/page.tsx

@@ -0,0 +1,110 @@
+import { notFound } from "next/navigation";
+import { draftMode } from "next/headers";
+import type { Metadata } from "next";
+import { getShioClient, shio, SITE_ID, slugToUrl } from "@/lib/shio";
+
+// ISR: pages not pre-rendered at build are rendered on-demand and cached for
+// 60s. For instant updates, wire publish webhooks to `/api/revalidate` (SH9) —
+// then this fixed window is just a fallback. In Draft Mode the route renders
+// dynamically (SSR) and this value is ignored.
+export const revalidate = 60;
+
+type Params = { slug?: string[] };
+
+/**
+ * Pre-render every published post's friendly URL at build time (SSG). Pages not
+ * listed here are still rendered on-demand and cached (ISR via `revalidate`).
+ */
+export async function generateStaticParams(): Promise<Params[]> {
+  if (!SITE_ID) return [];
+  const listing = await shio.query({ siteId: SITE_ID, size: 500 });
+  return listing.posts
+    .filter((p) => p.furl)
+    .map((p) => ({ slug: p.furl!.replace(/^\//, "").split("/") }));
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<Params>;
+}): Promise<Metadata> {
+  const { slug } = await params;
+  if (!SITE_ID) return {};
+  const client = await getShioClient();
+  const post = await client.getPostByUrl(SITE_ID, slugToUrl(slug));
+  if (!post) return {};
+  return {
+    title: post.title ?? undefined,
+    description: post.summary ?? undefined,
+  };
+}
+
+export default async function CatchAllPage({
+  params,
+}: {
+  params: Promise<Params>;
+}) {
+  const { slug } = await params;
+  if (!SITE_ID) notFound();
+
+  // PREVIEW client when Draft Mode is on (SSR draft preview), PROD otherwise.
+  const { isEnabled: isDraft } = await draftMode();
+  const client = await getShioClient();
+
+  const post = await client.getPostByUrl(SITE_ID, slugToUrl(slug));
+  if (!post) notFound();
+
+  // `attrs` is the post-type field map (e.g. content, body, image...). This
+  // starter renders a `content`/`body`/`text` HTML field if present; adapt to
+  // your own post types.
+  const html = pickHtml(post.attrs);
+
+  return (
+    <article>
+      {isDraft && <DraftBanner />}
+      <h1>{post.title}</h1>
+      {post.summary && <p style={{ color: "#666" }}>{post.summary}</p>}
+      {html ? (
+        <div dangerouslySetInnerHTML={{ __html: html }} />
+      ) : (
+        <pre
+          style={{
+            background: "#f6f6f6",
+            padding: "1rem",
+            borderRadius: 8,
+            overflow: "auto",
+          }}
+        >
+          {JSON.stringify(post.attrs, null, 2)}
+        </pre>
+      )}
+    </article>
+  );
+}
+
+function pickHtml(attrs: Record<string, unknown>): string | null {
+  for (const key of ["content", "body", "text", "html"]) {
+    const value = attrs[key];
+    if (typeof value === "string" && value.trim()) return value;
+  }
+  return null;
+}
+
+/** Shown while Draft Mode is active; links to disable it. */
+function DraftBanner() {
+  return (
+    <div
+      style={{
+        background: "#fff7ed",
+        border: "1px solid #fdba74",
+        borderRadius: 8,
+        padding: "0.5rem 0.75rem",
+        marginBottom: "1rem",
+        fontSize: "0.85rem",
+      }}
+    >
+      Draft preview is on.{" "}
+      <a href="/api/preview?disable=1">Exit preview</a>
+    </div>
+  );
+}

package/template/app/api/preview/route.ts

@@ -0,0 +1,65 @@
+import { cookies, draftMode } from "next/headers";
+import { NextResponse } from "next/server";
+import { PREVIEW_SECRET, PREVIEW_TOKEN_COOKIE } from "@/lib/shio";
+
+/**
+ * Draft-preview entry point (Shio roadmap SH9 + SH13, riding on SH5 PREVIEW-env keys).
+ *
+ * Two ways in:
+ *   - Console-issued, short-lived token (SH13):
+ *       `/api/preview?token=<minted>&url=/the/path`
+ *     Shio's console mints an expiring PREVIEW-env CDA token and hands the editor
+ *     this link. The token is stashed in an httpOnly cookie and used per-request
+ *     by `getShioClient()`; it stops working on its own when it expires server-side.
+ *   - Static shared secret (SH9):
+ *       `/api/preview?secret=<SHIO_PREVIEW_SECRET>&url=/the/path`
+ *     Falls back to the long-lived `SHIO_PREVIEW_TOKEN` server client.
+ *
+ * Disable: `/api/preview?disable=1`
+ *
+ * Enabling turns on Next.js Draft Mode (a cookie); subsequent requests render
+ * dynamically (SSR) through the PREVIEW CDA client, which prefers draft rows
+ * over published ones.
+ */
+export async function GET(request: Request): Promise<NextResponse> {
+  const { searchParams } = new URL(request.url);
+  const draft = await draftMode();
+  const cookieStore = await cookies();
+
+  if (searchParams.get("disable")) {
+    draft.disable();
+    cookieStore.delete(PREVIEW_TOKEN_COOKIE);
+    return NextResponse.redirect(new URL(searchParams.get("url") ?? "/", request.url));
+  }
+
+  // Redirect target — relative paths only, to avoid open redirects.
+  const target = searchParams.get("url") ?? "/";
+  const safeTarget = target.startsWith("/") ? target : "/";
+
+  const token = searchParams.get("token");
+  if (token) {
+    // SH13: trust the console-minted token; the backend enforces its expiry and
+    // single-site scope. Stash it httpOnly so getShioClient() reads draft-preferred.
+    draft.enable();
+    cookieStore.set(PREVIEW_TOKEN_COOKIE, token, {
+      httpOnly: true,
+      sameSite: "lax",
+      path: "/",
+      maxAge: 60 * 60, // 1h ceiling; the token itself may expire sooner server-side
+    });
+    return NextResponse.redirect(new URL(safeTarget, request.url));
+  }
+
+  if (!PREVIEW_SECRET) {
+    return NextResponse.json(
+      { message: "SHIO_PREVIEW_SECRET is not configured" },
+      { status: 500 }
+    );
+  }
+  if (searchParams.get("secret") !== PREVIEW_SECRET) {
+    return NextResponse.json({ message: "Invalid preview secret" }, { status: 401 });
+  }
+
+  draft.enable();
+  return NextResponse.redirect(new URL(safeTarget, request.url));
+}

package/template/app/api/revalidate/route.ts

@@ -0,0 +1,96 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { revalidatePath, revalidateTag } from "next/cache";
+import { NextResponse } from "next/server";
+import { WEBHOOK_SECRET } from "@/lib/shio";
+
+// Webhook receiver — runs on the Node runtime (needs `node:crypto`).
+export const runtime = "nodejs";
+
+/**
+ * On-demand revalidation endpoint (Shio roadmap SH9).
+ *
+ * Shio's publish pipeline (SH12) POSTs here on publish / unpublish / delete. The
+ * body is HMAC-SHA256-signed with `SHIO_WEBHOOK_SECRET`; we verify it, then ask
+ * Next.js to drop the affected page(s) from the ISR cache so the next request
+ * re-renders fresh content — turning minutes-of-staleness ISR into seconds.
+ *
+ * Expected payload (the contract SH12 emits — see docs/recipes/nextjs-rendering.md):
+ *   {
+ *     "event":   "publish" | "unpublish" | "delete",
+ *     "siteId":  "<site id>",
+ *     "postId":  "<post id>",
+ *     "url":     "/the/friendly-url",   // optional but preferred
+ *     "tags":    ["optional", "cache", "tags"]
+ *   }
+ *
+ * Signature header: `x-shio-signature: sha256=<hex hmac of the raw body>`.
+ */
+export async function POST(request: Request): Promise<NextResponse> {
+  if (!WEBHOOK_SECRET) {
+    return NextResponse.json(
+      { revalidated: false, message: "SHIO_WEBHOOK_SECRET is not configured" },
+      { status: 500 }
+    );
+  }
+
+  const raw = await request.text();
+  const signature = request.headers.get("x-shio-signature");
+  if (!verifySignature(raw, signature, WEBHOOK_SECRET)) {
+    return NextResponse.json(
+      { revalidated: false, message: "Invalid signature" },
+      { status: 401 }
+    );
+  }
+
+  let payload: WebhookPayload;
+  try {
+    payload = JSON.parse(raw) as WebhookPayload;
+  } catch {
+    return NextResponse.json(
+      { revalidated: false, message: "Invalid JSON body" },
+      { status: 400 }
+    );
+  }
+
+  const revalidated: string[] = [];
+
+  // Drop the affected page itself plus the home/listing page.
+  if (payload.url) {
+    revalidatePath(payload.url);
+    revalidated.push(`path:${payload.url}`);
+  }
+  revalidatePath("/");
+  revalidated.push("path:/");
+
+  // Honour any explicit cache tags (pair with `fetch(..., { next: { tags } })`).
+  for (const tag of payload.tags ?? []) {
+    revalidateTag(tag);
+    revalidated.push(`tag:${tag}`);
+  }
+
+  return NextResponse.json({ revalidated: true, event: payload.event, dropped: revalidated });
+}
+
+type WebhookPayload = {
+  event?: string;
+  siteId?: string;
+  postId?: string;
+  url?: string;
+  tags?: string[];
+};
+
+/** Constant-time verification of `sha256=<hex>` against HMAC-SHA256(raw, secret). */
+function verifySignature(
+  raw: string,
+  header: string | null,
+  secret: string
+): boolean {
+  if (!header) return false;
+  const provided = header.startsWith("sha256=") ? header.slice(7) : header;
+  const expected = createHmac("sha256", secret).update(raw).digest("hex");
+  // timingSafeEqual throws if lengths differ — guard first.
+  const a = Buffer.from(provided, "hex");
+  const b = Buffer.from(expected, "hex");
+  if (a.length !== b.length || a.length === 0) return false;
+  return timingSafeEqual(a, b);
+}

package/template/app/layout.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+
+export const metadata = {
+  title: "Shio site",
+  description: "Powered by Shio CMS — headless, JavaScript-first.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body
+        style={{
+          fontFamily: "system-ui, sans-serif",
+          margin: 0,
+          lineHeight: 1.6,
+          color: "#1a1a1a",
+        }}
+      >
+        <main style={{ maxWidth: 720, margin: "0 auto", padding: "2rem 1rem" }}>
+          {children}
+        </main>
+      </body>
+    </html>
+  );
+}

package/template/app/page.tsx

@@ -0,0 +1,72 @@
+import Link from "next/link";
+import { getShioClient, SITE_ID } from "@/lib/shio";
+
+// ISR: re-fetch from the CDA at most once per minute. Pair with publish
+// webhooks + on-demand revalidation (`/api/revalidate`) for instant updates
+// (see Shio roadmap SH9/SH12). In Draft Mode this renders dynamically (SSR).
+export const revalidate = 60;
+
+export default async function HomePage() {
+  if (!SITE_ID) {
+    return <SetupHint />;
+  }
+
+  const shio = await getShioClient();
+  const site = await shio.getSite(SITE_ID);
+  const listing = await shio.query({ siteId: SITE_ID, size: 50 });
+
+  return (
+    <>
+      <header style={{ marginBottom: "2rem" }}>
+        <h1 style={{ marginBottom: 4 }}>{site?.name ?? "Shio site"}</h1>
+        {site?.description && (
+          <p style={{ color: "#666", marginTop: 0 }}>{site.description}</p>
+        )}
+      </header>
+
+      <h2 style={{ fontSize: "1rem", textTransform: "uppercase", color: "#888" }}>
+        Published content
+      </h2>
+
+      {listing.posts.length === 0 ? (
+        <p style={{ color: "#666" }}>
+          No published posts yet. Publish content in Shio, then refresh.
+        </p>
+      ) : (
+        <ul style={{ listStyle: "none", padding: 0 }}>
+          {listing.posts.map((post) => (
+            <li key={post.id} style={{ padding: "0.75rem 0", borderBottom: "1px solid #eee" }}>
+              {post.furl ? (
+                <Link href={post.furl}>{post.title ?? post.furl}</Link>
+              ) : (
+                <span>{post.title ?? post.id}</span>
+              )}
+              {post.summary && (
+                <p style={{ margin: "4px 0 0", color: "#666", fontSize: "0.9rem" }}>
+                  {post.summary}
+                </p>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </>
+  );
+}
+
+function SetupHint() {
+  return (
+    <>
+      <h1>Welcome to your Shio site 👋</h1>
+      <p>
+        Set <code>SHIO_SITE_ID</code> (and <code>SHIO_URL</code> /{" "}
+        <code>SHIO_CDA_TOKEN</code>) in <code>.env.local</code>, then restart{" "}
+        <code>npm run dev</code>.
+      </p>
+      <p style={{ color: "#666" }}>
+        This starter talks to the Shio Content Delivery API through{" "}
+        <code>@viglet/shio-client</code> — no Java, just TypeScript.
+      </p>
+    </>
+  );
+}

package/template/gitignore

@@ -0,0 +1,26 @@
+# dependencies
+/node_modules
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env files (keep .env.example, ignore real secrets)
+.env*.local
+.env
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

package/template/lib/shio.ts

@@ -0,0 +1,70 @@
+import { cookies, draftMode } from "next/headers";
+import { ShioClient } from "@viglet/shio-client";
+
+const SHIO_BASE_URL = process.env.SHIO_URL ?? "http://localhost:2710";
+
+/** httpOnly cookie holding a console-minted, short-lived preview token (SH13). */
+export const PREVIEW_TOKEN_COOKIE = "shio-preview-token";
+
+/** A draft-preferred client bound to a specific (short-lived) preview token. */
+function previewClientFor(token: string): ShioClient {
+  return new ShioClient({ baseUrl: SHIO_BASE_URL, apiToken: token });
+}
+
+/**
+ * Shared Shio Content Delivery API clients.
+ *
+ * Reads connection details from the environment (see `.env.local`). Safe to
+ * import from any Server Component, Route Handler, or `generateStaticParams`.
+ *
+ * Two clients are exposed:
+ *   - `shio`        — a PROD-env CDA key; serves PUBLISHED content (SSG/ISR).
+ *   - `shioPreview` — a PREVIEW-env CDA key; serves draft-preferred content (SSR
+ *                     draft preview, see `app/api/preview`). `null` unless
+ *                     `SHIO_PREVIEW_TOKEN` is set.
+ *
+ * Use {@link getShioClient} to pick the right one for the current request — it
+ * honours Next.js Draft Mode automatically.
+ */
+export const shio = new ShioClient({
+  baseUrl: process.env.SHIO_URL ?? "http://localhost:2710",
+  apiToken: process.env.SHIO_CDA_TOKEN,
+});
+
+/** The PREVIEW-env client (draft-preferred reads), or `null` if not configured. */
+export const shioPreview: ShioClient | null = process.env.SHIO_PREVIEW_TOKEN
+  ? new ShioClient({
+      baseUrl: process.env.SHIO_URL ?? "http://localhost:2710",
+      apiToken: process.env.SHIO_PREVIEW_TOKEN,
+    })
+  : null;
+
+/**
+ * Pick the CDA client for the current request. Under Next.js Draft Mode, prefer
+ * a console-minted short-lived preview token (SH13) from the request cookie;
+ * otherwise fall back to the long-lived PREVIEW server client (SH9). With Draft
+ * Mode off, always the PROD client. Call from Server Components / Route Handlers.
+ */
+export async function getShioClient(): Promise<ShioClient> {
+  const { isEnabled } = await draftMode();
+  if (isEnabled) {
+    const token = (await cookies()).get(PREVIEW_TOKEN_COOKIE)?.value;
+    if (token) return previewClientFor(token);
+    if (shioPreview) return shioPreview;
+  }
+  return shio;
+}
+
+/** The site this front-end renders. */
+export const SITE_ID = process.env.SHIO_SITE_ID ?? "";
+
+/** Shared secret the publish webhook signs its body with (HMAC-SHA256, SH12). */
+export const WEBHOOK_SECRET = process.env.SHIO_WEBHOOK_SECRET ?? "";
+
+/** Secret that gates the draft-preview entry point (`app/api/preview`). */
+export const PREVIEW_SECRET = process.env.SHIO_PREVIEW_SECRET ?? "";
+
+/** Normalize Next's `slug[]` into a CDA friendly-URL path (always leading slash). */
+export function slugToUrl(slug?: string[]): string {
+  return "/" + (slug ?? []).join("/");
+}

package/template/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/template/next.config.mjs

@@ -0,0 +1,12 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Allow <Image> to load media served from the Shio instance.
+  images: {
+    remotePatterns: [
+      { protocol: "http", hostname: "localhost" },
+      // Add your Shio host here, e.g. { protocol: "https", hostname: "cms.example.com" }
+    ],
+  },
+};
+
+export default nextConfig;

package/template/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "shio:types": "shio-types --url ${SHIO_URL:-http://localhost:2710} --token $SHIO_CDA_TOKEN --out lib/shio-types.d.ts"
+  },
+  "dependencies": {
+    "@viglet/shio-client": "^2026.2.1",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}