hono-svelte 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.3.1
+
+- Package metadata: repository/homepage/author, publishConfig, LICENSE + CHANGELOG in files.
+- No code changes since 0.3.0.
+
+## 0.3.0
+
+- Fully in-memory package: entries and manifest are virtual modules (no files written to disk).
+- Automatic zero-JS: `.svelte` pages without `<script>` render on the server (`svelte/server`)
+  and download no JS on the client.
+- Deterministic opaque IDs derived from the entryName (no salt, no env, no disk).
+- Zero config: the shell resolves the SSR map on its own (relative import redirected by the plugin).
+- Test suite (vitest) and CI (typecheck + tests + build + publint).
+
+## 0.2.0
+
+- Opaque IDs (`r-` + hash) replace configurable `rootId`/`dataId`.
+
+## 0.1.0
+
+- First version: `shell()` middleware + `pages()` plugin with disk-generated entries.

package/README.md

@@ -1,71 +1,187 @@
 # 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
+Render Svelte 5 pages in Hono apps with a single `c.render("page")` — no SPA, no build boilerplate.
+
+Each `.svelte` file becomes an independent page. Static pages reach the browser as ready-made HTML with **zero JavaScript**. Interactive pages receive only their own JS. Works in dev with HMR and in production with per-page bundles.
+
+## Why use it
+
+Real sites and dashboards mix simple pages (landing, login, terms) with interactive screens (panels, forms). In a traditional SPA, a landing visitor downloads the entire dashboard's JS. With hono-svelte:
+
+- **Static pages cost zero JS** — HTML arrives ready from the server;
+- **Interactive pages cost only their own JS** — independent bundles, no loading the rest of the app;
+- **Public initial data ships in the HTML** — the page mounts with content, no extra fetch;
+- **Sensitive data stays in the API** — typed end to end with the Hono client.
+
+## Installation
+
+Requires Node 22+, Hono 4, Svelte 5, and Vite 6/7/8.
+
+```sh
+npm install hono-svelte
+```
+
+## Quick start
+
+**1. Configure Vite** — add the pages plugin in every mode and use the entry list in the client build:
 
 ```ts
-// vite.config.ts
+import build from "@hono/vite-build/node";
+import devServer from "@hono/vite-dev-server";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
 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.
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+
+const appPages = pages();
+
+export default defineConfig(({ command, mode }) => {
+  if (mode === "client") {
+    return {
+      plugins: [svelte(), appPages],
+      build: {
+        rollupOptions: {
+          input: { ...appPages.input(), styles: resolve("src/styles.css") },
+          output: {
+            entryFileNames: "static/[name].js",
+            chunkFileNames: "static/chunks/[name]-[hash].js",
+            assetFileNames: "static/[name][extname]",
+          },
+        },
+      },
+    };
+  }
+
+  if (command === "serve") {
+    return {
+      plugins: [svelte(), appPages, devServer({ entry: "src/routes/index.ts" })],
+    };
+  }
+
+  return {
+    plugins: [svelte(), appPages, build({ entry: "src/routes/index.ts", staticRoot: "./dist" })],
+  };
+});
 ```
 
+**2. Register the shell on the server:**
+
 ```ts
-// servidor
+import { Hono } from "hono";
 import { shell } from "hono-svelte";
 
-app.use("/*", shell({ title: "Meu App", lang: "pt-BR" }));
-app.get("/dashboard", (c) => c.render("dashboard", { data: { plan: "pro" } }));
+const app = new Hono().use("/*", shell({ title: "My App", lang: "en" }));
 ```
 
+**3. Create pages** in `src/pages` — one page per file:
+
 ```svelte
-<!-- pagina estatica: sem <script> => zero-JS, HTML vem pronto do servidor -->
-<main>...</main>
+<!-- src/pages/home.svelte — no <script>: becomes plain HTML, zero JS -->
+<main>
+  <h1>Welcome</h1>
+  <a href="/dashboard">Sign in</a>
+</main>
+```
+
+```svelte
+<!-- src/pages/dashboard.svelte — has <script>: gets its own JS -->
+<script lang="ts">
+  import { hc } from "hono/client";
+  import type { AppType } from "../routes/api";
+
+  let { plan } = $props<{ plan: string }>();
+  const client = hc<AppType>("/");
+
+  let time = $state("--:--");
+  async function refresh() {
+    const res = await client.api.time.$get();
+    time = (await res.json()).time;
+  }
+</script>
+
+<main>
+  <h1>Dashboard — {plan} plan</h1>
+  <p>Server time: {time}</p>
+  <button onclick={refresh}>Refresh</button>
+</main>
+```
+
+**4. Render in routes:**
+
+```ts
+app.get("/", (c) => c.render("home"));
+app.get("/dashboard", (c) => c.render("dashboard", { data: { plan: "pro" } }));
+```
+
+The rule is simple: **if the `.svelte` file has no `<script>`, the page ships as plain HTML. If it has one, it hydrates on the client** with initial data available via `$props()`.
+
+Files starting with `_` and `layout.svelte` are ignored (convention for partials and layouts).
+
+## Passing data to the page
+
+Small, public initial data (plan name, title, preferences) goes in `data` and arrives via `$props()` — no extra request:
+
+```ts
+app.get("/dashboard", (c) => c.render("dashboard", { data: { plan: "pro" } }));
 ```
 
-## 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>;
-  }
-}
+
+## API
+
+### `shell(options?)`
+
+Hono middleware that provides `c.render(entry, { title?, data? })` on every route.
+
+| Option | Default | Description |
+|---|---|---|
+| `title` | `"App"` | Title used when the route doesn't provide one |
+| `lang` | `"en"` | `<html>` `lang` attribute |
+| `assetsBase` | `"/static"` | Prefix for JS files in production |
+| `stylesHref` | `"/static/styles.css"` in prod, `"/src/styles.css"` in dev | Global stylesheet (or an `(isProd) => string` function) |
+| `head` | `""` | Extra HTML in `<head>` (fonts, meta tags) |
+
+### `pages(options?)`
+
+Vite plugin (`hono-svelte/vite`) that discovers pages and generates client entries.
+
+| Option | Default | Description |
+|---|---|---|
+| `pagesDir` | `"src/pages"` | Pages folder |
+| `ignore` | `["**/layout.svelte", "**/_*.svelte"]` | Ignored patterns |
+| `alwaysClient` | `[]` | Pages that always get JS, even without `<script>` |
+
+Handy methods: `input()` (client build entries), `entries()` (all pages), `staticEntries()` (static pages only), `hasClient(entry)`.
+
+### Typing `c.render`
+
+So TypeScript accepts `c.render` in routes, declare once in the app:
+
+```ts
+import type { RenderProps } from "hono-svelte";
+
+declare module "hono" {
+  interface ContextRenderer {
+    (entryName: string, props?: RenderProps): Response | Promise<Response>;
+  }
+}
+```
+
+## Production tips
+
+- Serve hashed files with long cache and `immutable`; the stylesheet with short cache or a versioned name.
+- Works with `script-src 'self'` — there is no executable inline script on the page.
+- Run both client and server builds before serving; the example in `examples/playground/` shows the full setup.
+
+## Example
+
+`examples/playground/` is a real Hono app using the package: static landing, login, and a dashboard with typed RPC and cookie session. To run it:
+
+```sh
+cd examples/playground && npm install && npm run build
 ```
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Changelog in [CHANGELOG.md](./CHANGELOG.md).
+
+Anything sensitive, large, or frequently changing stays in the API, fetched after mount with the typed Hono client (`hc<AppType>`) — with the session in an `HttpOnly` cookie as usual. Never put secrets in `data`: it is visible in the HTML.

package/dist/ids.js

@@ -1,6 +1,6 @@
-// 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.
+// Opaque IDs derived from the entryName. Pure, no runtime dependencies.
+// (works on Node, Workers, Deno, Bun). Not a state secret:
+// it just avoids exposing server internals in the HTML.
 function hashString(input) {
     let h1 = 0xdeadbeef;
     let h2 = 0x41c6ce57;

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export type ShellOptions = {
     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). */
+    /** Manual override of the entryName -> loader map (optional; otherwise the shell
+     *  resolves the map automatically via ssr-manifest). */
     ssrPages?: Record<string, SsrPageLoader>;
 };
 export type ShellContext = {

package/dist/index.js

@@ -23,7 +23,7 @@ function serializePageData(data, dataId) {
         json = JSON.stringify(data);
     }
     catch {
-        throw new Error("hono-svelte: props.data precisa ser serializavel em JSON");
+        throw new Error("hono-svelte: props.data must be JSON-serializable");
     }
     if (json === undefined)
         return "";
@@ -39,13 +39,13 @@ export function shell(options = {}) {
     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").
+    // Zero config: with pages() active, this module is redirected to the
+    // in-memory manifest by the plugin's resolveId (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)}`);
+                throw new Error(`hono-svelte: invalid entryName: ${JSON.stringify(entryName)}`);
             }
             const ids = getIds(entryName);
             const title = props?.title ?? titleDefault;

package/dist/ssr-manifest.js

@@ -1,6 +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.
+// Static stub used by the shell when the hono-svelte/vite plugin (pages())
+// is not active in the bundler: no static pages, every entry
+// is client-side. With pages() active, the plugin resolveId (enforce: 'pre')
+// redirects the shell relative import './ssr-manifest.js' to the
+// virtual manifest generated in memory.
 export const ssrPages = {};

package/dist/virtual.js

@@ -1,6 +1,6 @@
-// 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.
+// IDs of the virtual modules shared between the plugin (hono-svelte/vite)
+// and the shell (hono-svelte). Nothing is written to disk: entries and the manifest
+// are served in-memory as virtual modules.
 const NULL = String.fromCharCode(0);
 export const ENTRY_PREFIX = "virtual:hono-svelte/entry/";
 export const ENTRY_RESOLVED_PREFIX = NULL + ENTRY_PREFIX;
@@ -12,8 +12,8 @@ export function entryVirtualId(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.
+// Dev URL for the <script type='module'> generated by the shell.
+// \0 becomes __x00__ in the URL served by the Vite dev server.
 export function devEntryUrl(entryName) {
     return "/@id/" + entryResolvedId(entryName).replace(NULL, "__x00__");
 }

package/dist/vite.d.ts

@@ -2,7 +2,7 @@ import { type Plugin } from "vite";
 export type PagesOptions = {
     pagesDir?: string;
     ignore?: string[];
-    /** entryNames que sempre geram client JS, mesmo sem <script>. */
+    /** entryNames that always generate client JS, even without a `<script>`. */
     alwaysClient?: string[];
     generatedHeader?: string;
 };

package/dist/vite.js

@@ -14,7 +14,7 @@ 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 header = options.generatedHeader ?? "// @generated - hono-svelte, do not edit.";
     const filter = createFilter(["**/*.svelte"], ignore, { resolve: pagesDir });
     let cachedPages = null;
     let cachedInput = {};
@@ -29,12 +29,12 @@ export function pages(options = {}) {
         for (const file of files) {
             const entryName = entryNameFromFile(file);
             if (seen.has(entryName)) {
-                throw new Error(`hono-svelte: entry duplicado: ${entryName}`);
+                throw new Error(`hono-svelte: duplicate entry: ${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.
+            // Automatic zero-JS: a page without <script> has no interactivity,
+            // so the shell renders it on the server and the client downloads no JS.
             const hasScript = /<script[\s>]/i.test(readFileSync(absFile, "utf8"));
             result.push({ entryName, file, absFile, isStatic: !hasScript && !alwaysClient.has(entryName) });
         }
@@ -52,7 +52,7 @@ export function pages(options = {}) {
         }
         if (log) {
             const staticCount = cachedPages.length - jsCount;
-            console.log("[hono-svelte] " + jsCount + " pagina(s) com JS + " + staticCount + " estatica(s), tudo in-memory");
+            console.log("[hono-svelte] " + jsCount + " page(s) with JS + " + staticCount + " static(s), all in-memory");
         }
     }
     function listPages() {
@@ -97,7 +97,7 @@ export function pages(options = {}) {
     }
     function entrySource(page) {
         const ids = getIds(page.entryName);
-        return (header + " Origem: " + page.file + "\n" +
+        return (header + " Source: " + 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" +
@@ -107,8 +107,8 @@ export function pages(options = {}) {
     }
     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.
+        // pre: must run BEFORE vite:resolve to intercept the shell's
+        // relative import ("./ssr-manifest.js") and redirect it to the manifest.
         enforce: "pre",
         configResolved(config) {
             viteRoot = config.root;
@@ -117,15 +117,15 @@ export function pages(options = {}) {
             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.
+            // Virtual manifest: explicit (virtual:hono-svelte/manifest, backwards compat)
+            // or the shell's own relative import. Without pages() active, the
+            // relative import resolves the static dist/ssr-manifest.js stub.
             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()
+            // already-resolved ids (\0...) go straight through to load()
             if (source === MANIFEST_RESOLVED || source.startsWith(ENTRY_RESOLVED_PREFIX)) {
                 return source;
             }
@@ -138,7 +138,7 @@ export function pages(options = {}) {
                 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);
+                    throw new Error("hono-svelte: no page found for entry: " + entryName);
                 }
                 return entrySource(page);
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hono-svelte",
-  "version": "0.3.0",
-  "description": "Shell server-side + multi-entry Svelte pages for Hono apps",
+  "version": "0.3.1",
+  "description": "Server-side shell + multi-entry Svelte pages for Hono apps",
   "type": "module",
   "exports": {
     ".": {
@@ -15,7 +15,9 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -49,5 +51,14 @@
     "ssr",
     "zero-js",
     "middleware"
-  ]
+  ],
+  "author": "omarcos",
+  "homepage": "https://github.com/omarcosr/hono-svelte",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omarcosr/hono-svelte.git"
+  }
 }