Lockness Hono Bridge

LLM DOCS:VIEW

⚠️ INTERNAL PACKAGE: This is an internal infrastructure package. Developers should use @lockness/core instead.

Internal Hono dependency bridge providing centralized Hono dependency management for Lockness framework.

Overview

@lockness/hono is a proxy package that:

Centralizes Hono dependency - Single source of truth for Hono version
Simplifies imports - All 61 Hono features from one import
Ensures consistency - One Hono version across entire framework
Provides documentation - Comprehensive JSDoc with examples

For Application Developers

DO NOT use this package directly in applications. Use @lockness/core instead:

typescript

// ✅ Recommended (Use this)
import { basicAuth, Context, cors, Hono, logger } from '@lockness/core'

// ❌ Not recommended (Internal package)
import { basicAuth, Context, cors, Hono, logger } from '@lockness/hono'

For Framework Developers

This package is designed for Lockness framework packages that need Hono functionality:

typescript

// In @lockness/auth, @lockness/session, etc.
import { Context, MiddlewareHandler } from '@lockness/hono'

Architecture

Why This Package Exists

Problem: Without a bridge, every Lockness package would import npm:hono@^4.11.1 directly, causing:

Version conflicts between packages
Duplicate Hono instances
Difficult version management

Solution: @lockness/hono acts as a single source of truth:

✅ One Hono version for entire framework
✅ Centralized updates - change once, update everywhere
✅ Clean imports - import { Hono } from '@lockness/hono'
✅ JSR compatibility - packages can depend on npm packages

Updating Hono Version

To update Hono across entire Lockness ecosystem:

Edit deno.json in this package to update Hono version
Bump package version: ./nessy bump 0.2.0
All Lockness packages automatically get new Hono version

Available Exports (61 total)

Core Modules

Hono - Main application class
Context - Request context (type)
MiddlewareHandler - Middleware signature (type)
HTTPException - Error handling
HonoRequest - Request type
Env - Environment types

JSX & Rendering

jsx, jsxFn, Fragment - JSX runtime
jsxRenderer - JSX middleware
html, raw - HTML helpers
css, cx, keyframes, Style - CSS-in-JS

Authentication

basicAuth - HTTP Basic Authentication
bearerAuth - Bearer Token Authentication
jwt - JWT middleware
jwk - JWK middleware

Security

cors - CORS handling
csrf - CSRF protection
secureHeaders - Security headers
ipRestriction - IP-based access control

Content Management

compress - Response compression (gzip, deflate)
etag - ETag generation
prettyJSON - JSON formatting
trailingSlash - URL normalization
bodyLimit - Request body size limits

Request Handling

logger - Request logging
requestId - Request ID generation
language - Language detection
poweredBy - X-Powered-By header
methodOverride - HTTP method override
accepts - Accept header parsing

Timing & Performance

timeout - Request timeout
timing - Server-Timing header
cache - Response caching

Routing

combine - Combine multiple apps
factory - Create middleware/handlers
route - Dynamic routing utilities

SSG & Streaming

ssgParams, toSSG, disableSSG, isSSGContext, onlySSG - Static Site Generation
stream, streamSSE, streamText - Streaming responses

Utilities

getCookie, setCookie, deleteCookie, getSignedCookie, setSignedCookie - Cookie management
getConnInfo - Connection info
validator - Request validation
createMiddleware, createFactory - Factory functions
serveStatic, denoServeStatic - Static file serving
hc - RPC client
proxy - Proxy requests

Import Patterns (Internal Use)

Flat Import (Recommended)

typescript

import { basicAuth, Context, cors, Hono, logger } from '@lockness/hono'

Organized Imports

typescript

import { Hono } from '@lockness/hono'
import { basicAuth, jwt } from '@lockness/hono/middleware/auth'
import { cors, csrf } from '@lockness/hono/middleware/security'
import { logger } from '@lockness/hono/middleware/request'

Namespace Imports

typescript

import { Hono } from '@lockness/hono'
import * as auth from '@lockness/hono/middleware/auth'
import * as security from '@lockness/hono/middleware/security'

app.use('*', security.cors())
app.use('/api/*', auth.bearerAuth({ token: 'secret' }))

Usage Examples (Framework Development)

Basic Middleware

typescript

import { Context, MiddlewareHandler } from '@lockness/hono'

export function customMiddleware(): MiddlewareHandler {
    return async (c: Context, next) => {
        console.log(`Request to: ${c.req.path}`)
        await next()
    }
}

Type-Safe Context

typescript

import { Context, Env } from '@lockness/hono'

type MyEnv = {
    Bindings: {
        DB: D1Database
    }
    Variables: {
        user: { id: string; name: string }
    }
}

export function authMiddleware(): MiddlewareHandler<MyEnv> {
    return async (c: Context<MyEnv>, next) => {
        c.set('user', { id: '1', name: 'John' })
        await next()
    }
}

Custom Error Handling

typescript

import { HTTPException } from '@lockness/hono'

export function throwNotFound(message: string): never {
    throw new HTTPException(404, { message })
}

JSX Components (Framework)

typescript

import { Fragment, jsx } from '@lockness/hono'

export function ErrorPage({ message }: { message: string }) {
    return (
        <html>
            <body>
                <h1>Error</h1>
                <p>{message}</p>
            </body>
        </html>
    )
}

Testing with Hono Bridge

typescript

import { Hono, testClient } from '@lockness/hono'
import { assertEquals } from 'jsr:@std/assert'

Deno.test('middleware test', async () => {
    const app = new Hono()

    app.get('/', (c) => c.json({ message: 'Hello' }))

    const client = testClient(app)
    const res = await client.index.$get()

    assertEquals(res.status, 200)
    assertEquals(await res.json(), { message: 'Hello' })
})

Documentation

All exports include comprehensive JSDoc comments with:

Purpose and description
Usage examples
Parameter descriptions
Return types
Related exports

Example:

typescript

/**
 * HTTP Basic Authentication middleware
 *
 * @example
 * ```typescript
 * app.use('/admin/*', basicAuth({
 *     username: 'admin',
 *     password: 'secret'
 * }))
 * ```
 */
export { basicAuth } from 'npm:hono@4.11.1/basic-auth'

Version Information

Current version: 0.1.21
Based on: Hono 4.11.1
Published to: JSR (@lockness/hono)

Maintenance

Adding New Exports

Add export to mod.ts:
typescript
```
/**
 * Your JSDoc here
 */
export { newFeature } from 'npm:hono@4.11.1/new-feature'
```
Update organized imports if needed:
typescript
```
// middleware/new-category.ts
export { newFeature } from 'npm:hono@4.11.1/new-feature'
```
Update this documentation

Version Updates

Update Hono version in deno.json:
json
```
{
    "imports": {
        "hono": "npm:hono@4.12.0"
    }
}
```
Bump package version:
bash
```
./nessy bump 0.2.0
```
Test all Lockness packages
Publish to JSR

Integration with Lockness Core

@lockness/core re-exports all Hono functionality:

typescript

// @lockness/core/mod.ts
export * from '@lockness/hono'

This allows application developers to use single import:

typescript

import { basicAuth, Context, Hono } from '@lockness/core'

Best Practices

For Framework Developers

Use TypeScript types from @lockness/hono for type safety
Import minimal exports to keep bundle size small
Document usage when creating framework features
Test compatibility when Hono version updates

For Application Developers

Use @lockness/core instead of @lockness/hono
Follow Lockness patterns (MVC, decorators, services)
Refer to @lockness/core docs for application development

Troubleshooting

Import Errors

If you see import errors:

Check you're using correct package:
Framework development: @lockness/hono
Application development: @lockness/core
Verify version compatibility in deno.json
Clear Deno cache: deno cache --reload

Type Errors

If TypeScript types don't match:

Ensure all Lockness packages use same @lockness/hono version
Check deno.json imports are correct
Restart TypeScript server

Contributing

When contributing to this package:

Maintain backward compatibility
Add comprehensive JSDoc to new exports
Test with all Lockness packages
Update this documentation
Follow semantic versioning

Internal Package Notice

Remember: This is an internal package for Lockness framework infrastructure. Application developers should use @lockness/core which provides a unified API including all Hono functionality plus Lockness-specific features like decorators, dependency injection, and MVC patterns.

Edit this page