@temir.ra/create-hono-spa 0.1.0-pre.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Version 0
+
+## 0.1.0-pre.1
+
+1. First version of the template.

package/README.md

@@ -0,0 +1,214 @@
+# Introduction
+
+A template for single-page applications distributed as Hono sub-app libraries. The generated package bundles a frontend shell (HTML, JS, CSS, PWA manifest, favicon) as static assets and exposes a `createSpa()` function that returns a `Hono` instance serving them. Intended to be consumed by a [`@temir.ra/create-hono-server`](https://www.npmjs.com/package/@temir.ra/create-hono-server) backend, where it is mounted as a route group.
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [AI Assistant Context](#ai-assistant-context)
+3. [Documentation](#documentation)
+    1. [`template/`](#template)
+    2. [Architecture](#architecture)
+    3. [`src/spa.ts`](#srcspa-ts)
+    4. [`src/constants.ts`](#srcconstants-ts)
+    5. [`assets/`](#assets)
+4. [DevOps](#devops)
+    1. [Change Management](#change-management)
+    2. [Publish](#publish)
+        1. [npmjs.org](#npmjsorg)
+        2. [Custom registry](#custom-registry)
+
+# Quick Start
+
+*`bun create` caches the template package - a newer published version will not be picked up automatically. Pin the version or clear the cache to use the latest.*
+
+```bash
+# placeholder:
+    # <NEW_PACKAGE: <NEW_PACKAGE>
+    # <@_VERSION: <@_VERSION>
+
+# identify the latest version of the template package as <@_VERSION.
+bun info "@temir.ra/create-hono-spa" version
+# create a new library from the template version
+bun create --no-install --no-git "@temir.ra/hono-spa<@_VERSION>" <NEW_PACKAGE>
+
+# or
+
+# clear package manager cache to ensure the latest template version is used
+bun pm cache rm
+# create a new library from the latest template version
+bun create --no-install --no-git "@temir.ra/hono-spa" <NEW_PACKAGE>
+
+# dependencies must be installed manually
+cd <NEW_PACKAGE>
+bun install
+```
+
+# AI Assistant Context
+
+To generate an AI coding assistant context file for this project:
+
+> Generate an AI coding assistant context file. Analyze the project structure and source files, using this README as the primary reference for architecture and conventions. Give particular attention to: the SPA-as-library abstraction and how assets are served via import.meta.url without any file copying on the consuming server, the `./spa` export condition and createSpa() as the library's public API, and the base href patching mechanism that enables client-side routing regardless of mount path.
+
+# Documentation
+
+The following sections explain the configurations and conventions baked into the generated package.
+
+## `template/`
+
+The files in `template/` were created from the [`@temir.ra/ts-lib@0.5.0`](https://www.npmjs.com/package/@temir.ra/create-ts-lib/v/0.5.0) template and then updated to fit the needs of a Hono SPA template.
+
+```powershell
+bun create --no-install --no-git --force "@temir.ra/ts-lib@0.5.0" "template/"
+```
+
+[Official documentation](https://hono.dev/docs/) provided by the Hono team is a great resource.
+
+## Architecture
+
+The generated SPA package is a library - not a runnable server. It abstracts three things from the consuming server:
+
+**Asset serving** - All frontend assets (HTML shell, JS bundle, CSS, PWA manifest, favicon) are resolved from the package directory via `import.meta.url` and served by the sub-app itself. The consuming server does not configure static file serving or copy any files.
+
+**Client-side routing** - The `/app/*` wildcard returns `index.html` for every navigation path. The `<base href>` tag is patched at request time from `basePath` and `path`, so relative asset URLs resolve correctly wherever the sub-app is mounted.
+
+**PWA scaffold** - The `assets/` directory ships with the structure expected by browsers for PWA installation: manifest, favicon, and screenshots.
+
+The consuming server treats the package as an opaque route group passed to `endpointGroups`. See [`@temir.ra/create-hono-server`](https://www.npmjs.com/package/@temir.ra/create-hono-server) for the mount pattern.
+
+## `src/spa.ts`
+
+**Built-in routes:**
+
+| Path | Description |
+|---|---|
+| `/health` | Returns `ok` with status 200 |
+| `/buildinfo` | Returns the contents of `buildinfo.txt` |
+| `/app/*` | Serves `index.html` with runtime substitutions applied |
+| `/<faviconPath>` | Serves `favicon.svg` as `image/svg+xml` |
+| `/<webmanifestPath>` | Serves `manifest.webmanifest` as `application/manifest+json` |
+| `/<indexJsPath>` | Serves `dist/index.bundle.js` |
+| `/<indexCssPath>` | Serves `dist/index.css` |
+| `/<siteCssPath>` | Serves `dist/site.css` |
+
+**Options:**
+
+```typescript
+type CreateSpaOptions = {
+    basePath?: string;               // outer base path matching the server host's basePath
+    path?: string;                   // sub-path for this SPA within the server
+    metaDescriptionContent?: string; // replaces content="" in the description meta tag
+    faviconPath?: string;            // serve path for the favicon (default: 'favicon.svg')
+    webmanifestPath?: string;        // default: 'manifest.webmanifest'
+    vAppContainerId?: string;        // id attribute of the root app container div
+    indexJsPath?: string;            // default: 'index.js'
+    indexCssPath?: string;           // default: 'index.css'
+    siteCssPath?: string;            // default: 'site.css'
+}
+```
+
+## `src/constants.ts`
+
+```typescript
+export const packageUrl    = new URL('../',                         import.meta.url);
+export const buildinfoUrl  = new URL('buildinfo.txt',               packageUrl);
+export const distUrl       = new URL('dist/',                       packageUrl);
+export const indexJsUrl    = new URL('index.bundle.js',             distUrl);
+export const assetsUrl     = new URL('assets/@scope/package-name/', packageUrl);
+export const indexHtmlUrl  = new URL('index.html',                  assetsUrl);
+// ...
+```
+
+Replace `@scope/package-name` with your actual package name when adapting the template. Update `constants.ts` and rename the `assets/@scope/package-name/` directory to match.
+
+## `assets/`
+
+The template provides a PWA shell scaffold:
+
+```
+assets/
+└── @scope/
+    └── package-name/
+        ├── index.html                  ← SPA entry point; base href patched at request time
+        ├── favicon.svg
+        ├── manifest.webmanifest
+        └── images/
+            ├── mobile-screenshot.png   ← used in manifest for PWA install UI
+            └── wide-screenshot.png
+```
+
+`assets/` is included in the `files` field of `package.json` and published with the package. The naming convention (`assets/@scope/package-name/`) follows the asset resolution contract from [`@temir.ra/create-ts-lib`](https://www.npmjs.com/package/@temir.ra/create-ts-lib#asset-resolution) - scoped directories prevent naming collisions when multiple SPA packages coexist in the same server.
+
+# DevOps
+
+```bash
+# remove dist/ and tsconfig.build.tsbuildinfo
+bun run clean
+
+# remove dist/ only
+bun run clean:dist
+
+# remove tsconfig.build.tsbuildinfo only
+bun run clean:tsbuildinfo
+
+# compile + bundle
+bun run build
+
+# create a new test hono spa in example/
+bun run dist/cli.bundle.js -- example
+```
+
+**Publish** - see [Publish](#publish).
+
+## Change Management
+
+1. Create a new branch for the change.
+2. Make the changes and commit.
+3. Bump the version in [`package.json`](package.json).
+4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
+5. Pull request the branch.
+6. After merge, run `bun run build` - ensures artifacts are current before publish.
+7. Publish.
+
+## Publish
+
+See the following sources to configure the target registry and authentication.
+
+- [Configuring npm - `npmrc`](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc)
+- [Bun package manager - `install.registry`](https://bun.com/docs/runtime/bunfig#install-scopes)
+
+⚠️ Package Scope and the authentication for the target registry must be aligned.
+
+### `npmjs.org`
+
+Publish to the public npm registry.
+
+```powershell
+# authenticate
+npm login
+# publish
+bun publish --registry https://registry.npmjs.org/ --access public
+```
+
+### Custom registry
+
+```bash
+# placeholder:
+    # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
+    # <REGISTRY_URL: <REGISTRY_URL>
+    # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
+```
+
+`~/.bunfig.toml` or `bunfig.toml`:
+
+```toml
+[install.scopes]
+"<SCOPE_WITHOUT_AT>" = { url = "<REGISTRY_URL>", token = "$BUN_PUBLISH_AUTH_TOKEN" }
+```
+
+```powershell
+# authenticate
+$env:BUN_PUBLISH_AUTH_TOKEN = "<BUN_PUBLISH_AUTH_TOKEN>"
+# publish
+bun publish
+```

package/buildinfo.txt

@@ -0,0 +1 @@
+0.1.0-pre.1+bad3cf6

package/dist/cli.bundle.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import{cpSync as s,readFileSync as f,renameSync as u,writeFileSync as P}from"fs";import{resolve as t}from"path";import{resolve as o}from"path";import{fileURLToPath as h}from"url";var d=new URL("../",import.meta.url),n=o(h(d)),m=o(n,"template/"),p=o(n,"CHANGELOG.md"),g=o(n,"buildinfo.txt"),l=o(n,"README.md");try{let r=process.argv[2];if(!r)throw Error("Package name argument is required. Usage: `create-hono-spa <package-name>`");let a=r.replace(/\\/g,"/"),e=t(process.cwd(),a);s(m,e,{recursive:!0}),s(p,t(e,"CHANGELOG-template.md")),s(g,t(e,"buildinfo-template.txt")),s(l,t(e,"README-template.md"));let c=t(e,"package.json"),i=JSON.parse(f(c,"utf-8"));i.name=a,P(c,JSON.stringify(i,null,2)),u(t(e,"gitignore"),t(e,".gitignore")),console.log(`Template has been successfully instantiated at '${e}' with package name '${a}'.`)}catch(r){let a=r instanceof Error?r:Error(String(r));console.error("Error:",a.message),process.exit(1)}
+
+//# debugId=22A62DDB3C86A9D764756E2164756E21

package/dist/cli.bundle.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["..\\src\\cli.ts", "..\\src\\constants.ts"],
+  "sourcesContent": [
+    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve, basename } from 'path';\r\nimport {\r\n    templatePath,\r\n    changelogPath,\r\n    buildinfoPath,\r\n    readmePath\r\n} from './constants.js';\r\n\r\n\r\ntry {\r\n\r\n    const packageNameArgument = process.argv[2];\r\n    if (!packageNameArgument) throw new Error('Package name argument is required. Usage: `create-hono-spa <package-name>`');\r\n    const packageName = packageNameArgument.replace(/\\\\/g, '/');\r\n\r\n    const destinationPath = resolve(process.cwd(), packageName);\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));\r\n    cpSync(readmePath, resolve(destinationPath, 'README-template.md'));\r\n\r\n    const packageJsonPath = resolve(destinationPath, 'package.json');\r\n    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));\r\n    packageJson.name = packageName;\r\n    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));\r\n\r\n    renameSync(resolve(destinationPath, 'gitignore'), resolve(destinationPath, '.gitignore'));\r\n\r\n    console.log(`Template has been successfully instantiated at '${destinationPath}' with package name '${packageName}'.`);\r\n\r\n}\r\ncatch (error) {\r\n    const err = error instanceof Error ? error : new Error(String(error));\r\n    console.error('Error:', err.message);\r\n    process.exit(1);\r\n}\r\n",
+    "import { resolve } from 'path';\r\nimport { fileURLToPath } from 'url';\r\n\r\n\r\nexport const packageUrl: URL = new URL('../', import.meta.url);\r\nexport const packagePath: string = resolve(fileURLToPath(packageUrl));\r\n\r\nexport const templatePath: string = resolve(packagePath, 'template/');\r\n\r\nexport const changelogPath: string = resolve(packagePath, 'CHANGELOG.md');\r\nexport const buildinfoPath: string = resolve(packagePath, 'buildinfo.txt');\r\nexport const readmePath: string = resolve(packagePath, 'README.md');\r\n"
+  ],
+  "mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,aCHT,kBAAS,aACT,wBAAS,YAGF,IAAM,EAAkB,IAAI,IAAI,MAAO,YAAY,GAAG,EAChD,EAAsB,EAAQ,EAAc,CAAU,CAAC,EAEvD,EAAuB,EAAQ,EAAa,WAAW,EAEvD,EAAwB,EAAQ,EAAa,cAAc,EAC3D,EAAwB,EAAQ,EAAa,eAAe,EAC5D,EAAqB,EAAQ,EAAa,WAAW,EDClE,GAAI,CAEA,IAAM,EAAsB,QAAQ,KAAK,GACzC,GAAI,CAAC,EAAqB,MAAU,MAAM,4EAA4E,EACtH,IAAM,EAAc,EAAoB,QAAQ,MAAO,GAAG,EAEpD,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAW,EAE1D,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAe,EAAQ,EAAiB,uBAAuB,CAAC,EACvE,EAAO,EAAe,EAAQ,EAAiB,wBAAwB,CAAC,EACxE,EAAO,EAAY,EAAQ,EAAiB,oBAAoB,CAAC,EAEjE,IAAM,EAAkB,EAAQ,EAAiB,cAAc,EACzD,EAAc,KAAK,MAAM,EAAa,EAAiB,OAAO,CAAC,EACrE,EAAY,KAAO,EACnB,EAAc,EAAiB,KAAK,UAAU,EAAa,KAAM,CAAC,CAAC,EAEnE,EAAW,EAAQ,EAAiB,WAAW,EAAG,EAAQ,EAAiB,YAAY,CAAC,EAExF,QAAQ,IAAI,mDAAmD,yBAAuC,KAAe,EAGzH,MAAO,EAAO,CACV,IAAM,EAAM,aAAiB,MAAQ,EAAY,MAAM,OAAO,CAAK,CAAC,EACpE,QAAQ,MAAM,SAAU,EAAI,OAAO,EACnC,QAAQ,KAAK,CAAC",
+  "debugId": "22A62DDB3C86A9D764756E2164756E21",
+  "names": []
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { resolve, basename } from 'path';
+import { templatePath, changelogPath, buildinfoPath, readmePath } from './constants.js';
+try {
+    const packageNameArgument = process.argv[2];
+    if (!packageNameArgument)
+        throw new Error('Package name argument is required. Usage: `create-hono-spa <package-name>`');
+    const packageName = packageNameArgument.replace(/\\/g, '/');
+    const destinationPath = resolve(process.cwd(), packageName);
+    cpSync(templatePath, destinationPath, { recursive: true });
+    cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));
+    cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));
+    cpSync(readmePath, resolve(destinationPath, 'README-template.md'));
+    const packageJsonPath = resolve(destinationPath, 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    packageJson.name = packageName;
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+    renameSync(resolve(destinationPath, 'gitignore'), resolve(destinationPath, '.gitignore'));
+    console.log(`Template has been successfully instantiated at '${destinationPath}' with package name '${packageName}'.`);
+}
+catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    console.error('Error:', err.message);
+    process.exit(1);
+}

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const packageUrl: URL;
+export declare const packagePath: string;
+export declare const templatePath: string;
+export declare const changelogPath: string;
+export declare const buildinfoPath: string;
+export declare const readmePath: string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,EAAE,GAAqC,CAAC;AAC/D,eAAO,MAAM,WAAW,EAAE,MAA2C,CAAC;AAEtE,eAAO,MAAM,YAAY,EAAE,MAA0C,CAAC;AAEtE,eAAO,MAAM,aAAa,EAAE,MAA6C,CAAC;AAC1E,eAAO,MAAM,aAAa,EAAE,MAA8C,CAAC;AAC3E,eAAO,MAAM,UAAU,EAAE,MAA0C,CAAC"}

package/dist/constants.js

@@ -0,0 +1,8 @@
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+export const packageUrl = new URL('../', import.meta.url);
+export const packagePath = resolve(fileURLToPath(packageUrl));
+export const templatePath = resolve(packagePath, 'template/');
+export const changelogPath = resolve(packagePath, 'CHANGELOG.md');
+export const buildinfoPath = resolve(packagePath, 'buildinfo.txt');
+export const readmePath = resolve(packagePath, 'README.md');

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@temir.ra/create-hono-spa",
+  "version": "0.1.0-pre.1",
+  "description": "SPA template with Hono server backend",
+  "author": "temir.ra",
+  "license": "MIT",
+  "keywords": [
+    "typescript",
+    "template",
+    "hono",
+    "spa",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://git.chimps.quest/trs/create-hono-spa.git"
+  },
+  "type": "module",
+  "imports": {
+    "#src/*.js": "./src/*.ts"
+  },
+  "bin": "./dist/cli.bundle.js",
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "buildinfo.txt",
+    "template"
+  ],
+  "scripts": {
+    "clean:dist": "rm -rf dist/",
+    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
+    "prebuild": "bun run scripts/buildinfo.ts",
+    "tests": "bun test",
+    "build": "bun run build:lib && bun run build:cli-bundle",
+    "build:lib": "tsc --project tsconfig.build.json",
+    "build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  }
+}

package/template/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Version 0
+
+## 0.0.0
+
+1. Versioning initialized.

package/template/README.md

@@ -0,0 +1,115 @@
+# Introduction
+
+*<INTRO TEXT>*
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [AI Assistant Context](#ai-assistant-context)
+3. [Documentation](#documentation)
+4. [DevOps](#devops)
+    1. [Change Management](#change-management)
+    2. [Publish](#publish)
+        1. [npmjs.org](#npmjsorg)
+        2. [Custom registry](#custom-registry)
+
+# Quick Start
+
+```bash
+# remove dist/ and tsconfig.build.tsbuildinfo
+bun run clean
+
+# remove dist/ only
+bun run clean:dist
+
+# remove tsconfig.build.tsbuildinfo only
+bun run clean:tsbuildinfo
+
+# compile + bundle
+bun run build
+
+# run tests
+bun run tests
+
+# run src/dev.ts in watch mode
+bun run dev
+```
+
+**Publish** - see [Publish](#publish).
+
+# AI Assistant Context
+
+To generate an AI coding assistant context file for this project:
+
+> Generate an AI coding assistant context file. `README-template.md` is available now and documents the architectural conventions of this package — use it as your primary source. The generated context file must be self-contained: `README-template.md` will be deleted after context generation, so do not reference it in the output. Give particular attention to: the dual tsconfig setup and the import constraints it imposes, the `#src/*.js` alias and where it may and may not be used, the `./spa` export condition and createSpa() as the library's public API, the asset resolution via import.meta.url and why it is reliable when the package is loaded externalized, and the base href patching mechanism for client-side routing.
+
+# Documentation
+
+*<DOCUMENTATION>*
+
+## Asset Resolution
+
+*<!-- Remove this section if the library has no runtime assets. Replace `@scope/lib-name` throughout with the actual package name. -->*
+
+Assets are placed under `assets/@scope/lib-name/` (scoped to the package name to prevent collisions). They are resolved at runtime via `import.meta.url` and loaded with `fetch()` (browser) or `readFile` (Node). `assets/` must be listed in `files` in `package.json`.
+
+`import.meta.url` is reliable when the library is loaded as a discrete module (from CDN or `node_modules/`). When the consumer bundles the library, they must copy the assets - see below.
+
+### For consumers bundling this library
+
+Copy `node_modules/@scope/lib-name/assets/` into your build output alongside the bundle, preserving the relative path. No code configuration is required - only the file copy.
+
+# DevOps
+
+## Change Management
+
+1. Create a new branch for the change.
+2. Make the changes and commit.
+3. Bump the version in [`package.json`](package.json).
+4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
+5. Pull request the branch.
+6. After merge, run `bun run build` - ensures artifacts are current before publish.
+7. Publish.
+
+## Publish
+
+See the following sources to configure the target registry and authentication.
+
+- [Configuring npm - `npmrc`](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc)
+- [Bun package manager - `install.registry`](https://bun.com/docs/runtime/bunfig#install-scopes)
+
+⚠️ Package Scope and the authentication for the target registry must be aligned.
+
+### `npmjs.org`
+
+Publish to the public npm registry.
+
+```powershell
+# authenticate
+npm login
+# publish
+bun publish --registry https://registry.npmjs.org/ --access public
+```
+
+### Custom registry
+
+```bash
+# placeholder:
+    # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
+    # <REGISTRY_URL: <REGISTRY_URL>
+    # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
+```
+
+`~/.bunfig.toml` or `bunfig.toml`:
+
+```toml
+[install.scopes]
+"<SCOPE_WITHOUT_AT>" = { url = "<REGISTRY_URL>", token = "$BUN_PUBLISH_AUTH_TOKEN" }
+```
+
+```powershell
+# authenticate
+$env:BUN_PUBLISH_AUTH_TOKEN = "<BUN_PUBLISH_AUTH_TOKEN>"
+# publish
+bun publish
+```

package/template/assets/@scope/package-name/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" fill="currentColor" viewBox="0 0 192 192">
+  <text x="50%" y="50%" font-family="monospace" font-size="72" dominant-baseline="middle" text-anchor="middle">{app}</text>
+</svg>

package/template/assets/@scope/package-name/index.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<base href="/" />
+
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="description" content="" />
+    <meta name="viewport" content="width=device-width, interactive-widget=resizes-content" />
+
+    <link rel="icon" href="favicon.svg" sizes="any" type="image/svg+xml" />
+    <link rel="manifest" href="manifest.webmanifest" />
+
+</head>
+
+<body>
+    
+    <div id="" class="v-app-container"></div>
+    <script type="module" src="index.js"></script>
+    <link rel="stylesheet" href="index.css" />
+    <link rel="stylesheet" href="site.css" />
+
+</body>
+
+</html>

package/template/assets/@scope/package-name/manifest.webmanifest

@@ -0,0 +1,26 @@
+{
+  "name": "",
+  "short_name": "",
+  "id": "",
+  "start_url": "",
+  "display": "standalone",
+  "icons": [
+    {
+      "src": "favicon.svg",
+      "sizes": "192x192",
+      "type": "image/svg+xml"
+    }
+  ],
+  "screenshots": [
+    {
+      "src": "images/wide-screenshot.png",
+      "type": "image/png",
+      "sizes": "1280x720"
+    },
+    {
+      "src": "images/mobile-screenshot.png",
+      "type": "image/png",
+      "sizes": "414x896"
+    }
+  ]
+}

package/template/gitignore

@@ -0,0 +1,7 @@
+dist
+node_modules
+buildinfo.txt
+*.tsbuildinfo
+buildinfo-template.txt
+CHANGELOG-template.md
+README-template.md

package/template/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "",
+  "version": "0.0.0+FE",
+  "description": "",
+  "author": "",
+  "license": "",
+  "keywords": [
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "entrypoint": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.bundle.js",
+      "import": "./dist/index.js"
+    },
+    "./spa": {
+      "entrypoint": "./src/spa.ts",
+      "types": "./dist/spa.d.ts",
+      "browser": "./dist/spa.bundle.js",
+      "import": "./dist/spa.js"
+    }
+  },
+  "imports": {
+    "#src/*.js": "./src/*.ts"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "buildinfo.txt",
+    "assets"
+  ],
+  "scripts": {
+    "clean:dist": "rm -rf dist/",
+    "clean:tsbuildinfo": "rm -f tsconfig.build.tsbuildinfo",
+    "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
+    "prebuild": "bun run scripts/buildinfo.ts",
+    "tests": "bun test",
+    "build": "bun run build:lib && bun run build:lib-bundle",
+    "build:lib": "tsc --project tsconfig.build.json",
+    "build:lib-bundle": "bun run scripts/build-lib-bundle.ts",
+    "typecheck": "tsc --noEmit",
+    "dev": "bun run --watch src/dev.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3",
+    "hono": "^4.12.5"
+  }
+}

package/template/scripts/build-lib-bundle.ts

@@ -0,0 +1,156 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import CDN_REWRITE_MAP from './cdn-rewrite-map.json';
+
+
+interface ExportConditions {
+    [key: string]: string | undefined;
+    import?: string;
+    types?: string;
+    browser?: string;
+    entrypoint?: string;
+}
+
+interface DependencyMap {
+    [packageName: string]: string;
+}
+
+interface PackageManifest {
+    version: string;
+    exports?: Record<string, ExportConditions>;
+    dependencies?: DependencyMap;
+    devDependencies?: DependencyMap;
+    peerDependencies?: DependencyMap;
+}
+
+function getManifest(packageIdentifier?: string): PackageManifest {
+
+    const manifestPath = packageIdentifier
+        ? join('node_modules', packageIdentifier, 'package.json')
+        : 'package.json';
+
+    let manifest: PackageManifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    } catch {
+        if (packageIdentifier)
+            throw new Error("[scripts/build-lib-bundle.ts] Could not read manifest for '" + packageIdentifier + "' at '" + manifestPath + "'. Is it installed?");
+        else
+            throw new Error("[scripts/build-lib-bundle.ts] Could not read package manifest at '" + manifestPath + "'.");
+    }
+
+    return manifest;
+
+}
+
+function getManifestEntrypoints(packageManifest: PackageManifest): string[] {
+
+    const exports = packageManifest.exports;
+    if (!exports) throw new Error('[scripts/build-lib-bundle.ts] No exports field found in package.json.');
+
+    const entrypoints = Object.entries(exports)
+        .map(([key, conditions]) => {
+            if (!conditions.entrypoint) throw new Error(`[scripts/build-lib-bundle.ts] Export '${key}' does not have an 'entrypoint' condition.`);
+            return conditions.entrypoint;
+        });
+
+    return entrypoints;
+
+}
+
+function getPackageVersion(manifest: PackageManifest, packageIdentifier?: string): string {
+
+    let version: string | undefined;
+    if (packageIdentifier) {
+
+        const dependencies = {
+            ...manifest.dependencies,
+            ...manifest.devDependencies,
+            ...manifest.peerDependencies,
+        };
+
+        version = dependencies[packageIdentifier];
+        if (!version) throw new Error(`[scripts/build-lib-bundle.ts] Package '${packageIdentifier}' is not listed in dependencies.`);
+
+    }
+    else {
+        if (!manifest.version) throw new Error('[scripts/build-lib-bundle.ts] Package manifest does not contain a version field.');
+        version = manifest.version;
+    }
+
+    return version;
+
+}
+
+function resolveCdnUrl(importSpecifier: string, urlTemplate: string): string {
+    const manifest = getManifest();
+    const version = getPackageVersion(manifest, importSpecifier);
+    return urlTemplate.replace('<VERSION>', version);
+}
+
+const cdnRewritePlugin = {
+    name: 'cdn-rewrite',
+    setup(build: any) {
+
+        const resolved = new Map<string, string>();
+        for (const [importSpecifier, urlTemplate] of Object.entries(CDN_REWRITE_MAP) as [string, string][]) {
+            const url = resolveCdnUrl(importSpecifier, urlTemplate);
+            resolved.set(importSpecifier, url);
+            console.log(`[cdn-rewrite] '${importSpecifier}' → '${url}'`);
+        }
+
+        build.onResolve({ filter: /\*/ }, (args: any) => {
+            const url = resolved.get(args.path);
+            if (url) return { path: url, external: true };
+        });
+
+    },
+};
+
+
+const entrypoints = getManifestEntrypoints(getManifest());
+console.log('[scripts/build-lib-bundle.ts] Entrypoints:', entrypoints);
+
+let buildResult;
+
+console.log('[scripts/build-lib-bundle.ts] Starting ESM bundle build...');
+buildResult = await Bun.build({
+    entrypoints,
+    outdir: 'dist',
+    naming: '[dir]/[name].bundle.[ext]',
+    target: 'browser',
+    format: 'esm',
+    minify: true,
+    sourcemap: 'external',
+    plugins: [cdnRewritePlugin],
+});
+
+if (!buildResult.success) {
+    console.error('[scripts/build-lib-bundle.ts] Build failed:');
+    for (const message of buildResult.logs) {
+        console.error(message);
+    }
+    process.exit(1);
+}
+console.log('[scripts/build-lib-bundle.ts] ESM bundle build completed successfully.');
+
+console.log('[scripts/build-lib-bundle.ts] Starting IIFE bundle build...');
+buildResult = await Bun.build({
+    entrypoints,
+    outdir: 'dist',
+    naming: '[dir]/[name].iife.[ext]',
+    target: 'browser',
+    format: 'iife',
+    minify: true,
+    sourcemap: 'external',
+    plugins: [cdnRewritePlugin],
+});
+
+if (!buildResult.success) {
+    console.error('[scripts/build-lib-bundle.ts] Build failed:');
+    for (const message of buildResult.logs) {
+        console.error(message);
+    }
+    process.exit(1);
+}
+console.log('[scripts/build-lib-bundle.ts] IIFE bundle build completed successfully.');

package/template/scripts/buildinfo.ts

@@ -0,0 +1,25 @@
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync } from 'fs';
+
+
+const BUILD_INFO_FILE = 'buildinfo.txt';
+const GIT_COMMAND = 'git rev-parse --short HEAD';
+
+const version: string = JSON.parse(readFileSync('package.json', 'utf-8')).version;
+
+let gitHash = '';
+try {
+    gitHash = execSync(GIT_COMMAND, { stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString()
+        .trim();
+} catch { }
+
+const buildinfo = gitHash
+    ? version.includes('+')
+        ? `${version}.${gitHash}`
+        : `${version}+${gitHash}`
+    : version;
+
+writeFileSync(BUILD_INFO_FILE, buildinfo.trim(), 'utf-8');
+
+console.log(`'${BUILD_INFO_FILE}' has been updated with build info: ${buildinfo}`);

package/template/scripts/cdn-rewrite-map.json

@@ -0,0 +1 @@
+{}

package/template/src/constants.ts

@@ -0,0 +1,14 @@
+
+export const packageUrl: URL = new URL('../', import.meta.url);
+
+export const buildinfoUrl: URL = new URL('buildinfo.txt', packageUrl);
+
+export const distUrl: URL = new URL('dist/', packageUrl);
+export const indexJsUrl: URL = new URL('index.bundle.js', distUrl);
+export const indexCssUrl: URL = new URL('index.css', distUrl);
+export const siteCssUrl: URL = new URL('site.css', distUrl);
+
+export const assetsUrl: URL = new URL('assets/@scope/package-name/', packageUrl);
+export const indexHtmlUrl: URL = new URL('index.html', assetsUrl);
+export const webmanifestUrl: URL = new URL('manifest.webmanifest', assetsUrl);
+export const faviconUrl: URL = new URL('favicon.svg', assetsUrl);

package/template/src/spa.ts

@@ -0,0 +1,135 @@
+import { Hono, type Env } from 'hono';
+import {
+    buildinfoUrl,
+    faviconUrl,
+    indexCssUrl,
+    indexHtmlUrl,
+    indexJsUrl,
+    siteCssUrl,
+    webmanifestUrl
+} from './constants.js';
+
+
+type CreateSpaOptions = {
+    basePath?: string,
+    path?: string,
+    metaDescriptionContent?: string,
+    faviconPath?: string,
+    webmanifestPath?: string,
+    indexCssPath?: string,
+    vAppContainerId?: string,
+    indexJsPath?: string,
+    siteCssPath?: string,
+}
+export function createSpa<E extends Env>(options: CreateSpaOptions): Hono<E> {
+
+    const trimmedBasePath = options.basePath ? options.basePath.trim().replace(/^\/+/, '').replace(/\/+$/, '') : '';
+    const trimmedPath = options.path ? options.path.trim().replace(/^\/+/, '').replace(/\/+$/, '') : '';
+    const baseHref =
+        (trimmedBasePath ? `/${trimmedBasePath}/` : '/')
+        +
+        (trimmedPath ? `${trimmedPath}/` : '')
+        ;
+
+    const spa = new Hono<E>().basePath(`/${trimmedPath}`);
+
+    spa.get('/health', (c) => c.text('OK'));
+    spa.get('/buildinfo', async (c) => {
+        try {
+            const buildInfo = await fetch(buildinfoUrl).then(res => res.text());
+            return c.text(buildInfo);
+        } catch (error) {
+            throw error;
+            return c.status(500);
+        }
+    });
+
+    spa.get('/app/*', async (c) => {
+        try {
+
+            let indexHtml = await fetch(indexHtmlUrl).then(res => res.text());
+
+            indexHtml = indexHtml.replace('<base href="/" />', `<base href="${baseHref}" />`);
+
+            if (options.metaDescriptionContent)
+                indexHtml = indexHtml.replace('<meta name="description" content="" />', `<meta name="description" content="${options.metaDescriptionContent}" />`);
+
+            if (options.faviconPath)
+                indexHtml = indexHtml.replace('<link rel="icon" href="favicon.svg" sizes="any" type="image/svg+xml" />', `<link rel="icon" href="${options.faviconPath}" sizes="any" type="image/svg+xml" />`);
+
+            if (options.webmanifestPath)
+                indexHtml = indexHtml.replace('<link rel="manifest" href="manifest.webmanifest" />', `<link rel="manifest" href="${options.webmanifestPath}" />`);
+
+            if (options.vAppContainerId)
+                indexHtml = indexHtml.replace('<div id="" class="v-app-container"></div>', `<div id="${options.vAppContainerId}" class="v-app-container"></div>`);
+
+            if (options.indexJsPath)
+                indexHtml = indexHtml.replace('<script type="module" src="index.js"></script>', `<script type="module" src="${options.indexJsPath}"></script>`);
+
+            if (options.indexCssPath)
+                indexHtml = indexHtml.replace('<link rel="stylesheet" href="index.css" />', `<link rel="stylesheet" href="${options.indexCssPath}" />`);
+
+            if (options.siteCssPath)
+                indexHtml = indexHtml.replace('<link rel="stylesheet" href="site.css" />', `<link rel="stylesheet" href="${options.siteCssPath}" />`);
+
+            return c.html(indexHtml);
+
+        } catch (error) {
+            throw error;
+            return c.status(500);
+        }
+    });
+
+    spa.get(`/${options.faviconPath || 'favicon.svg'}`, async (c) => {
+        try {
+            const svg = await fetch(faviconUrl).then(res => res.text());
+            return c.text(svg, 200, { 'Content-Type': 'image/svg+xml' });
+        } catch (error) {
+            throw error;
+            return c.status(500);
+        }
+    });
+
+    spa.get(`/${options.webmanifestPath || 'manifest.webmanifest'}`, async (c) => {
+        try {
+            const webmanifest = await fetch(webmanifestUrl).then(res => res.json());
+            return c.json(webmanifest, 200, { 'Content-Type': 'application/manifest+json', });
+        } catch (error) {
+            throw error;
+            return c.status(500);
+        }
+    });
+
+    spa.get(`/${options.indexJsPath || 'index.js'}`, async (c) => {
+        try {
+            const js = await fetch(indexJsUrl).then(res => res.text());
+            return c.text(js, 200, { 'Content-Type': 'application/javascript' });
+        } catch (error) {
+            throw error;
+            return c.status(500);
+        }
+    });
+
+    spa.get(`/${options.indexCssPath || 'index.css'}`, async (c) => {
+        try {
+            const css = await fetch(indexCssUrl).then(res => res.text());
+            return c.text(css, 200, { 'Content-Type': 'text/css' });
+        } catch (error) {
+            throw error;
+            return c.status(500);
+        }
+    });
+
+    spa.get(`/${options.siteCssPath || 'site.css'}`, async (c) => {
+        try {
+            const css = await fetch(siteCssUrl).then(res => res.text());
+            return c.text(css, 200, { 'Content-Type': 'text/css' });
+        } catch (error) {
+            throw error;
+            return c.status(500);
+        }
+    });
+
+    return spa;
+
+}

package/template/tests/buildinfo.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'bun:test';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+
+const buildinfoUrl = new URL('../buildinfo.txt', import.meta.url);
+
+// taken from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+// Captures: [1]=major, [2]=minor, [3]=patch, [4]=pre-release, [5]=build-metadata
+const SEMVER_REGEX =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+function readBuildinfo(): string {
+    return readFileSync(fileURLToPath(buildinfoUrl), 'utf-8').trim();
+}
+
+describe('buildInfo', () => {
+
+    it('should be a valid semver string', () => {
+        expect(readBuildinfo()).toMatch(SEMVER_REGEX);
+    });
+
+});

package/template/tsconfig.build.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "emitDeclarationOnly": false,
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/dev.ts",
+    "node_modules",
+    "dist",
+    "tests",
+    "scripts"
+  ]
+}

package/template/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "isolatedDeclarations": true,
+    "esModuleInterop": true,
+    "composite": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+  },
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "scripts/**/*.ts",
+    "scripts/**/*.json"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}