honertia 0.1.1 → 0.1.2

package/README.md

@@ -9,20 +9,13 @@
 [![Cloudflare Workers](https://img.shields.io/badge/Cloudflare%20Workers-F38020?logo=cloudflare&logoColor=fff)](https://workers.cloudflare.com/)
 [![Effect](https://img.shields.io/badge/Effect-TS-black)](https://effect.website/)
 
-## Raison d'être
+## Overview
 
-I've found myself wanting to use Cloudflare Workers for everything, but having come from a Laravel background nothing quite matched the DX and simplicity of Laravel x Inertia.js. When building Laravel projects I would always use Loris Leiva's laravel-actions package among other opinionated architecture decisions such as Vite, Tailwind, Bun, React etc., all of which have or will be incorporated into this project. With Cloudflare Workers the obvious choice is Hono and so we've adapted the Inertia.js protocol to run on workers+hono to mimic a Laravel-style app. Ever since learning of Effect.ts I've known that I wanted to use it for something bigger, and so we've utilised it here. Ultimately this is a workers+hono+vite+bun+laravel+inertia+effect+betterauth+planetscale mashup that delivers clean, readable, and powerful web app scaffolding.
+An Inertia.js-style adapter for Hono with Effect.js integration. Inertia keeps a server-driven app but behaves like an SPA: link clicks and form posts are intercepted, a fetch/XHR request returns a JSON page object (component + props), and the client swaps the page without a full reload. Honertia layers Laravel-style route patterns and Effect actions on top of that so handlers stay clean, readable, and composable.
 
-An Inertia.js-style adapter for Hono with Effect.js integration. Build full-stack applications with type-safe server actions, Laravel-inspired validation, and seamless React rendering.
+## Raison d'être
 
-## Requirements
-
-- **Runtime**: Node.js 18+ or Bun 1.0+
-- **Peer Dependencies**:
-  - `hono` >= 4.0.0
-  - `better-auth` >= 1.0.0
-- **Dependencies**:
-  - `effect` >= 3.12.0
+I've found myself wanting to use Cloudflare Workers for everything, but having come from a Laravel background nothing quite matched the DX and simplicity of Laravel x Inertia.js. When building Laravel projects I would always use Loris Leiva's laravel-actions package among other opinionated architecture decisions such as Vite, Tailwind, Bun, React etc., all of which have or will be incorporated into this project. With Cloudflare Workers the obvious choice is Hono and so we've adapted the Inertia.js protocol to run on workers+hono to mimic a Laravel-style app. Ever since learning of Effect.ts I've known that I wanted to use it for something bigger, and so we've utilised it here. Ultimately this is a workers+hono+vite+bun+laravel+inertia+effect+betterauth+planetscale mashup.
 
 ## Installation
 
@@ -36,8 +29,9 @@ bun add honertia
 // src/index.ts
 import { Hono } from 'hono'
 import { logger } from 'hono/logger'
-import { setupHonertia, createTemplate, registerErrorHandlers, vite } from 'honertia'
+import { setupHonertia, createTemplate, createVersion, registerErrorHandlers, vite } from 'honertia'
 import { Context, Layer } from 'effect'
+import manifest from '../dist/manifest.json'
 
 import { createDb } from './db'
 import type { Env } from './types'
@@ -45,13 +39,16 @@ import { createAuth } from './lib/auth'
 import { registerRoutes } from './routes'
 
 const app = new Hono<Env>()
+const assetVersion = createVersion(manifest)
+const entry = manifest['src/main.tsx']
+const assetPath = (path: string) => `/${path}`
 
 class BindingsService extends Context.Tag('app/Bindings')<
   BindingsService,
   { KV: KVNamespace }
 >() {}
 
-// Database & Auth
+// Request-scoped setup: put db/auth on c.var so Honertia/Effect can read them.
 app.use('*', async (c, next) => {
   c.set('db', createDb(c.env.DATABASE_URL))
   c.set('auth', createAuth({
@@ -62,24 +59,28 @@ app.use('*', async (c, next) => {
   await next()
 })
 
-// Honertia (bundles core middleware, auth loading, and Effect bridge)
+// Honertia bundles the core middleware + auth loading + Effect runtime setup.
 app.use('*', setupHonertia<Env, BindingsService>({
   honertia: {
-    version: '1.0.0',
+    // Use your asset manifest hash so Inertia reloads on deploy.
+    version: assetVersion,
     render: createTemplate((ctx) => {
       const isProd = ctx.env.ENVIRONMENT === 'production'
       return {
-        title: 'Dashboard',
-        scripts: isProd ? ['/assets/main.js'] : [vite.script()],
+        title: 'My Web App',
+        scripts: isProd ? [assetPath(entry.file)] : [vite.script()],
+        styles: isProd ? (entry.css ?? []).map(assetPath) : [],
         head: isProd ? '' : vite.hmrHead(),
       }
     }),
   },
   effect: {
+    // Expose Cloudflare bindings to Effect handlers via a service layer.
     services: (c) => Layer.succeed(BindingsService, {
       KV: c.env.MY_KV,
     }),
   },
+  // Optional: extra Hono middleware in the same chain.
   middleware: [
     logger(),
     // register additional middleware here...
@@ -101,16 +102,18 @@ import { effectAuthRoutes, RequireAuthLayer } from 'honertia/auth'
 import { showDashboard, listProjects, createProject, showProject, deleteProject } from './actions'
 
 export function registerRoutes(app: Hono<Env>) {
-  // Auth routes (login, register, logout, API handler)
+  // Auth routes (login, register, logout, API handler) wired to better-auth.
+  // CORS for /api/auth/* can be enabled via the `cors` option (see below).
   effectAuthRoutes(app, {
     loginComponent: 'Auth/Login',
     registerComponent: 'Auth/Register',
   })
 
-  // Routes that require the user to be authenticated
+  // Effect routes give you typed, DI-friendly handlers (no direct Hono ctx).
   effectRoutes(app)
     .provide(RequireAuthLayer)
     .group((route) => {
+      // Grouped routes share layers and path prefixes.
       route.get('/', showDashboard) // GET example.com
 
       route.prefix('/projects').group((route) => {
@@ -123,6 +126,163 @@ export function registerRoutes(app: Hono<Env>) {
 }
 ```
 
+### Environment Variables
+
+Honertia reads these from `c.env` (Cloudflare Workers bindings):
+
+```toml
+# wrangler.toml
+ENVIRONMENT = "production"
+```
+
+If you prefer `wrangler.jsonc`, the same binding looks like:
+
+```jsonc
+{
+  "vars": {
+    "ENVIRONMENT": "production"
+  }
+}
+```
+
+Set secrets like `DATABASE_URL` and `BETTER_AUTH_SECRET` via Wrangler (not in source control):
+
+```bash
+wrangler secret put DATABASE_URL
+wrangler secret put BETTER_AUTH_SECRET
+```
+
+### Client Setup (React + Inertia)
+
+Honertia uses the standard Inertia React client. You'll need a client entry
+point and a Vite build that emits a manifest (for `createVersion`).
+
+Install client dependencies:
+
+```bash
+bun add react react-dom @inertiajs/react
+bun add -d @vitejs/plugin-react tailwindcss @tailwindcss/vite
+```
+
+Create a Vite config that enables Tailwind v4, sets up an alias used in the
+examples, and emits `dist/manifest.json`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [tailwindcss(), react()],
+  build: {
+    outDir: 'dist',
+    // Use an explicit filename so imports match build output.
+    manifest: 'manifest.json',
+    emptyOutDir: true,
+  },
+  resolve: {
+    alias: {
+      '~': path.resolve(__dirname, 'src'),
+    },
+  },
+})
+```
+
+Create a Tailwind CSS entry file:
+
+```css
+/* src/styles.css */
+@import "tailwindcss";
+
+@layer base {
+  body {
+    margin: 0;
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+    background-color: #f8fafc;
+    color: #0f172a;
+  }
+}
+```
+
+Set up the Inertia client entry point (default path matches `vite.script()`):
+
+```tsx
+// src/main.tsx
+import './styles.css'
+
+import { createInertiaApp } from '@inertiajs/react'
+import { createRoot } from 'react-dom/client'
+
+const pages = import.meta.glob('./pages/**/*.tsx')
+
+createInertiaApp({
+  resolve: (name) => {
+    const page = pages[`./pages/${name}.tsx`]
+    if (!page) {
+      throw new Error(`Page not found: ${name}`)
+    }
+    return page()
+  },
+  setup({ el, App, props }) {
+    createRoot(el).render(<App {...props} />)
+  },
+})
+```
+
+The `resolve` function maps `render('Projects/Index')` to
+`src/pages/Projects/Index.tsx`.
+
+Optional: add a `tailwind.config.ts` only if you need theme extensions or
+custom content globs.
+
+### Build & Deploy Notes
+
+The server imports `dist/manifest.json`, so it must exist at build time. In
+production, read scripts and styles from the manifest (Tailwind's CSS is listed
+under your entry's `css` array). When deploying with Wrangler, build the client
+assets first:
+
+```bash
+# build client assets before deploying the worker
+bun run build:client
+wrangler deploy
+```
+
+Optional dev convenience: if you want to run the worker without building the
+client, you can keep a stub `dist/manifest.json` (ignored by git) and replace it
+once you run `vite build`.
+
+### Recommended File Structure
+
+Here's a minimal project layout that matches the Quick Start:
+
+```
+.
+├── src/
+│   ├── index.ts                 # Hono app setup (setupHonertia)
+│   ├── routes.ts                # effectRoutes / effectAuthRoutes
+│   ├── main.tsx                 # Inertia + React client entry
+│   ├── styles.css               # Tailwind CSS entry
+│   ├── actions/
+│   │   └── projects/
+│   │       └── list.ts           # listProjects action
+│   ├── pages/
+│   │   └── Projects/
+│   │       └── Index.tsx         # render('Projects/Index')
+│   ├── db.ts
+│   ├── lib/
+│   │   └── auth.ts
+│   └── types.ts
+├── dist/
+│   └── manifest.json            # generated by Vite build
+├── vite.config.ts
+├── wrangler.toml                # or wrangler.jsonc
+├── package.json
+└── tsconfig.json
+```
+
 ### Example Action
 
 Here's the `listProjects` action referenced above:
@@ -157,10 +317,92 @@ export const listProjects = Effect.gen(function* () {
   const db = yield* DatabaseService
   const user = yield* AuthUserService
   const props = yield* fetchProjects(db as Database, user)
-  return yield* render('Dashboard/Projects/Index', props)
+  return yield* render('Projects/Index', props)
 })
 ```
 
+The component name `Projects/Index` maps to a file on disk. A common
+Vite + React layout is:
+
+```
+src/pages/Projects/Index.tsx
+```
+
+That means the folders mirror the component path, and `Index.tsx` is the file
+that exports the page component. In the example below, `Link` comes from
+`@inertiajs/react` because it performs Inertia client-side visits (preserving
+page state and avoiding full reloads), whereas a plain `<a>` would do a full
+navigation.
+
+```tsx
+// src/pages/Projects/Index.tsx
+/**
+ * Projects Index Page
+ */
+
+import { Link } from '@inertiajs/react'
+import Layout from '~/components/Layout'
+import type { PageProps, Project } from '~/types'
+
+interface Props {
+  projects: Project[]
+}
+
+export default function ProjectsIndex({ projects }: PageProps<Props>) {
+  return (
+    <Layout>
+      <div className="flex justify-between items-center mb-6">
+        <h1 className="text-2xl font-bold text-gray-900">Projects</h1>
+        <Link
+          href="/projects/create"
+          className="bg-indigo-600 text-white px-4 py-2 rounded-md hover:bg-indigo-700"
+        >
+          New Project
+        </Link>
+      </div>
+      
+      <div className="bg-white rounded-lg shadow">
+        {projects.length === 0 ? (
+          <div className="p-6 text-center text-gray-500">
+            No projects yet.{' '}
+            <Link href="/projects/create" className="text-indigo-600 hover:underline">
+              Create your first project
+            </Link>
+          </div>
+        ) : (
+          <ul className="divide-y divide-gray-200">
+            {projects.map((project) => (
+              <li key={project.id}>
+                <Link
+                  href={`/projects/${project.id}`}
+                  className="block px-6 py-4 hover:bg-gray-50"
+                >
+                  <div className="flex justify-between items-start">
+                    <div>
+                      <h3 className="text-sm font-medium text-gray-900">
+                        {project.name}
+                      </h3>
+                      {project.description && (
+                        <p className="text-sm text-gray-500 mt-1">
+                          {project.description}
+                        </p>
+                      )}
+                    </div>
+                    <span className="text-sm text-gray-400">
+                      {new Date(project.createdAt).toLocaleDateString()}
+                    </span>
+                  </div>
+                </Link>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </Layout>
+  )
+}
+```
+
 ### Vite Helpers
 
 The `vite` helper provides dev/prod asset management:
@@ -172,6 +414,15 @@ vite.script()   // 'http://localhost:5173/src/main.tsx'
 vite.hmrHead()  // HMR preamble script tags for React Fast Refresh
 ```
 
+## Requirements
+
+- **Runtime**: Node.js 18+ or Bun 1.0+
+- **Peer Dependencies**:
+  - `hono` >= 4.0.0
+  - `better-auth` >= 1.0.0
+- **Dependencies**:
+  - `effect` >= 3.12.0
+
 ## Core Concepts
 
 ### Effect-Based Handlers
@@ -567,6 +818,23 @@ effectAuthRoutes(app, {
 })
 ```
 
+To enable CORS for the auth API handler (`/api/auth/*`), pass a `cors` config.
+By default, no CORS headers are added (recommended when your UI and API share the same origin).
+Use this when your frontend is on a different origin (local dev, separate domain, mobile app, etc.).
+
+```typescript
+effectAuthRoutes(app, {
+  apiPath: '/api/auth',
+  cors: {
+    origin: ['http://localhost:5173', 'http://localhost:3000'],
+    credentials: true,
+  },
+})
+```
+
+This sets the appropriate `Access-Control-*` headers and handles `OPTIONS` preflight for the auth API routes.
+Always keep the `origin` list tight; avoid `'*'` for auth endpoints, especially with `credentials: true`.
+
 ## Action Factories
 
 For common patterns, use action factories:

package/dist/helpers.d.ts

@@ -6,6 +6,12 @@ import type { PageObject } from './types.js';
 export interface PageProps {
     errors?: Record<string, string>;
 }
+export interface AssetManifestEntry {
+    file?: string;
+    css?: string[];
+    assets?: string[];
+}
+export type AssetManifest = Record<string, string | AssetManifestEntry>;
 export interface TemplateOptions {
     title?: string;
     scripts?: string[];
@@ -26,16 +32,23 @@ export interface TemplateOptions {
  *
  * @example Dynamic config based on environment
  * ```ts
+ * const entry = manifest['src/main.tsx']
+ * const assetPath = (path: string) => `/${path}`
+ *
  * createTemplate((ctx) => ({
  *   title: 'App',
  *   scripts: ctx.env.ENVIRONMENT === 'production'
- *     ? ['/assets/main.js']
- *     : ['http://localhost:5173/src/main.tsx'],
+ *     ? [assetPath(entry.file)]
+ *     : [vite.script()],
+ *   styles: ctx.env.ENVIRONMENT === 'production'
+ *     ? (entry.css ?? []).map(assetPath)
+ *     : [],
+ *   head: ctx.env.ENVIRONMENT === 'production' ? '' : vite.hmrHead(),
  * }))
  * ```
  */
 export declare function createTemplate(options: TemplateOptions | ((ctx: Context) => TemplateOptions)): (page: PageObject, ctx?: Context) => string;
-export declare function createVersion(manifest: Record<string, string>): string;
+export declare function createVersion(manifest: AssetManifest): string;
 /**
  * Vite development configuration helpers.
  */
@@ -57,7 +70,7 @@ export declare const vite: {
      * @param port - Vite dev server port (default: 5173)
      * @example
      * ```ts
-     * scripts: isProd ? ['/assets/main.js'] : [vite.script()]
+     * scripts: isProd ? [manifest['src/main.tsx'].file] : [vite.script()]
      * ```
      */
     script(entry?: string, port?: number): string;

package/dist/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,eAAe,CAAC,GAC7D,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,MAAM,CA6C7C;AAWD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAStE;AAED;;GAEG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;OAQG;4BACmB,MAAM;IAa5B;;;;;;;;;OASG;2CAC2C,MAAM;CAGrD,CAAA"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAA;AAEvE,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,eAAe,CAAC,GAC7D,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,MAAM,CA6C7C;AAWD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA8B7D;AAED;;GAEG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;OAQG;4BACmB,MAAM;IAa5B;;;;;;;;;OASG;2CAC2C,MAAM;CAGrD,CAAA"}

package/dist/helpers.js

@@ -14,11 +14,18 @@
  *
  * @example Dynamic config based on environment
  * ```ts
+ * const entry = manifest['src/main.tsx']
+ * const assetPath = (path: string) => `/${path}`
+ *
  * createTemplate((ctx) => ({
  *   title: 'App',
  *   scripts: ctx.env.ENVIRONMENT === 'production'
- *     ? ['/assets/main.js']
- *     : ['http://localhost:5173/src/main.tsx'],
+ *     ? [assetPath(entry.file)]
+ *     : [vite.script()],
+ *   styles: ctx.env.ENVIRONMENT === 'production'
+ *     ? (entry.css ?? []).map(assetPath)
+ *     : [],
+ *   head: ctx.env.ENVIRONMENT === 'production' ? '' : vite.hmrHead(),
  * }))
  * ```
  */
@@ -66,7 +73,26 @@ function escapeHtml(str) {
         .replace(/'/g, ''');
 }
 export function createVersion(manifest) {
-    const combined = Object.values(manifest).sort().join('');
+    const assetFiles = [];
+    for (const value of Object.values(manifest)) {
+        if (typeof value === 'string') {
+            assetFiles.push(value);
+            continue;
+        }
+        if (!value || typeof value !== 'object') {
+            continue;
+        }
+        if (typeof value.file === 'string') {
+            assetFiles.push(value.file);
+        }
+        if (Array.isArray(value.css)) {
+            assetFiles.push(...value.css);
+        }
+        if (Array.isArray(value.assets)) {
+            assetFiles.push(...value.assets);
+        }
+    }
+    const combined = assetFiles.sort().join('');
     let hash = 0;
     for (let i = 0; i < combined.length; i++) {
         const char = combined.charCodeAt(i);
@@ -107,7 +133,7 @@ export const vite = {
      * @param port - Vite dev server port (default: 5173)
      * @example
      * ```ts
-     * scripts: isProd ? ['/assets/main.js'] : [vite.script()]
+     * scripts: isProd ? [manifest['src/main.tsx'].file] : [vite.script()]
      * ```
      */
     script(entry = '/src/main.tsx', port = 5173) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "honertia",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Inertia.js-style server-driven SPA adapter for Hono",
   "type": "module",
   "main": "./dist/index.js",