hono-svelte 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hono-svelte contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# hono-svelte
+
+Shell server-side + paginas Svelte multi-entry para apps Hono, 100% in-memory
+(nenhum arquivo gerado em disco) e com zero-JS automatico para paginas estaticas.
+Zero config: o app nao importa nada alem de `shell()` e `pages()`.
+
+- `hono-svelte` — middleware `shell()`: registra `c.render(entry, { title?, data? })`.
+  - `data` (pequeno, publico, serializavel) vai embutido no HTML
+    (`<script type="application/json">` com id opaco) e chega na pagina via `$props()`.
+  - Dados privados, grandes ou mutaveis: buscar via RPC (`hc<AppType>`) apos o mount.
+  - Zero config: o shell descobre sozinho quais paginas sao estaticas e
+    renderiza no servidor via `svelte/server`, sem import nenhum no app.
+- `hono-svelte/vite` — plugin `pages()`: cada `*.svelte` em `pagesDir`
+  (exceto parciais) vira um entry virtual com `mount()` automatico.
+  Nada e escrito em disco.
+
+## Uso
+
+```ts
+// vite.config.ts
+import { pages } from "hono-svelte/vite";
+const appPages = pages(); // defaults: src/pages
+// input: { ...appPages.input(), styles: "src/styles.css" }
+// plugins: [tailwindcss(), svelte(), appPages, ...] em TODOS os modos
+// (client, serve e server build) - o modo server precisa de appPages para
+// o shell enxergar o manifesto in-memory.
+```
+
+```ts
+// servidor
+import { shell } from "hono-svelte";
+
+app.use("/*", shell({ title: "Meu App", lang: "pt-BR" }));
+app.get("/dashboard", (c) => c.render("dashboard", { data: { plan: "pro" } }));
+```
+
+```svelte
+<!-- pagina estatica: sem <script> => zero-JS, HTML vem pronto do servidor -->
+<main>...</main>
+```
+
+## Zero-JS automatico
+
+Pagina sem `<script>` no `.svelte` nao gera entry client: o `shell()` renderiza
+o HTML no servidor e nenhum `<script>` e enviado ao cliente. Para forcar client
+JS em uma pagina especifica: `pages({ alwaysClient: ["index"] })`.
+Para override manual do mapa de SSR: `shell({ ssrPages })` (opcional).
+
+## IDs
+
+`root`/`data` usam ids opacos derivados do `entryName` via `getIds(entryName)`
+(`r-` + hash). Servidor e client derivam o mesmo par sem config, sem disco, sem salt.
+
+## Repo
+
+- `/` — o pacote `hono-svelte` (src, test, dist)
+- `/examples/playground` — app Hono de demonstracao, consome o pacote via `file:../..`
+
+## Tipagem do `c.render`
+
+Augmente o `ContextRenderer` no SEU app (padrao do Hono) — crie um `env.d.ts`:
+
+```ts
+import type { RenderProps } from "hono-svelte";
+
+declare module "hono" {
+  interface ContextRenderer {
+    (entryName: string, props?: RenderProps): Response | Promise<Response>;
+  }
+}
+```

package/dist/ids.d.ts

@@ -0,0 +1,5 @@
+export type SharedIds = {
+    rootId: string;
+    dataId: string;
+};
+export declare function getIds(entryName: string): SharedIds;

package/dist/ids.js

@@ -0,0 +1,22 @@
+// IDs opacos derivados do entryName. Puro, sem dependencias de runtime.
+// (funciona em Node, Workers, Deno, Bun). Nao e segredo de estado:
+// apenas evita expor dados do servidor no HTML.
+function hashString(input) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    const n = 4294967296 * (2097151 & h2) + (h1 >>> 0);
+    return n.toString(16).padStart(12, '0').slice(0, 8);
+}
+export function getIds(entryName) {
+    return {
+        rootId: 'r-' + hashString(entryName + ':root'),
+        dataId: 'r-' + hashString(entryName + ':data'),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { Next } from "hono";
+export { getIds } from "./ids.js";
+export type { SharedIds } from "./ids.js";
+export type SsrPageLoader = () => Promise<{
+    default: unknown;
+}>;
+export type RenderProps = {
+    title?: string;
+    data?: Record<string, unknown>;
+};
+export type ShellOptions = {
+    title?: string;
+    lang?: string;
+    assetsBase?: string;
+    stylesHref?: string | ((isProd: boolean) => string);
+    head?: string;
+    /** Override manual do mapa entryName -> loader (opcional; sem isso o shell
+     *  resolve o mapa automaticamente via ssr-manifest). */
+    ssrPages?: Record<string, SsrPageLoader>;
+};
+export type ShellContext = {
+    render: (entryName: string, props?: RenderProps) => Response | Promise<Response>;
+};
+export declare function shell(options?: ShellOptions): (c: any, next: Next) => Promise<void>;

package/dist/index.js

@@ -0,0 +1,84 @@
+import { getIds } from "./ids.js";
+import { ssrPages as autoSsrPages } from "./ssr-manifest.js";
+import { devEntryUrl } from "./virtual.js";
+export { getIds } from "./ids.js";
+function escapeAttr(value) {
+    return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+function isValidEntryName(entryName) {
+    if (!entryName || entryName.length > 200)
+        return false;
+    if (entryName.startsWith("/") || entryName.startsWith("."))
+        return false;
+    if (entryName.includes("\\"))
+        return false;
+    const parts = entryName.split("/");
+    return parts.every((p) => p.length > 0 && p !== "." && p !== ".." && !p.includes(String.fromCharCode(0)));
+}
+function serializePageData(data, dataId) {
+    if (!data)
+        return "";
+    let json;
+    try {
+        json = JSON.stringify(data);
+    }
+    catch {
+        throw new Error("hono-svelte: props.data precisa ser serializavel em JSON");
+    }
+    if (json === undefined)
+        return "";
+    json = json.replace(/</g, "\\u003c");
+    const lt = String.fromCharCode(60);
+    return lt + 'script type="application/json" id="' + dataId + '">' + json + lt + "/script>";
+}
+export function shell(options = {}) {
+    const titleDefault = options.title ?? "App";
+    const lang = options.lang ?? "en";
+    const assetsBase = (options.assetsBase ?? "/static").replace(/\/$/, "");
+    const head = options.head ?? "";
+    const resolveStyles = typeof options.stylesHref === "function"
+        ? options.stylesHref
+        : () => options.stylesHref;
+    // Zero config: com pages() ativo, este modulo e redirecionado para o
+    // manifesto in-memory pelo resolveId do plugin (enforce: "pre").
+    const ssrPages = options.ssrPages ?? autoSsrPages;
+    return async function shellMiddleware(c, next) {
+        c.setRenderer(async (entryName, props) => {
+            if (!isValidEntryName(entryName)) {
+                throw new Error(`hono-svelte: entryName invalido: ${JSON.stringify(entryName)}`);
+            }
+            const ids = getIds(entryName);
+            const title = props?.title ?? titleDefault;
+            const isProd = import.meta.env?.PROD ?? false;
+            const stylesHref = resolveStyles(isProd) ?? (isProd ? "/static/styles.css" : "/src/styles.css");
+            const dataHtml = props?.data ? serializePageData(props.data, ids.dataId) : "";
+            const lt = String.fromCharCode(60);
+            const loader = ssrPages[entryName];
+            let bodyHtml = "";
+            let ssrHead = "";
+            if (loader !== undefined) {
+                const mod = await loader();
+                const { render } = await import("svelte/server");
+                const rendered = render(mod.default);
+                bodyHtml = rendered.html;
+                ssrHead = rendered.head ?? "";
+            }
+            let scriptHtml = "";
+            if (loader === undefined) {
+                const src = isProd ? `${assetsBase}/${entryName}.js` : devEntryUrl(entryName);
+                scriptHtml = lt + `script type="module" src="${escapeAttr(src)}">` + lt + "/script>";
+            }
+            return c.html(`<!doctype html><html lang="${escapeAttr(lang)}"><head><title>${escapeAttr(title)}</title>` +
+                `<meta charset="utf-8" /><meta content="width=device-width, initial-scale=1" name="viewport" />` +
+                (head ? head : "") +
+                `<link rel="stylesheet" href="${escapeAttr(stylesHref)}" />` +
+                ssrHead +
+                scriptHtml +
+                `</head>` +
+                `<body class="bg-base-200 min-h-screen text-base-content"><div id="${ids.rootId}">${bodyHtml}</div>` +
+                dataHtml +
+                `</body></html>`);
+        });
+        await next();
+    };
+}

package/dist/ssr-manifest.d.ts

@@ -0,0 +1,3 @@
+export declare const ssrPages: Record<string, () => Promise<{
+    default: unknown;
+}>>;

package/dist/ssr-manifest.js

@@ -0,0 +1,6 @@
+// Stub estatico usado pelo shell quando o plugin hono-svelte/vite (pages())
+// nao esta ativo no bundler: nenhuma pagina estatica, todos os entries
+// sao client-side. Com pages() ativo, o resolveId do plugin (enforce: "pre")
+// redireciona o import relativo "./ssr-manifest.js" do shell para o
+// manifesto virtual gerado em memoria.
+export const ssrPages = {};

package/dist/virtual.d.ts

@@ -0,0 +1,7 @@
+export declare const ENTRY_PREFIX = "virtual:hono-svelte/entry/";
+export declare const ENTRY_RESOLVED_PREFIX: string;
+export declare const MANIFEST_ID = "virtual:hono-svelte/manifest";
+export declare const MANIFEST_RESOLVED: string;
+export declare function entryVirtualId(entryName: string): string;
+export declare function entryResolvedId(entryName: string): string;
+export declare function devEntryUrl(entryName: string): string;

package/dist/virtual.js

@@ -0,0 +1,19 @@
+// IDs dos modulos virtuais compartilhados entre o plugin (hono-svelte/vite)
+// e o shell (hono-svelte). Nada e escrito em disco: entries e manifesto
+// sao servidos in-memory como virtual modules.
+const NULL = String.fromCharCode(0);
+export const ENTRY_PREFIX = "virtual:hono-svelte/entry/";
+export const ENTRY_RESOLVED_PREFIX = NULL + ENTRY_PREFIX;
+export const MANIFEST_ID = "virtual:hono-svelte/manifest";
+export const MANIFEST_RESOLVED = NULL + MANIFEST_ID;
+export function entryVirtualId(entryName) {
+    return ENTRY_PREFIX + entryName;
+}
+export function entryResolvedId(entryName) {
+    return ENTRY_RESOLVED_PREFIX + entryName;
+}
+// URL de dev para o <script type="module"> gerado pelo shell.
+// \0 vira __x00__ na URL servida pelo dev server do Vite.
+export function devEntryUrl(entryName) {
+    return "/@id/" + entryResolvedId(entryName).replace(NULL, "__x00__");
+}

package/dist/vite.d.ts

@@ -0,0 +1,15 @@
+import { type Plugin } from "vite";
+export type PagesOptions = {
+    pagesDir?: string;
+    ignore?: string[];
+    /** entryNames que sempre geram client JS, mesmo sem <script>. */
+    alwaysClient?: string[];
+    generatedHeader?: string;
+};
+export type PagesPlugin = Plugin & {
+    input: () => Record<string, string>;
+    entries: () => string[];
+    staticEntries: () => string[];
+    hasClient: (entryName: string) => boolean;
+};
+export declare function pages(options?: PagesOptions): PagesPlugin;

package/dist/vite.js

@@ -0,0 +1,193 @@
+import { globSync, readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { getIds } from "./ids.js";
+import { ENTRY_PREFIX, ENTRY_RESOLVED_PREFIX, MANIFEST_ID, MANIFEST_RESOLVED, } from "./virtual.js";
+import { createFilter } from "vite";
+const DEFAULT_IGNORE = ["**/layout.svelte", "**/_*.svelte"];
+function normalizeSlashes(p) {
+    return p.replace(/\\/g, "/");
+}
+function entryNameFromFile(file) {
+    return normalizeSlashes(file).slice(0, -".svelte".length);
+}
+export function pages(options = {}) {
+    const pagesDir = resolve(options.pagesDir ?? "src/pages");
+    const ignore = options.ignore ?? DEFAULT_IGNORE;
+    const alwaysClient = new Set(options.alwaysClient ?? []);
+    const header = options.generatedHeader ?? "// @generated - hono-svelte, nao editar.";
+    const filter = createFilter(["**/*.svelte"], ignore, { resolve: pagesDir });
+    let cachedPages = null;
+    let cachedInput = {};
+    let viteRoot = null;
+    function computePages() {
+        const files = globSync("**/*.svelte", { cwd: pagesDir })
+            .map(normalizeSlashes)
+            .filter((f) => filter(pagesDir + "/" + f))
+            .sort();
+        const seen = new Set();
+        const result = [];
+        for (const file of files) {
+            const entryName = entryNameFromFile(file);
+            if (seen.has(entryName)) {
+                throw new Error(`hono-svelte: entry duplicado: ${entryName}`);
+            }
+            seen.add(entryName);
+            const absFile = resolve(pagesDir, file);
+            // Zero-JS automatico: pagina sem <script> nao tem interatividade,
+            // entao o shell renderiza no servidor e o cliente nao baixa JS.
+            const hasScript = /<script[\s>]/i.test(readFileSync(absFile, "utf8"));
+            result.push({ entryName, file, absFile, isStatic: !hasScript && !alwaysClient.has(entryName) });
+        }
+        return result;
+    }
+    function refresh(log = true) {
+        cachedPages = computePages();
+        cachedInput = {};
+        let jsCount = 0;
+        for (const page of cachedPages) {
+            if (page.isStatic)
+                continue;
+            cachedInput[page.entryName] = ENTRY_RESOLVED_PREFIX + page.entryName;
+            jsCount++;
+        }
+        if (log) {
+            const staticCount = cachedPages.length - jsCount;
+            console.log("[hono-svelte] " + jsCount + " pagina(s) com JS + " + staticCount + " estatica(s), tudo in-memory");
+        }
+    }
+    function listPages() {
+        if (!cachedPages)
+            refresh(false);
+        return cachedPages;
+    }
+    function stateKey() {
+        return listPages()
+            .map((p) => (p.isStatic ? "S:" : "C:") + p.entryName)
+            .join("|");
+    }
+    function pageImportPath(page) {
+        const root = viteRoot ?? process.cwd();
+        const rel = relative(root, page.absFile);
+        if (rel.startsWith("..")) {
+            throw new Error("hono-svelte: pagesDir precisa estar dentro do root do Vite");
+        }
+        return "/" + normalizeSlashes(rel);
+    }
+    function manifestSource() {
+        const all = listPages();
+        const client = all.filter((p) => !p.isStatic).map((p) => p.entryName);
+        const staticPages = all.filter((p) => p.isStatic);
+        const loaders = staticPages.map((p) => "  " + JSON.stringify(p.entryName) + ": () => import(" + JSON.stringify(pageImportPath(p)) + "),");
+        return [
+            header + " gerado em memoria pelo plugin - nao editar.",
+            "",
+            "export const clientEntries = " + JSON.stringify(client) + ";",
+            "",
+            "export const staticEntries = " + JSON.stringify(staticPages.map((p) => p.entryName)) + ";",
+            "",
+            "export const ssrPages = {",
+            ...(loaders.length > 0 ? loaders : ["  // nenhuma pagina estatica detectada"]),
+            "};",
+            "",
+            "export function hasClient(entryName) {",
+            "  return !Object.prototype.hasOwnProperty.call(ssrPages, entryName);",
+            "}",
+            "",
+        ].join("\n");
+    }
+    function entrySource(page) {
+        const ids = getIds(page.entryName);
+        return (header + " Origem: " + page.file + "\n" +
+            'import { mount } from "svelte";\n' +
+            "import Page from " + JSON.stringify(pageImportPath(page)) + ";\n" +
+            "const target = document.getElementById(" + JSON.stringify(ids.rootId) + ");\n" +
+            "const raw = document.getElementById(" + JSON.stringify(ids.dataId) + ")?.textContent;\n" +
+            "const props = raw ? JSON.parse(raw) : {};\n" +
+            "if (target) mount(Page, { target, props });\n");
+    }
+    const plugin = {
+        name: "hono-svelte-pages",
+        // pre: precisa rodar ANTES do vite:resolve para interceptar o import
+        // relativo do shell ("./ssr-manifest.js") e redirecionar ao manifesto.
+        enforce: "pre",
+        configResolved(config) {
+            viteRoot = config.root;
+        },
+        buildStart() {
+            refresh();
+        },
+        resolveId(source) {
+            // Manifesto virtual: explicito (virtual:hono-svelte/manifest, retrocompat)
+            // ou o import relativo do proprio shell. Sem pages() ativo, o import
+            // relativo resolve o stub estatico dist/ssr-manifest.js.
+            if (source === MANIFEST_ID || source === "./ssr-manifest.js")
+                return MANIFEST_RESOLVED;
+            if (source.startsWith(ENTRY_PREFIX)) {
+                return ENTRY_RESOLVED_PREFIX + source.slice(ENTRY_PREFIX.length);
+            }
+            // ids ja resolvidos (\0...) passam direto para o load()
+            if (source === MANIFEST_RESOLVED || source.startsWith(ENTRY_RESOLVED_PREFIX)) {
+                return source;
+            }
+            return null;
+        },
+        load(id) {
+            if (id === MANIFEST_RESOLVED)
+                return manifestSource();
+            if (id.startsWith(ENTRY_RESOLVED_PREFIX)) {
+                const entryName = id.slice(ENTRY_RESOLVED_PREFIX.length);
+                const page = listPages().find((p) => p.entryName === entryName);
+                if (!page) {
+                    throw new Error("hono-svelte: pagina nao encontrada para entry: " + entryName);
+                }
+                return entrySource(page);
+            }
+            return null;
+        },
+        configureServer(server) {
+            server.watcher.add(pagesDir);
+            const isPagePath = (file) => {
+                const rel = normalizeSlashes(relative(pagesDir, file));
+                return rel.length > 0 && !rel.startsWith("..") && rel.endsWith(".svelte");
+            };
+            const onMaybeStructural = () => {
+                const before = stateKey();
+                cachedPages = null;
+                refresh();
+                if (stateKey() !== before) {
+                    const mod = server.moduleGraph.getModuleById(MANIFEST_RESOLVED);
+                    if (mod)
+                        server.moduleGraph.invalidateModule(mod);
+                    server.ws.send({ type: "full-reload" });
+                }
+            };
+            server.watcher.on("add", (file) => {
+                if (isPagePath(file))
+                    onMaybeStructural();
+            });
+            server.watcher.on("unlink", (file) => {
+                if (isPagePath(file))
+                    onMaybeStructural();
+            });
+            server.watcher.on("change", (file) => {
+                if (isPagePath(file))
+                    onMaybeStructural();
+            });
+        },
+        input() {
+            listPages();
+            return cachedInput;
+        },
+        entries() {
+            return listPages().map((p) => p.entryName);
+        },
+        staticEntries() {
+            return listPages().filter((p) => p.isStatic).map((p) => p.entryName);
+        },
+        hasClient(entryName) {
+            const page = listPages().find((p) => p.entryName === entryName);
+            return page ? !page.isStatic : false;
+        },
+    };
+    return plugin;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "hono-svelte",
+  "version": "0.3.0",
+  "description": "Shell server-side + multi-entry Svelte pages for Hono apps",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test && npx publint",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "hono": "^4",
+    "svelte": "^5",
+    "vite": "^6 || ^7 || ^8"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
+    "@types/node": "^22.7.0",
+    "publint": "^0.3.24",
+    "svelte": "^5.57.0",
+    "typescript": "^5.6.0",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "keywords": [
+    "hono",
+    "svelte",
+    "vite",
+    "ssr",
+    "zero-js",
+    "middleware"
+  ]
+}