create-honovel 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# Create Honovel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The default distribution is public on npmjs and requires no installation login.
+
+Create a Cloudflare Workers application with an optional Nuxt frontend:
+
+```sh
+npm create honovel@latest my-app
+npm create honovel@latest my-web-app -- --frontend=nuxt
+npm create honovel@latest my-api -- --api-only
+```
+
+The backend is always Cloudflare Workers. Without an explicit option, the installer asks whether to include Nuxt or create an API-only project. Nuxt is the default in non-interactive environments. `--frontend=none` is equivalent to `--api-only`; both `--frontend=value` and `--frontend value` work. Use `--no-install` to scaffold without installing dependencies. Existing directories are never overwritten.
+
+The explicit initializer is `npx create-honovel@latest my-app --frontend=nuxt`. The previous `--template=node|cloudflare` runtime selection has been removed.
+
+Both project modes include a health endpoint at `/api/health`, the application-level `/api` controller base, an empty D1 database schema, Durable Object cache/cache-backed locks, a Cloudflare Queue adapter and generated Cron Trigger support. No Todo table or initial SQL migration is created. Shared compiler/dev/build helpers ship in `honovel`, without a copied `scripts/` directory.
+
+With Nuxt, `npm run dev` starts the backend and frontend; open `http://localhost:5173`. Nuxt proxies API and documentation requests to Wrangler. `npm run build` generates the static frontend into `dist/frontend` and bundles the Worker into `dist/worker`; deployment attaches Workers Static Assets.
+
+For API-only projects, `npm run dev` starts only Wrangler at `http://localhost:8788`. There is no `frontend/` directory, Nuxt/Vue/Tailwind dependency, frontend npm script or static assets configuration. Build, typecheck and deployment only process the backend.
+
+Releases publish `honovel` and `create-honovel` to the public npm registry, linked to [Honovel/framework](https://github.com/Honovel/framework). The framework includes its Cloudflare adapters under `honovel/cloudflare`.

package/bin/create-honovel.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import readline from "node:readline/promises";
+const packageRoot = fileURLToPath(new URL("../", import.meta.url));
+const metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+async function main() {
+  const args = process.argv.slice(2);
+  if (!args.length || args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: npm create honovel@latest <project-name> [--frontend=nuxt|none] [--api-only] [--no-install]\nThe backend is always Cloudflare Workers. If no frontend option is given, the installer asks whether to include Nuxt (the non-interactive default).");
+    return;
+  }
+  const [name, ...options] = args;
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) throw new Error("Use a project name containing lowercase letters, digits, hyphens, or underscores.");
+  let frontend = "nuxt";
+  let frontendSelected = false;
+  let install = true;
+  for (let index = 0; index < options.length; index++) {
+    const option = options[index];
+    if (option === "--no-install") {
+      install = false;
+    } else if (option === "--api-only" || option === "--frontend" || option.startsWith("--frontend=")) {
+      if (frontendSelected) throw new Error("Select the frontend only once; do not combine --api-only and --frontend.");
+      frontendSelected = true;
+      frontend = option === "--api-only" ? "none" : option === "--frontend" ? options[++index] : option.slice("--frontend=".length);
+      if (!["nuxt", "none"].includes(frontend)) throw new Error("Supported frontend options: nuxt, none.");
+    } else if (option === "--template" || option.startsWith("--template=")) {
+      throw new Error("All projects use Cloudflare Workers. Use --frontend=nuxt, --frontend=none or --api-only.");
+    } else throw new Error("Unknown option. Supported: --frontend=nuxt|none, --api-only, --no-install");
+  }
+  if (!frontendSelected) frontend = await chooseFrontend();
+  if (name.length > 63) throw new Error("Cloudflare project names must be at most 63 characters long.");
+  const target = path.resolve(name);
+  if (fs.existsSync(target)) throw new Error(`${name} already exists. Choose a new directory.`);
+  fs.mkdirSync(target);
+  function copy(directory, destination) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const source = path.join(directory, entry.name);
+      const outputName = entry.name === "env.example.template" ? ".env.example" : entry.name.replace(/\.template$/, "");
+      const output = path.join(destination, outputName);
+      if (entry.isDirectory()) {
+        fs.mkdirSync(output, { recursive: true });
+        copy(source, output);
+      } else {
+        if (/\.(png|jpe?g|gif|webp|ico|woff2?)$/i.test(entry.name)) {
+          fs.copyFileSync(source, output);
+          continue;
+        }
+        const content = fs.readFileSync(source, "utf8").replaceAll("__PROJECT_NAME__", name).replaceAll("__WORKER_NAME__", name.replaceAll("_", "-")).replaceAll("__HONOVEL_VERSION__", metadata.version);
+        if (fs.existsSync(output) && ["package.json", "wrangler.jsonc"].includes(outputName)) {
+          const current = JSON.parse(fs.readFileSync(output, "utf8"));
+          const overlay = JSON.parse(content);
+          const merged = { ...current, ...overlay };
+          if (outputName === "package.json") {
+            for (const section of ["scripts", "dependencies", "devDependencies", "overrides"]) {
+              merged[section] = { ...current[section], ...overlay[section] };
+            }
+          }
+          fs.writeFileSync(output, JSON.stringify(merged, null, 2) + "\n");
+        } else fs.writeFileSync(output, content);
+      }
+    }
+  }
+  copy(path.join(packageRoot, "template/common"), target);
+  copy(path.join(packageRoot, "template/cloudflare"), target);
+  if (frontend === "nuxt") copy(path.join(packageRoot, "template/nuxt"), target);
+  const envExamplePath = path.join(target, ".env.example");
+  const envPath = path.join(target, ".env");
+  if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+    const localEnv = fs.readFileSync(envExamplePath, "utf8").replace(/^APP_DEBUG=.*$/m, "APP_DEBUG=true");
+    fs.writeFileSync(envPath, localEnv, { flag: "wx" });
+  }
+  if (install) {
+    const result = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", ["install", "--loglevel=error"], { cwd: target, stdio: "inherit", shell: process.platform === "win32" });
+    if (result.error || result.status !== 0) {
+      throw new Error(`Project created at ${target}, but npm install failed. Check the npm output above and run npm install there to retry.`);
+    }
+  }
+  console.log(`Created ${target} (Cloudflare Workers, ${frontend === "nuxt" ? "Nuxt frontend" : "API-only"})
+
+Next:
+  cd ${name}
+${install ? "" : "  npm install\n"}  npm run dev`);
+}
+async function chooseFrontend() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log("[Honovel] No interactive terminal detected; including Nuxt. Pass --api-only or --frontend=none for an API-only project.");
+    return "nuxt";
+  }
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log("\nCloudflare Workers backend \u2014 choose your frontend:\n\n  1) Nuxt frontend (recommended)\n  2) API-only (no frontend)\n");
+    const answer = await prompt.question("Select a project setup [1]: ");
+    const selected = answer.trim().toLowerCase();
+    if (!selected || selected === "1" || selected === "nuxt") return "nuxt";
+    if (selected === "2" || selected === "none" || selected === "api-only") return "none";
+    throw new Error("Choose 1 for Nuxt or 2 for API-only.");
+  } finally {
+    prompt.close();
+  }
+}
+main().catch((error) => {
+  console.error(`[Honovel] ${error.message}`);
+  process.exitCode = 1;
+});

package/bin/create-honovel.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["create-honovel.mts"],
+  "sourcesContent": ["#!/usr/bin/env node\nimport fs from 'node:fs'\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { spawnSync } from 'node:child_process'\nimport readline from 'node:readline/promises'\n\nconst packageRoot = fileURLToPath(new URL('../', import.meta.url))\nconst metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'))\n\nasync function main() {\n  const args = process.argv.slice(2)\n  if (!args.length || args.includes('--help') || args.includes('-h')) {\n    console.log('Usage: npm create honovel@latest <project-name> [--frontend=nuxt|none] [--api-only] [--no-install]\\nThe backend is always Cloudflare Workers. If no frontend option is given, the installer asks whether to include Nuxt (the non-interactive default).')\n    return\n  }\n  const [name, ...options] = args\n  if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) throw new Error('Use a project name containing lowercase letters, digits, hyphens, or underscores.')\n  let frontend = 'nuxt'\n  let frontendSelected = false\n  let install = true\n  for (let index = 0; index < options.length; index++) {\n    const option = options[index]\n    if (option === '--no-install') {\n      install = false\n    } else if (option === '--api-only' || option === '--frontend' || option.startsWith('--frontend=')) {\n      if (frontendSelected) throw new Error('Select the frontend only once; do not combine --api-only and --frontend.')\n      frontendSelected = true\n      frontend = option === '--api-only' ? 'none'\n        : option === '--frontend' ? options[++index] : option.slice('--frontend='.length)\n      if (!['nuxt', 'none'].includes(frontend)) throw new Error('Supported frontend options: nuxt, none.')\n    } else if (option === '--template' || option.startsWith('--template=')) {\n      throw new Error('All projects use Cloudflare Workers. Use --frontend=nuxt, --frontend=none or --api-only.')\n    } else throw new Error('Unknown option. Supported: --frontend=nuxt|none, --api-only, --no-install')\n  }\n  if (!frontendSelected) frontend = await chooseFrontend()\n  if (name.length > 63) throw new Error('Cloudflare project names must be at most 63 characters long.')\n  const target = path.resolve(name)\n  if (fs.existsSync(target)) throw new Error(`${name} already exists. Choose a new directory.`)\n  fs.mkdirSync(target)\n  function copy(directory, destination) {\n    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {\n      const source = path.join(directory, entry.name)\n      const outputName = entry.name === 'env.example.template'\n        ? '.env.example'\n        : entry.name.replace(/\\.template$/, '')\n      const output = path.join(destination, outputName)\n      if (entry.isDirectory()) {\n        fs.mkdirSync(output, { recursive: true })\n        copy(source, output)\n      } else {\n        if (/\\.(png|jpe?g|gif|webp|ico|woff2?)$/i.test(entry.name)) {\n          fs.copyFileSync(source, output)\n          continue\n        }\n        const content = fs.readFileSync(source, 'utf8')\n          .replaceAll('__PROJECT_NAME__', name)\n          .replaceAll('__WORKER_NAME__', name.replaceAll('_', '-'))\n          .replaceAll('__HONOVEL_VERSION__', metadata.version)\n        if (fs.existsSync(output) && ['package.json', 'wrangler.jsonc'].includes(outputName)) {\n          const current = JSON.parse(fs.readFileSync(output, 'utf8'))\n          const overlay = JSON.parse(content)\n          const merged = { ...current, ...overlay }\n          if (outputName === 'package.json') {\n            for (const section of ['scripts', 'dependencies', 'devDependencies', 'overrides']) {\n              merged[section] = { ...current[section], ...overlay[section] }\n            }\n          }\n          fs.writeFileSync(output, JSON.stringify(merged, null, 2) + '\\n')\n        } else fs.writeFileSync(output, content)\n      }\n    }\n  }\n  copy(path.join(packageRoot, 'template/common'), target)\n  copy(path.join(packageRoot, 'template/cloudflare'), target)\n  if (frontend === 'nuxt') copy(path.join(packageRoot, 'template/nuxt'), target)\n  const envExamplePath = path.join(target, '.env.example')\n  const envPath = path.join(target, '.env')\n  if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {\n    const localEnv = fs.readFileSync(envExamplePath, 'utf8')\n      .replace(/^APP_DEBUG=.*$/m, 'APP_DEBUG=true')\n    fs.writeFileSync(envPath, localEnv, { flag: 'wx' })\n  }\n  if (install) {\n    // Drizzle Kit 0.31 still declares deprecated loader packages upstream.\n    // Keep the scaffold output focused on actionable install/audit information.\n    const result = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '--loglevel=error'], { cwd: target, stdio: 'inherit', shell: process.platform === 'win32' })\n    if (result.error || result.status !== 0) {\n      throw new Error(`Project created at ${target}, but npm install failed. Check the npm output above and run npm install there to retry.`)\n    }\n  }\n  console.log(`Created ${target} (Cloudflare Workers, ${frontend === 'nuxt' ? 'Nuxt frontend' : 'API-only'})\\n\\nNext:\\n  cd ${name}\\n${install ? '' : '  npm install\\n'}  npm run dev`)\n}\n\nasync function chooseFrontend() {\n  if (!process.stdin.isTTY || !process.stdout.isTTY) {\n    console.log('[Honovel] No interactive terminal detected; including Nuxt. Pass --api-only or --frontend=none for an API-only project.')\n    return 'nuxt'\n  }\n\n  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout })\n  try {\n    console.log('\\nCloudflare Workers backend \u2014 choose your frontend:\\n\\n  1) Nuxt frontend (recommended)\\n  2) API-only (no frontend)\\n')\n    const answer = await prompt.question('Select a project setup [1]: ')\n    const selected = answer.trim().toLowerCase()\n    if (!selected || selected === '1' || selected === 'nuxt') return 'nuxt'\n    if (selected === '2' || selected === 'none' || selected === 'api-only') return 'none'\n    throw new Error('Choose 1 for Nuxt or 2 for API-only.')\n  } finally {\n    prompt.close()\n  }\n}\n\nmain().catch((error) => {\n  console.error(`[Honovel] ${error.message}`)\n  process.exitCode = 1\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/bin/create-honovel.mts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import readline from 'node:readline/promises'
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url))
+const metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'))
+
+async function main() {
+  const args = process.argv.slice(2)
+  if (!args.length || args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: npm create honovel@latest <project-name> [--frontend=nuxt|none] [--api-only] [--no-install]\nThe backend is always Cloudflare Workers. If no frontend option is given, the installer asks whether to include Nuxt (the non-interactive default).')
+    return
+  }
+  const [name, ...options] = args
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(name)) throw new Error('Use a project name containing lowercase letters, digits, hyphens, or underscores.')
+  let frontend = 'nuxt'
+  let frontendSelected = false
+  let install = true
+  for (let index = 0; index < options.length; index++) {
+    const option = options[index]
+    if (option === '--no-install') {
+      install = false
+    } else if (option === '--api-only' || option === '--frontend' || option.startsWith('--frontend=')) {
+      if (frontendSelected) throw new Error('Select the frontend only once; do not combine --api-only and --frontend.')
+      frontendSelected = true
+      frontend = option === '--api-only' ? 'none'
+        : option === '--frontend' ? options[++index] : option.slice('--frontend='.length)
+      if (!['nuxt', 'none'].includes(frontend)) throw new Error('Supported frontend options: nuxt, none.')
+    } else if (option === '--template' || option.startsWith('--template=')) {
+      throw new Error('All projects use Cloudflare Workers. Use --frontend=nuxt, --frontend=none or --api-only.')
+    } else throw new Error('Unknown option. Supported: --frontend=nuxt|none, --api-only, --no-install')
+  }
+  if (!frontendSelected) frontend = await chooseFrontend()
+  if (name.length > 63) throw new Error('Cloudflare project names must be at most 63 characters long.')
+  const target = path.resolve(name)
+  if (fs.existsSync(target)) throw new Error(`${name} already exists. Choose a new directory.`)
+  fs.mkdirSync(target)
+  function copy(directory, destination) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const source = path.join(directory, entry.name)
+      const outputName = entry.name === 'env.example.template'
+        ? '.env.example'
+        : entry.name.replace(/\.template$/, '')
+      const output = path.join(destination, outputName)
+      if (entry.isDirectory()) {
+        fs.mkdirSync(output, { recursive: true })
+        copy(source, output)
+      } else {
+        if (/\.(png|jpe?g|gif|webp|ico|woff2?)$/i.test(entry.name)) {
+          fs.copyFileSync(source, output)
+          continue
+        }
+        const content = fs.readFileSync(source, 'utf8')
+          .replaceAll('__PROJECT_NAME__', name)
+          .replaceAll('__WORKER_NAME__', name.replaceAll('_', '-'))
+          .replaceAll('__HONOVEL_VERSION__', metadata.version)
+        if (fs.existsSync(output) && ['package.json', 'wrangler.jsonc'].includes(outputName)) {
+          const current = JSON.parse(fs.readFileSync(output, 'utf8'))
+          const overlay = JSON.parse(content)
+          const merged = { ...current, ...overlay }
+          if (outputName === 'package.json') {
+            for (const section of ['scripts', 'dependencies', 'devDependencies', 'overrides']) {
+              merged[section] = { ...current[section], ...overlay[section] }
+            }
+          }
+          fs.writeFileSync(output, JSON.stringify(merged, null, 2) + '\n')
+        } else fs.writeFileSync(output, content)
+      }
+    }
+  }
+  copy(path.join(packageRoot, 'template/common'), target)
+  copy(path.join(packageRoot, 'template/cloudflare'), target)
+  if (frontend === 'nuxt') copy(path.join(packageRoot, 'template/nuxt'), target)
+  const envExamplePath = path.join(target, '.env.example')
+  const envPath = path.join(target, '.env')
+  if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+    const localEnv = fs.readFileSync(envExamplePath, 'utf8')
+      .replace(/^APP_DEBUG=.*$/m, 'APP_DEBUG=true')
+    fs.writeFileSync(envPath, localEnv, { flag: 'wx' })
+  }
+  if (install) {
+    // Drizzle Kit 0.31 still declares deprecated loader packages upstream.
+    // Keep the scaffold output focused on actionable install/audit information.
+    const result = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '--loglevel=error'], { cwd: target, stdio: 'inherit', shell: process.platform === 'win32' })
+    if (result.error || result.status !== 0) {
+      throw new Error(`Project created at ${target}, but npm install failed. Check the npm output above and run npm install there to retry.`)
+    }
+  }
+  console.log(`Created ${target} (Cloudflare Workers, ${frontend === 'nuxt' ? 'Nuxt frontend' : 'API-only'})\n\nNext:\n  cd ${name}\n${install ? '' : '  npm install\n'}  npm run dev`)
+}
+
+async function chooseFrontend() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log('[Honovel] No interactive terminal detected; including Nuxt. Pass --api-only or --frontend=none for an API-only project.')
+    return 'nuxt'
+  }
+
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    console.log('\nCloudflare Workers backend — choose your frontend:\n\n  1) Nuxt frontend (recommended)\n  2) API-only (no frontend)\n')
+    const answer = await prompt.question('Select a project setup [1]: ')
+    const selected = answer.trim().toLowerCase()
+    if (!selected || selected === '1' || selected === 'nuxt') return 'nuxt'
+    if (selected === '2' || selected === 'none' || selected === 'api-only') return 'none'
+    throw new Error('Choose 1 for Nuxt or 2 for API-only.')
+  } finally {
+    prompt.close()
+  }
+}
+
+main().catch((error) => {
+  console.error(`[Honovel] ${error.message}`)
+  process.exitCode = 1
+})

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "create-honovel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Create a Cloudflare Workers application with an optional Nuxt frontend",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "create-honovel": "./bin/create-honovel.mjs"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Honovel/framework.git",
+    "directory": "packages/create-honovel"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "esbuild bin/create-honovel.mts --platform=node --format=esm --outfile=bin/create-honovel.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  }
+}

package/template/cloudflare/.vscode/launch.json.template

@@ -0,0 +1,18 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Honovel Cloudflare (attach)",
+      "type": "node",
+      "request": "attach",
+      "port": 9229,
+      "address": "127.0.0.1",
+      "cwd": "/",
+      "resolveSourceMapLocations": null,
+      "attachExistingChildren": false,
+      "autoAttachChildProcesses": false,
+      "restart": true,
+      "sourceMaps": true
+    }
+  ]
+}

package/template/cloudflare/README.md

@@ -0,0 +1,46 @@
+# __PROJECT_NAME__
+
+This Honovel project runs on Cloudflare Workers and is API-only. No frontend directory, frontend dependencies or static assets binding are generated.
+
+```sh
+npm run dev
+```
+
+The API is available at `http://localhost:8788/api/health`. Development Swagger and OpenAPI are served at `/swagger` and `/openapi.json`. Use `npm run dev:debug` to attach an IDE to the Worker inspector on `127.0.0.1:9229`; normal development uses an ephemeral inspector port.
+
+## Application structure
+
+`index.ts` creates the Hono app and exports the Durable Object cache class. `src/runtime/Controller.ts` supplies the `/api` prefix. Add feature controllers, DTOs, actions, repositories and services under `src/features/`.
+
+```sh
+npm run honovel -- make:feature users
+npm run honovel -- list
+npm run typecheck
+npm run build
+```
+
+`build` generates binding types, compiles for production and performs a local Wrangler deployment dry run. It writes the Worker bundle to `dist/worker`; it does not upload anything. Production documentation routes are disabled by default.
+
+Build/dev helpers are provided by `honovel` through the `honovel` CLI. This project has no copied `scripts/` directory. `npm run dev` launches Wrangler directly without a frontend server.
+
+## Runtime services and database
+
+The project selects D1 for SQL, Durable Objects for cache and cache-backed locks, Cloudflare Queues for queued listeners and Cron Triggers for schedules. Application runtime wrappers under `src/runtime/` select those providers through DI.
+
+The configured `main` database has an empty schema and no initial SQL migration. Add tables and export them from `src/database/main/schema/index.ts`, then run:
+
+```sh
+npm run db:generate
+npm run db:migrate                  # local D1
+```
+
+See `src/database/README.md` for an optional table example. Before deployment, create the database named in `wrangler.jsonc`, replace its placeholder `database_id`, run `npm run compile` and apply any migrations with `npm run db:migrate:remote`. `npm run deploy` rejects placeholder IDs before builds or uploads.
+
+```sh
+npm run cf-typegen                  # after changing bindings
+npm run deploy
+```
+
+Edit `wrangler.jsonc`; `.honovel.wrangler.jsonc` and `.honovel/` are generated files. Keep secrets in local environment files or Wrangler secrets. The generated local `.env` enables `APP_DEBUG=true`; disable debug details in production.
+
+Framework documentation: https://honovel.github.io/framework

package/template/cloudflare/index.ts.template

@@ -0,0 +1,7 @@
+import { createHonoApp } from 'honovel'
+import type { AppEnv } from './src/env'
+
+export { HonovelCacheDurableObject } from 'honovel/cloudflare'
+
+const app = createHonoApp<AppEnv>()
+export default app

package/template/cloudflare/package.json.template

@@ -0,0 +1,47 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#src/*": "./src/*.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "overrides": {
+    "@esbuild-kit/core-utils": {
+      "esbuild": "^0.25.12"
+    }
+  },
+  "scripts": {
+    "honovel": "honovel",
+    "compile": "honovel cloudflare:compile",
+    "compile:wrangler": "honovel cloudflare:build",
+    "typecheck:backend": "npm run cf-typegen && honovel typecheck",
+    "typecheck": "npm run typecheck:backend",
+    "db:generate": "honovel db:generate --db=main",
+    "db:migrate": "wrangler d1 migrations apply __WORKER_NAME__-main --local",
+    "db:migrate:remote": "wrangler d1 migrations apply __WORKER_NAME__-main --remote",
+    "build": "npm run cf-typegen && honovel cloudflare:deploy --dry-run --outdir dist/worker",
+    "dev:backend": "honovel cloudflare:dev-backend",
+    "dev:backend:debug": "honovel cloudflare:dev-backend --debug",
+    "dev": "honovel cloudflare:dev-backend",
+    "dev:debug": "honovel cloudflare:dev-backend --debug",
+    "predeploy": "honovel cloudflare:predeploy",
+    "deploy": "npm run cf-typegen && honovel cloudflare:deploy --minify",
+    "cf-typegen": "honovel cloudflare:typegen"
+  },
+  "dependencies": {
+    "honovel": "__HONOVEL_VERSION__",
+    "hono": "^4.13.17",
+    "drizzle-orm": "^0.45.3",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "drizzle-kit": "^0.31.11",
+    "typescript": "^6.0.3",
+    "wrangler": "4.158.0"
+  }
+}

package/template/cloudflare/src/database/main/MainDatabase.ts.template

@@ -0,0 +1,10 @@
+import type { Context } from 'hono'
+import { drizzle } from 'drizzle-orm/d1'
+import { defineDatabase } from 'honovel'
+import type { AppEnv } from '../../env'
+import * as schema from './schema'
+
+/** The default D1 database. Replace the placeholder ID in wrangler.jsonc before deploy. */
+export class MainDatabase extends defineDatabase(
+  (context: Context<AppEnv>) => drizzle(context.env.DB, { schema }),
+) {}

package/template/cloudflare/src/database/main/drizzle.config.ts.template

@@ -0,0 +1,7 @@
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './src/database/main/schema/*.ts',
+  out: './src/database/main/migrations',
+})

package/template/cloudflare/src/database/main/migrations/meta/_journal.json

@@ -0,0 +1,6 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+  ]
+}

package/template/cloudflare/src/database/main/schema/index.ts.template

@@ -0,0 +1,2 @@
+// Export your application tables here. See ../../README.md for an example.
+export {}

package/template/cloudflare/src/env.ts.template

@@ -0,0 +1,5 @@
+export type AppEnv = {
+  Bindings: CloudflareBindings & {
+    APP_DEBUG?: string
+  }
+}

package/template/cloudflare/src/runtime/CloudflareQueue.ts.template

@@ -0,0 +1,11 @@
+import { Context } from 'hono'
+import { Queue, Scope } from 'honovel'
+import { BaseCloudflareQueue } from 'honovel/cloudflare'
+import type { AppEnv } from '../env'
+
+@Scope({ provides: Queue })
+export class CloudflareQueue extends BaseCloudflareQueue {
+  constructor(context: Context<AppEnv>) {
+    super(context.env.HONOVEL_QUEUE)
+  }
+}

package/template/cloudflare/src/runtime/DurableObjectCache.ts.template

@@ -0,0 +1,11 @@
+import { Context } from 'hono'
+import { Cache, Scope } from 'honovel'
+import { BaseDurableObjectCache } from 'honovel/cloudflare'
+import type { AppEnv } from '../env'
+
+@Scope({ provides: Cache })
+export class DurableObjectCache extends BaseDurableObjectCache {
+  constructor(context: Context<AppEnv>) {
+    super(context.env.HONOVEL_CACHE)
+  }
+}

package/template/cloudflare/wrangler.jsonc

@@ -0,0 +1,56 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "__WORKER_NAME__",
+  "main": ".honovel/index.js",
+  "compatibility_date": "2026-09-21",
+  "compatibility_flags": [
+    "no_nodejs_compat",
+    "no_nodejs_compat_v2"
+  ],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "HONOVEL_CACHE",
+        "class_name": "HonovelCacheDurableObject"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": [
+        "HonovelCacheDurableObject"
+      ]
+    }
+  ],
+  "queues": {
+    "producers": [
+      {
+        "binding": "HONOVEL_QUEUE",
+        "queue": "__WORKER_NAME__"
+      }
+    ],
+    "consumers": [
+      {
+        "queue": "__WORKER_NAME__"
+      }
+    ]
+  },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "__WORKER_NAME__-main",
+      "database_id": "00000000-0000-0000-0000-000000000000",
+      "migrations_dir": "src/database/main/migrations"
+    }
+  ],
+  "build": {
+    "command": "honovel cloudflare:build",
+    "watch_dir": [
+      "src",
+      "index.ts",
+      "tsconfig.json",
+      "tsconfig.build.json"
+    ]
+  }
+}

package/template/common/.gitignore.template

@@ -0,0 +1,16 @@
+node_modules/
+.honovel/
+.honovel.wrangler.jsonc
+dist/
+.nuxt/
+.output/
+.wrangler/
+.dev.vars
+.dev.vars.*
+worker-configuration.d.ts
+.env
+.env.*
+!.env.example
+*.db
+*.db-*
+*.log

package/template/common/.vscode/settings.json.template

@@ -0,0 +1,4 @@
+{
+  "js/ts.tsdk.path": "./node_modules/typescript/lib",
+  "js/ts.experimental.useTsgo": false
+}

package/template/common/agents.md

@@ -0,0 +1,33 @@
+# Honovel project guide for coding agents
+
+This project is a Honovel application generated by `create-honovel`. Read this file before changing framework-specific code.
+
+## Project structure
+
+- `index.ts` is the runtime entrypoint. It creates the Hono application and exports it for Cloudflare Workers.
+- `src/features/<feature>/` contains feature code. Keep controllers, DTOs, actions, repositories and services close to the feature that owns them.
+- `src/runtime/Controller.ts` is the application-owned controller base. It adds the `/api` prefix to feature controller routes.
+- `src/database/<name>/` contains a database provider, Drizzle schemas and migrations. Keep schemas and migration history grouped by physical database.
+- `frontend/` contains the optional Nuxt 4 frontend. It exists only when Nuxt was selected during project creation and uses the same origin as the API in production. API-only projects have no frontend directory, dependencies or assets configuration.
+- Runtime and build helpers are provided by the `honovel` CLI from `honovel`; there is no generated `scripts/` directory. `.honovel/` and `dist/` contain generated output; application code belongs in `src/`, `frontend/` and `index.ts`.
+
+The project `README.md` describes the selected Nuxt or API-only setup. The backend is always Cloudflare Workers. Check `package.json` and `wrangler.jsonc` before changing deployment or platform code.
+
+## Working conventions
+
+- Import Honovel APIs from `honovel` and `honovel/cloudflare`. Do not import application code from `.honovel/`.
+- Use the Honovel CLI for new structure: `npm run honovel -- make:feature <name>` and the other `make:*` commands listed in `README.md`.
+- Controllers handle HTTP input and delegate application work to actions or services. Repositories own database queries.
+- The database schema starts empty. Add/export tables, then generate and apply migrations before using them. Run `npm run typecheck` after framework or TypeScript changes.
+- Keep request-specific state scoped to the request. In Cloudflare Workers, do not store request or binding objects in module-level mutable state.
+
+## Honovel documentation
+
+The hosted documentation is the source of truth for framework APIs and runtime behavior:
+
+- Index for agents: https://honovel.github.io/framework/llms.txt
+- Complete agent documentation: https://honovel.github.io/framework/llms-full.txt
+- Human-readable documentation: https://honovel.github.io/framework
+- Individual Markdown topics: https://honovel.github.io/framework/raw/<topic>.md
+
+When working on Honovel-specific code, consult `/llms.txt` first and load the relevant topic from `/raw/` before implementing framework APIs. Use `/llms-full.txt` when the task spans several parts of the framework or when the topic is unclear. This prevents assuming undocumented APIs from other frameworks or plain Hono.

package/template/common/env.example.template

@@ -0,0 +1,3 @@
+# Expose exception messages and stack traces in HTTP 500 responses.
+# Keep disabled in production.
+APP_DEBUG=false

package/template/common/src/database/README.md

@@ -0,0 +1,27 @@
+# Databases
+
+Keep each database under its own directory here, e.g. `main/MainDatabase.ts`, `main/schema/*.ts`, `main/drizzle.config.ts`, and `main/migrations/`.
+
+Nuxt and API-only projects both include a configured `main` D1 database with an empty schema and no initial SQL migration. No Todo table or CRUD feature is created.
+
+For example, create `main/schema/todos.ts` with:
+
+```ts
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+export const todos = sqliteTable('todos', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  title: text('title').notNull(),
+  completed: integer('completed', { mode: 'boolean' }).notNull().default(false),
+})
+```
+
+Export it from `main/schema/index.ts` with `export * from './todos'`. Then run `npm run db:generate` and `npm run db:migrate`. Only add the table if your application needs it. Create `<project>-main` and replace the placeholder `database_id` in `wrangler.jsonc` before remote migrations or deployment.
+
+Import `MainDatabase` and the tables only in feature repositories. Additional connections can be added as sibling directories under `src/database/`, each with its own provider, schema, Drizzle config, and migrations.
+
+Database providers extend `defineDatabase(...)`, are lazy and request-scoped, and should be injected into repositories rather than controllers. Keep long-lived driver clients/pools outside the provider factory where the runtime supports it; do not cache a request-specific Hono context or binding globally.
+
+The starter uses the stable Drizzle Kit 0.31 line and overrides its nested esbuild version to a secure release. The upstream Kit package still declares deprecated `@esbuild-kit` loader packages; the initializer suppresses those non-actionable npm deprecation notices during its automatic install. Revisit this workaround when Drizzle Kit 1.0 is stable.
+
+Generate migrations with `npm run db:generate`, then apply them through Wrangler using `npm run db:migrate` (local D1) or `npm run db:migrate:remote` (remote D1).

package/template/common/src/decorators.ts.template

@@ -0,0 +1,65 @@
+import {
+  Cache,
+  createDecorator,
+  TooManyRequestsException,
+} from 'honovel'
+
+/**
+ * Default API rate limit: 200 requests per minute per client IP.
+ *
+ * This can be adapted to user-, account-, token-, or route-based limits if needed.
+ */
+export const IpRateLimit = createDecorator(
+  [Cache],
+  async (context, cache, attempts: number) => {
+    const forwardedFor = context.req.header('X-Forwarded-For')
+    const ip = context.req.header('CF-Connecting-IP')
+      ?? forwardedFor?.split(',')[0]?.trim()
+      ?? 'unknown'
+
+    const currentAttempts = await cache.increment(
+      'rate-limit',
+      `api:${ip}`,
+      1,
+      60_000,
+    )
+
+    if (currentAttempts > attempts) {
+      throw new TooManyRequestsException()
+    }
+  },
+  { cache: false },
+)
+
+/**
+ * Additional custom decorator examples. Uncomment and adapt these to your application.
+ * They can be used on controller parameters, methods, or controllers.
+ */
+
+/*
+import { JwtPayload } from 'honovel'
+import { UserService } from './services/UserService'
+
+export const Header = createDecorator((context, name: string) =>
+  context.req.header(name)
+)
+
+// You can inject any service or even other decorators to your custom decorators.
+// UserService is request-scoped by default. Replace findById() with the
+// application-specific lookup used by your user model.
+export const CurrentUser = createDecorator(
+  [UserService, JwtPayload], // Inject any service or even other decorators here
+  async (_context, users, jwt) => users.findById(Number(jwt.sub)),
+)
+
+// Example usage:
+//
+// @ApiRateLimit()
+// @Get('/')
+// show(
+//   @Header('x-request-id') requestId: string | undefined,
+//   @CurrentUser() user: User,
+// ) {
+//   return { requestId, user }
+// }
+*/

package/template/common/src/features/health/controllers/HealthController.ts.template

@@ -0,0 +1,10 @@
+import { BaseUrl, Get } from 'honovel'
+import { Controller } from '#src/runtime/Controller'
+
+@BaseUrl('/health')
+export class HealthController extends Controller {
+  @Get('/')
+  show() {
+    return { status: 'ok' }
+  }
+}

package/template/common/src/runtime/CacheLock.ts.template

@@ -0,0 +1,4 @@
+import { CacheLock, Lock, Scope } from 'honovel'
+
+@Scope({ provides: Lock })
+export class AppLock extends CacheLock {}

package/template/common/src/runtime/Controller.ts.template

@@ -0,0 +1,4 @@
+import { BaseController, BaseUrl } from 'honovel'
+
+@BaseUrl('/api')
+export abstract class Controller extends BaseController {}

package/template/common/tsconfig.build.json.template

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": ".", "outDir": ".honovel", "declaration": false },
+  "include": ["index.ts", "src/**/*.ts", "worker-configuration.d.ts"]
+}

package/template/common/tsconfig.json.template

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "experimentalDecorators": true,
+    "lib": ["ESNext", "DOM"],
+    "plugins": [{ "name": "honovel/typescript-plugin" }]
+  }
+}

package/template/nuxt/README.md

@@ -0,0 +1,103 @@
+# __PROJECT_NAME__
+
+```sh
+npm run dev
+```
+
+The starter runs a Nuxt 4 frontend and the Honovel Worker together. Open `http://localhost:5173`; Nuxt proxies `/api`, `/swagger`, and `/openapi.json` to the local Wrangler backend. Honovel prefers backend port 8788 and automatically picks a free port when 8788 is already in use, while the public frontend URL stays fixed on 5173. The sample frontend calls `GET /api/health`. In production, `nuxt generate` prerenders the frontend and Honovel deploys the generated files with the Worker as Cloudflare Static Assets, so frontend assets and API routes share one origin and one deployment.
+
+The combined dev command uses scrolling logs with `[Nuxt]` prefixes for frontend output. Nuxt's fullscreen terminal UI is disabled so it cannot overwrite the Worker logs or the app link. Press Ctrl+C to stop both servers.
+
+The frontend includes Tailwind CSS through its Vite plugin and a locally bundled Manrope font. Customize colors and typography in `frontend/app/assets/css/main.css` (`@theme`), and use utility classes directly in Vue components. Pages live in `frontend/app/pages/`.
+
+The default production rendering mode is SSG. Nuxt prerenders discoverable pages during the build and hydrates them in the browser. Pure CSR is also possible with `ssr: false` in `frontend/nuxt.config.ts`. Request-time SSR and ISR are not supported by the current Honovel starter because no Nuxt/Nitro server runtime is deployed.
+
+Wrangler serves the Worker locally with automatic rebuilding when application source changes. `/swagger` and `/openapi.json` are enabled in development. Normal `npm run dev` chooses a free backend port when needed and lets Wrangler use an ephemeral inspector port, so multiple Honovel or Wrangler projects can run locally without hard-coded port collisions.
+
+Wrangler executes the Worker in Cloudflare's local `workerd` runtime rather than in the Node process that launched Wrangler. Use `npm run dev` for normal development. When you want to attach an IDE debugger, run `npm run dev:debug`; that pins the Worker inspector to `127.0.0.1:9229` for the included `Honovel Cloudflare (attach)` configuration. Do not launch Wrangler itself through a Node debug terminal, because that debugs Wrangler and Honovel's custom-build Node subprocesses instead of the Worker runtime.
+
+`index.ts` creates and exports the Hono app. Honovel compiles routes to `.honovel/index.js`, the `main` entry in `wrangler.jsonc`. Cloudflare invokes the app's `fetch` handler directly; this template has no Node server adapter or HTTP listener.
+
+```sh
+npm run typecheck
+npm run build
+npm run deploy
+```
+
+`build` runs a local Wrangler deployment dry run and writes the production Worker bundle to `dist/`; it does not upload anything. `deploy` publishes the Worker after Cloudflare authentication. Both invoke Honovel's custom build through Wrangler, which selects production mode for deployment and disables documentation by default.
+
+The application-level `src/runtime/Controller.ts` extends Honovel's `BaseController` and declares `@BaseUrl('/api')`. Feature controllers add their own segment, so `@BaseUrl('/users')` becomes `/api/users`. Change that one runtime controller if your application uses a different API prefix.
+
+The frontend is generated into `frontend/.output/public` and copied to `dist/frontend`. `wrangler.jsonc` configures SPA fallback routing and sends only `/api/*`, `/swagger`, and `/openapi.json` through the Worker first; normal static asset requests are served directly by Cloudflare's static asset layer.
+
+`compile` and `typecheck` generate `CloudflareBindings` with `wrangler types`. Add bindings such as D1, KV, or R2 to `wrangler.jsonc`; `src/env.ts` exposes them as `AppEnv`. Keep local secrets in ignored `.dev.vars`, and use `wrangler secret put` for deployed secrets. Node.js is required for tooling only; the Worker runtime does not need `nodejs_compat` for this starter.
+
+The custom build uses `honovel cloudflare:build` from `honovel`. It skips compilation when called by `wrangler types`, because Wrangler also invokes custom builds while inspecting the entrypoint for type generation; this prevents recursive builds.
+
+Wrangler is pinned to the version tested with this starter. Upgrade that dependency and the compatibility date deliberately when adopting newer Workers features.
+
+Generate a feature with `npm run honovel -- make:feature users`. Database schemas, migrations, and provider classes belong under `src/database/<name>/`. Generate CRUD code for an existing table with `make:resource users/User --table=users --database=main`. For additional databases, choose the appropriate Drizzle driver and binding in a database factory.
+
+The starter includes `src/database/main/` with a D1 provider and an empty schema. See `src/database/README.md` for an optional table example; generate your first migration after adding tables. Create a D1 database named exactly like the generated `database_name` (for example `my-app-main`) and replace the placeholder `database_id` in `wrangler.jsonc` with its ID. Run `npm run compile` after changing the ID to refresh the generated Wrangler configuration before applying remote migrations. After generating a migration, run `npm run db:migrate` for the local D1 database; use `npm run db:migrate:remote` for the deployed database. Generate new migrations with `npm run db:generate`.
+
+`npm run deploy` checks for D1 placeholder IDs before type generation, builds, or uploads and prints the setup commands if a database has not been configured. `npm run build` remains usable with placeholder IDs because it only performs a local dry run. This check does not verify that configured databases exist in your Cloudflare account; Wrangler validates them during deployment.
+
+## Honovel commands
+
+```sh
+npm run honovel -- list
+npm run honovel -- compile             # development compile
+npm run honovel -- build               # production compile
+npm run honovel -- typecheck
+npm run honovel -- make:feature users
+npm run honovel -- make:resource users/User --table=users --database=main
+npm run honovel -- make:controller users/User
+npm run honovel -- make:repository users/UserRepository
+npm run honovel -- make:service users/UserService
+npm run honovel -- make:action users/CreateUser
+npm run honovel -- make:request users/CreateUserRequest
+npm run honovel -- make:response users/UserResponse
+npm run honovel -- make:middleware Auth
+npm run honovel -- make:migration add-index
+npm run db:generate
+npm run db:migrate                 # local D1
+npm run db:migrate:remote          # deployed D1
+```
+
+`make:feature` creates only the feature structure. `make:resource` generates CRUD code for an existing exported table; it does not create database files. Keep connections and schemas central under `src/database/`, then expose them to features through repositories.
+
+## DI and decorators
+
+Honovel resolves concrete, named-exported classes by constructor. Services are request-scoped by default, which is important in Workers because global mutable state can leak between requests. Inject the concrete `MainDatabase` provider into repositories; it creates a typed Drizzle D1 client lazily from the current Hono context.
+
+The following example assumes you have added and exported the optional `todos` table described in `src/database/README.md`.
+
+```ts
+import { BaseUrl, Controller, Get } from 'honovel'
+import { MainDatabase } from '../../../database/main/MainDatabase'
+import { todos } from '../../../database/main/schema'
+
+@BaseUrl('/todos')
+export class TodoController extends Controller {
+  constructor(private readonly database: MainDatabase) { super() }
+
+  @Get('/')
+  list() {
+    return this.database.client.select().from(todos)
+  }
+}
+```
+
+Use `@Get`, `@Post`, `@Put`, `@Patch`, and `@Delete` for routes, `@BaseUrl` for a controller prefix, and `@Query`/`@Param` for typed route parameters. `@Middleware` attaches middleware. Use `@Scope('transient')` only for stateless, independently-created helpers; database providers must remain request-scoped. Custom decorators can be built with `createDecorator` and explicit DI dependencies. Validation uses `FormRequest(schema)` or standard schemas and keeps request parsing at the route boundary.
+
+The published Core includes the Honovel TypeScript language-service plugin. The generated `tsconfig.json` points editors at `honovel/typescript-plugin`; restart the TypeScript server after installing dependencies to get diagnostics for missing routes, DI dependencies, and decorator usage. The plugin is editor tooling only—the compiler remains the authoritative build/typecheck step.
+
+Keep `index.ts` as the Worker entrypoint and keep runtime bindings in `AppEnv`. Do not access `globalThis` for request state or cache a request-specific D1/Context object. Use Wrangler secrets for credentials, keep `.dev.vars` local, and commit migrations alongside the database they change.
+
+Copy `.env.example` to `.env` for local Wrangler configuration. `APP_DEBUG=false` is the safe default; set it to `true` locally to include the exception name and stack trace in otherwise hidden HTTP 500 responses. Never enable it in production.
+
+The framework and Cloudflare adapters are installed together as `honovel`; no framework source is copied into this project. Import framework APIs from `honovel` and Cloudflare adapters from `honovel/cloudflare`. Installation uses the public npm registry and requires no login.
+
+Build and runtime helpers are shipped in `honovel` and invoked through the `honovel` CLI. The starter does not copy a `scripts/` directory. `honovel frontend:build` generates the Nuxt frontend; Cloudflare tooling is available as `honovel cloudflare:<command>`.
+
+This project was created with `--frontend=nuxt`. For a new API-only project, use `npm create honovel@latest my-api -- --api-only`; its backend remains Cloudflare Workers.

package/template/nuxt/frontend/app/app.vue.template

@@ -0,0 +1,20 @@
+<template>
+  <a href="#main" class="sr-only fixed left-6 top-4 z-50 rounded bg-ink p-3 text-paper focus:not-sr-only">Skip to content</a>
+  <div class="flex min-h-screen flex-col">
+    <header class="page-width flex min-h-24 flex-wrap items-center justify-between gap-4 py-5">
+      <NuxtLink to="/" aria-label="Honovel home" class="flex items-center gap-3 text-xl font-extrabold tracking-tight">
+        <img src="/honovel-icon.png" alt="" width="32" height="32" class="size-8" aria-hidden="true">
+        honovel<span class="text-accent">.</span>
+      </NuxtLink>
+      <nav aria-label="Main navigation" class="flex items-center gap-1 rounded-full border border-line p-1 text-sm">
+        <NuxtLink to="/" class="nav-link">Overview</NuxtLink>
+        <NuxtLink to="/about" class="nav-link">The stack</NuxtLink>
+      </nav>
+    </header>
+    <NuxtPage />
+    <footer class="page-width mt-auto flex flex-wrap items-center justify-between gap-4 border-t border-line py-7 text-xs text-muted">
+      <span>__PROJECT_NAME__ <span class="mx-2 text-line">/</span> Built with Honovel</span>
+      <span>Nuxt 4 <span class="mx-2">·</span> Vue 3 <span class="mx-2">·</span> TypeScript <span class="mx-2">·</span> Tailwind CSS</span>
+    </footer>
+  </div>
+</template>

package/template/nuxt/frontend/app/assets/css/main.css.template

@@ -0,0 +1,38 @@
+@import '@fontsource-variable/manrope';
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: 'Manrope Variable', sans-serif;
+  --color-paper: #f5f3ed;
+  --color-ink: #242520;
+  --color-muted: #686a60;
+  --color-line: #dedfd5;
+  --color-accent: #bd3b23;
+}
+
+@layer base {
+  body { @apply m-0 min-w-80 bg-paper font-sans text-ink antialiased; }
+  ::selection { background: #f7c4aa; color: #242520; }
+  button, a { -webkit-tap-highlight-color: transparent; }
+  button:not(:disabled), a { cursor: pointer; }
+  :focus-visible { outline: 2px solid #bd3b23; outline-offset: 5px; }
+}
+
+@layer components {
+  .nav-link { @apply rounded-full px-5 py-2 transition-colors; }
+  .nav-link:hover { @apply bg-white; }
+  .nav-link.router-link-exact-active { @apply bg-ink text-paper; }
+  .page-width { @apply mx-auto w-full max-w-7xl px-6 sm:px-10 lg:px-16; }
+  .eyebrow { @apply font-mono text-xs uppercase tracking-[0.16em] text-muted; }
+  .action { @apply inline-flex min-h-12 items-center justify-center gap-5 rounded-full bg-ink px-6 text-sm font-semibold text-paper transition-colors hover:bg-accent disabled:cursor-wait disabled:opacity-60; }
+  .text-link { @apply inline-flex min-h-11 items-center gap-3 text-sm font-semibold transition-colors hover:text-accent; }
+}
+
+.enter { animation: enter 650ms cubic-bezier(0.2, 0.8, 0.2, 1) both; }
+.enter-late { animation-delay: 110ms; }
+.hero-mark { animation: mark-enter 950ms cubic-bezier(0.2, 0.8, 0.2, 1) both; }
+@keyframes enter { from { opacity: 0; transform: translateY(18px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes mark-enter { from { opacity: 0; transform: rotate(-8deg) scale(0.95); } to { opacity: 1; transform: rotate(0) scale(1); } }
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation: none !important; transition: none !important; scroll-behavior: auto !important; }
+}

package/template/nuxt/frontend/app/pages/about.vue.template

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+useSeoMeta({
+  title: 'The stack · __PROJECT_NAME__',
+  description: 'Nuxt and Honovel, connected by design.',
+})
+</script>
+
+<template>
+  <main id="main" class="page-width flex-1 pb-16 pt-10 lg:pb-24 lg:pt-16">
+    <section class="enter">
+      <p class="eyebrow mb-7">The stack / Connected by design</p>
+      <h1 class="max-w-4xl text-[clamp(3rem,6.5vw,5.5rem)] font-medium leading-[1.05] tracking-[-0.06em]">Two sides.<br />One <span class="text-accent">application.</span></h1>
+      <p class="mt-7 max-w-xl text-lg leading-8 text-muted">Nuxt handles the web experience. Honovel handles the API. TypeScript connects the pieces, and Tailwind makes them your own.</p>
+    </section>
+    <section class="enter enter-late my-12 overflow-hidden rounded-2xl bg-ink p-6 text-paper sm:p-10 lg:my-16" aria-label="Request flow">
+      <p class="mb-8 font-mono text-xs uppercase tracking-widest text-[#bfc0b5]">One origin, from browser to backend</p>
+      <div class="grid items-center gap-5 md:grid-cols-[1fr_auto_1fr_auto_1fr]">
+        <div><span class="font-mono text-xs text-[#bfc0b5]">01</span><h2 class="mt-2 text-2xl font-medium">Nuxt</h2><p class="mt-2 text-sm text-[#bfc0b5]">Pages, SEO, rendering</p></div>
+        <span class="text-3xl text-[#ed9b7b]" aria-hidden="true">→</span>
+        <div><span class="font-mono text-xs text-[#bfc0b5]">02</span><h2 class="mt-2 text-2xl font-medium">fetch('/api/…')</h2><p class="mt-2 text-sm text-[#bfc0b5]">Same-origin requests</p></div>
+        <span class="text-3xl text-[#ed9b7b]" aria-hidden="true">→</span>
+        <div><span class="font-mono text-xs text-[#bfc0b5]">03</span><h2 class="mt-2 text-2xl font-medium">Honovel + Hono</h2><p class="mt-2 text-sm text-[#bfc0b5]">Controllers, services, data</p></div>
+      </div>
+    </section>
+    <section class="grid gap-10 lg:grid-cols-[1fr_1.6fr] lg:gap-20">
+      <div><p class="eyebrow mb-4">A place for everything</p><h2 class="text-3xl font-medium tracking-tight">Simple foundations.<br />Room to grow.</h2></div>
+      <dl>
+        <div class="grid gap-2 border-t border-line py-6 sm:grid-cols-[140px_1fr] sm:gap-6"><dt class="font-semibold">Frontend</dt><dd class="text-sm leading-7 text-muted">Pages live in <code class="text-ink">frontend/app/pages</code>. Nuxt provides routing, SEO metadata, SSR and prerendering capabilities.</dd></div>
+        <div class="grid gap-2 border-t border-line py-6 sm:grid-cols-[140px_1fr] sm:gap-6"><dt class="font-semibold">API</dt><dd class="text-sm leading-7 text-muted">Backend features live in <code class="text-ink">src/features</code>. Requests under <code class="text-ink">/api</code> reach your Honovel controllers.</dd></div>
+        <div class="grid gap-2 border-t border-line py-6 sm:grid-cols-[140px_1fr] sm:gap-6"><dt class="font-semibold">Development</dt><dd class="text-sm leading-7 text-muted"><code class="text-ink">npm run dev</code> starts Nuxt and the backend together. Nuxt proxies API and docs requests while you work.</dd></div>
+        <div class="grid gap-2 border-y border-line py-6 sm:grid-cols-[140px_1fr] sm:gap-6"><dt class="font-semibold">Production</dt><dd class="text-sm leading-7 text-muted"><code class="text-ink">npm run build</code> prerenders the frontend and builds the backend. Your chosen runtime serves both from one origin.</dd></div>
+      </dl>
+    </section>
+    <div class="mt-12 flex flex-wrap items-center justify-between gap-6 border-t border-line pt-8">
+      <p class="text-xl font-medium tracking-tight">The rest is your story.</p>
+      <NuxtLink to="/" class="action">Back to your canvas <span aria-hidden="true">↗</span></NuxtLink>
+    </div>
+  </main>
+</template>

package/template/nuxt/frontend/app/pages/index.vue.template

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+
+useSeoMeta({
+  title: '__PROJECT_NAME__ · Honovel',
+  description: 'A Honovel application powered by Nuxt.',
+})
+
+const state = ref<'checking' | 'online' | 'offline'>('checking')
+const status = computed(() => ({ checking: 'Checking connection', online: 'API connected', offline: 'API unavailable' })[state.value])
+
+async function checkHealth() {
+  state.value = 'checking'
+  try {
+    const response = await fetch('/api/health', { signal: AbortSignal.timeout(5000) })
+    if (!response.ok) throw new Error('Health request failed')
+    const body = await response.json() as { status?: string }
+    state.value = body.status === 'ok' ? 'online' : 'offline'
+  } catch {
+    state.value = 'offline'
+  }
+}
+
+onMounted(checkHealth)
+</script>
+
+<template>
+  <main id="main" class="flex-1">
+    <section class="page-width grid items-center gap-10 pb-14 pt-10 lg:grid-cols-[1.3fr_1fr] lg:gap-16 lg:pb-20 lg:pt-16">
+      <div class="enter">
+        <p class="eyebrow mb-7">__PROJECT_NAME__ / Your next chapter</p>
+        <h1 class="text-[clamp(2.6rem,7.5vw,6.5rem)] font-medium leading-[1.02] tracking-[-0.065em]">Hello, builder.<br />Make it <span class="text-accent">yours.</span></h1>
+        <p class="mt-7 max-w-md text-base leading-7 text-muted sm:text-lg">A fresh canvas for your next idea. Your Nuxt frontend and Honovel API are ready to work together.</p>
+        <div class="mt-9 flex flex-wrap items-center gap-x-7 gap-y-2">
+          <NuxtLink to="/about" class="action">Explore the stack <span aria-hidden="true">↗</span></NuxtLink>
+          <a href="#start" class="text-link">Start building <span aria-hidden="true">↓</span></a>
+        </div>
+      </div>
+      <div class="hero-mark relative mx-auto flex aspect-square w-full max-w-[380px] items-center justify-center overflow-hidden rounded-full bg-[#e9e8de]" aria-hidden="true">
+        <svg viewBox="0 0 400 400" class="size-full">
+          <circle cx="200" cy="200" r="160" fill="none" stroke="#cecec0" />
+          <circle cx="200" cy="200" r="116" fill="none" stroke="#cecec0" />
+          <path d="M0 200h400M200 0v400" stroke="#cecec0" />
+          <g transform="rotate(-12 200 200)">
+            <path d="M101 94h59v80h80V94h59v212h-59v-80h-80v80h-59z" fill="#bd3b23" />
+            <path d="M160 174h80v52h-80z" fill="#a32d1a" />
+          </g>
+          <circle cx="323" cy="88" r="11" fill="#242520" />
+        </svg>
+      </div>
+    </section>
+    <section class="page-width enter enter-late" aria-label="Backend connection">
+      <div class="flex flex-wrap items-center justify-between gap-5 border-y border-line py-5">
+        <div class="flex items-center gap-3">
+          <span class="size-2 rounded-full" :class="state === 'online' ? 'bg-emerald-700' : state === 'offline' ? 'bg-accent' : 'bg-muted'" aria-hidden="true"></span>
+          <span role="status" aria-live="polite" class="text-sm font-semibold">{{ status }}</span>
+          <code class="hidden text-xs text-muted sm:inline">GET /api/health</code>
+        </div>
+        <button type="button" class="text-link -my-2" :disabled="state === 'checking'" @click="checkHealth">{{ state === 'checking' ? 'Checking…' : 'Check again' }} <span aria-hidden="true">↻</span></button>
+      </div>
+      <p v-if="state === 'offline'" class="mt-3 text-sm text-muted">Start the app with <code>npm run dev</code>, then check again.</p>
+    </section>
+    <section id="start" class="page-width py-14 lg:py-20">
+      <div class="mb-9 flex flex-wrap items-end justify-between gap-4">
+        <h2 class="text-3xl font-medium tracking-tight">Small start. Endless possibilities.</h2>
+        <span class="eyebrow">Three places to begin</span>
+      </div>
+      <div class="grid gap-8 md:grid-cols-3 md:gap-10">
+        <article class="border-t border-line pt-5">
+          <span class="eyebrow text-accent">01 / The interface</span>
+          <h3 class="mb-3 mt-5 text-xl font-semibold tracking-tight">Find your own look.</h3>
+          <p class="text-sm leading-6 text-muted">Edit this page, add another page, and make it feel like you. Nuxt routing and Tailwind are already wired in.</p>
+          <code class="mt-5 block break-all text-xs">frontend/app/pages/index.vue</code>
+        </article>
+        <article class="border-t border-line pt-5">
+          <span class="eyebrow text-accent">02 / The backend</span>
+          <h3 class="mb-3 mt-5 text-xl font-semibold tracking-tight">Give your idea a voice.</h3>
+          <p class="text-sm leading-6 text-muted">Your first endpoint is live. Build on the health controller to add your own API.</p>
+          <code class="mt-5 block text-xs">src/features/health/</code>
+        </article>
+        <article class="border-t border-line pt-5">
+          <span class="eyebrow text-accent">03 / The connection</span>
+          <h3 class="mb-3 mt-5 text-xl font-semibold tracking-tight">Bring it all together.</h3>
+          <p class="text-sm leading-6 text-muted">Call your API with a same-origin request. Nuxt and Honovel take it from there.</p>
+          <code class="mt-5 block text-xs">fetch('/api/health')</code>
+        </article>
+      </div>
+    </section>
+  </main>
+</template>

package/template/nuxt/frontend/nuxt.config.ts.template

@@ -0,0 +1,22 @@
+import tailwindcss from '@tailwindcss/vite'
+
+const backendDevUrl = process.env.HONOVEL_BACKEND_DEV_URL || 'http://127.0.0.1:8788'
+
+export default defineNuxtConfig({
+  compatibilityDate: '2026-10-02',
+  app: {
+    head: { link: [{ rel: 'icon', type: 'image/png', href: '/honovel-icon.png' }] },
+  },
+  devtools: { enabled: true },
+  css: ['~/assets/css/main.css'],
+  vite: {
+    plugins: [tailwindcss()],
+    server: {
+      proxy: {
+        '/api': backendDevUrl,
+        '/swagger': backendDevUrl,
+        '/openapi.json': backendDevUrl,
+      },
+    },
+  },
+})

package/template/nuxt/frontend/tsconfig.json.template

@@ -0,0 +1,9 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./.nuxt/tsconfig.app.json" },
+    { "path": "./.nuxt/tsconfig.server.json" },
+    { "path": "./.nuxt/tsconfig.shared.json" },
+    { "path": "./.nuxt/tsconfig.node.json" }
+  ]
+}

package/template/nuxt/package.json.template

@@ -0,0 +1,31 @@
+{
+  "scripts": {
+    "typecheck:frontend": "nuxt prepare frontend && nuxt typecheck frontend",
+    "typecheck": "npm run typecheck:backend && npm run typecheck:frontend",
+    "build:frontend": "honovel frontend:build",
+    "build": "npm run cf-typegen && npm run typecheck:frontend && npm run build:frontend && honovel cloudflare:deploy --dry-run --outdir dist/worker",
+    "dev:frontend": "nuxt dev frontend --port 5173 --host localhost --strictPort",
+    "dev": "honovel cloudflare:dev",
+    "dev:debug": "honovel cloudflare:dev --debug",
+    "deploy": "npm run cf-typegen && npm run build:frontend && honovel cloudflare:deploy --minify"
+  },
+  "dependencies": {
+    "@fontsource-variable/manrope": "^5.2.8",
+    "nuxt": "^4.6.4",
+    "vue": "^3.5.22"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.1.0",
+    "tailwindcss": "^4.1.0",
+    "vite": "^7.3.7",
+    "vue-tsc": "^3.1.1"
+  },
+  "overrides": {
+    "@vercel/nft": {
+      "glob": "^14.0.2"
+    },
+    "readdir-glob": {
+      "minimatch": "^11.0.1"
+    }
+  }
+}

package/template/nuxt/wrangler.jsonc

@@ -0,0 +1,11 @@
+{
+  "assets": {
+    "directory": "./dist/frontend",
+    "not_found_handling": "single-page-application",
+    "run_worker_first": [
+      "/api/*",
+      "/swagger",
+      "/openapi.json"
+    ]
+  }
+}