Hono Cookie State

hono-cookie-state

• hono-cookie-state
  • Overview
  • Features
  • Usage
    • Install package
    • Import and use
  • Roadmap
  • Credits and Notes
  • Releasing
  • License

Overview

hono-cookie-state is a simple library to persist data / states in cookies for Hono, securely (via iron-webcrypto) and with type-safety.

Features

• 👌 TypeScript

Usage

Install package

# npm
npm install -D hono-cookie-state

# bun
bun add -D hono-cookie-state

# pnpm
pnpm install -D hono-cookie-state

Import and use

import type { CookieState } from 'hono-cookie-state'
import { createCookieState } from 'hono-cookie-state'

// Usage is as simple .use() the created middleware, and just update the state's data, the cookie will automatically be updated when the data has changed, or is near expiration with `autoRefreshSession=true` (default)
const app = new Hono()
  .use(createCookieState({
    key: 'hiWorld',
    secret: 'password_at_least_32_characters!',
    cookieOptions: {
      maxAge: 90 * 60, // 90 mins
      sameSite: 'None',
      secure: true,
      path: '/',
      httpOnly: true,
    },
  }))
  // For simple inline usage, variable type is automatically populated to context chain
  .get('/sample', async (c) => {
    const state = c.var.hiWorld // is of type CookieState<any>
    state.data.hi = 'world'
  })

// For more complex usage, you can populate Hono's init Env:
const app = new Hono<{ Variables: { hiWorld: CookieState<{ hello: string }> } }>()
// Or pass the data type into createCookieState, note you need to also pass the key as the second generic, due to TS limitation:
createCookieState<{ hello: string }, 'hiWorld'>({
  key: 'hiWorld',
  secret: 'password_at_least_32_characters!',
})

Roadmap

• Chunked cookie support
  • Awaits honojs/hono#4447

Credits and Notes

This package copies the inline, rewritten iron-crypto.ts and base64url encoding.ts from h3

Releasing

Releases are version-first and manual. Go to Actions → Release → Run workflow, enter the version to ship (e.g. 0.2.0) and optionally tick dry-run to stop before pushing. The workflow validates the version, runs the lint/type/test gate, builds, lets changelogen bump package.json, write CHANGELOG.md, commit and tag v<version>, pushes that, creates the GitHub release and publishes to npm via trusted publishing (OIDC). A pushed tag publishes nothing — only a workflow dispatch does.

First-time setup: publish the package once by hand, then add this repository as a trusted publisher on npmjs.com (package → Settings → Trusted Publisher), naming the workflow file release.yml.

Local helpers: pnpm run release:check 0.2.0 validates a version against package.json, pnpm run release:preview prints the changelog the next release would get.

License