{"id":14984975,"url":"https://github.com/jcs224/hono_sessions","last_synced_at":"2025-04-10T23:14:53.112Z","repository":{"id":190547175,"uuid":"682875520","full_name":"jcs224/hono_sessions","owner":"jcs224","description":"Cookie-based sessions for Hono applications","archived":false,"fork":false,"pushed_at":"2025-03-21T02:56:50.000Z","size":204,"stargazers_count":89,"open_issues_count":2,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T23:14:27.584Z","etag":null,"topics":["bun","cloudflare-pages","cloudflare-workers","deno","hacktoberfest","hono","session-management"],"latest_commit_sha":null,"homepage":"https://jsr.io/@jcs224/hono-sessions","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jcs224.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-08-25T04:38:56.000Z","updated_at":"2025-04-03T15:08:23.000Z","dependencies_parsed_at":"2023-08-25T06:33:09.448Z","dependency_job_id":"eeb548e8-50b6-45a4-bfbe-d37ef8dd5401","html_url":"https://github.com/jcs224/hono_sessions","commit_stats":null,"previous_names":["jcs224/hono_sessions"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcs224%2Fhono_sessions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcs224%2Fhono_sessions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcs224%2Fhono_sessions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jcs224%2Fhono_sessions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jcs224","download_url":"https://codeload.github.com/jcs224/hono_sessions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248312135,"owners_count":21082638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","cloudflare-pages","cloudflare-workers","deno","hacktoberfest","hono","session-management"],"created_at":"2024-09-24T14:10:00.932Z","updated_at":"2025-04-10T23:14:53.090Z","avatar_url":"https://github.com/jcs224.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hono Sessions Middleware\nUse cookie-based sessions with the [Hono](https://hono.dev/) framework.\n\n### Supported runtimes\n\nHono Sessions is currently tested on these runtimes:\n\n- Deno\n- Cloudflare Workers\n- Cloudflare Pages\n- Bun\n- Node (v20+)\n\nOther runtimes may work, but are untested. In addition to Hono's requirements, the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) is required for this library.\n\n### 🛠️ Features\n- Flash messages — data that is deleted once it's read (one-off error messages, etc.)\n- Built-in Memory and Cookie storage drivers, as well as [community-supported drivers](https://github.com/jcs224/hono_sessions/wiki/Community-adapters) and the ability to [create your own storage driver](https://github.com/jcs224/hono_sessions/wiki/Creating-a-custom-storage-driver)\n- Encrypted cookies thanks to [iron-webcrypto](https://github.com/brc-dd/iron-webcrypto)\n- Session expiration after inactivity\n- Session key rotation* \n- Strong typing for session variables\n\n\u003e *It is not necessary to rotate CookieStore sessions because of how a pure cookie session works (no server-side state). Therefore, using session key rotation will have no effect while using CookieStore.\n\n## Installation and Usage\n\n### Deno\n\nSimply include the package from [JSR](https://jsr.io/@jcs224/hono-sessions) or [NPM](https://www.npmjs.com/package/hono-sessions)\n\n```ts\n// JSR\nimport { sessionMiddleware } from 'jsr:@jcs224/hono-sessions'\n\n// NPM\nimport { sessionMiddleware } from 'npm:hono-sessions'\n```\n\nYou can also use `deno add` and not need the `jsr:` specifier. \n\n### Node, Bun, Cloudflare Workers, etc.\n\nInstall the NPM package\n```\nnpm install hono-sessions\n```\n\n## Examples\n\n### Deno\n```ts\nimport { Hono } from 'npm:hono'\nimport { \n  Session,\n  sessionMiddleware, \n  CookieStore \n} from 'jsr:@jcs224/hono-sessions'\n\n// Add types to your session data (optional)\ntype SessionDataTypes = {\n  'counter': number\n}\n\n// Set up your Hono instance, using your types\nconst app = new Hono\u003c{\n  Variables: {\n    session: Session\u003cSessionDataTypes\u003e,\n    session_key_rotation: boolean\n  }\n}\u003e()\n\nconst store = new CookieStore()\n\napp.use('*', sessionMiddleware({\n  store,\n  encryptionKey: 'password_at_least_32_characters_long', // Required for CookieStore, recommended for others\n  expireAfterSeconds: 900, // Expire session after 15 minutes of inactivity\n  cookieOptions: {\n    sameSite: 'Lax', // Recommended for basic CSRF protection in modern browsers\n    path: '/', // Required for this library to work properly\n    httpOnly: true, // Recommended to avoid XSS attacks\n  },\n}))\n\napp.get('/', async (c, next) =\u003e {\n  const session = c.get('session')\n\n  session.set('counter', (session.get('counter') || 0) + 1)\n\n  return c.html(`\u003ch1\u003eYou have visited this page ${ session.get('counter') } times\u003c/h1\u003e`)\n})\n\nDeno.serve(app.fetch)\n```\n\n### Bun\n\n```ts\nimport { Hono } from 'hono'\nimport { sessionMiddleware, CookieStore, Session } from 'hono-sessions'\n\n// Same as Deno, however instead of:\n// Deno.serve(app.fetch)\n// use:\n\nexport default {\n  port: 3000,\n  fetch: app.fetch\n}\n```\n\n#### Using Bun's SQLite storage driver\n\nThis will automatically create a `database.sqlite` file and a `sessions` table in that sqlite database.\n\n```ts\nimport { Hono } from 'hono'\nimport { sessionMiddleware } from 'hono-sessions'\nimport { BunSqliteStore } from 'hono-sessions/bun-sqlite-store'\nimport { Database } from 'bun:sqlite'\n\nconst app = new Hono()\n\nconst db = new Database('./database.sqlite')\nconst store = new BunSqliteStore(db)\n\napp.use('*', sessionMiddleware({\n  store,\n  // ... other session options\n}))\n\n// Other app code\n\nexport default {\n  port: 3000,\n  fetch: app.fetch\n}\n```\n\n### Cloudflare Workers / Pages\n\n```ts\nimport { Hono } from 'hono'\nimport { sessionMiddleware, CookieStore, Session } from 'hono-sessions'\n\n// Same as Deno, however instead of:\n// Deno.serve(app.fetch)\n// use:\n\nexport default app\n```\n\n## API\n\nThe `session` object returned from `c.get('session')` has several methods:\n\n- `get(id: string)`: Fetch the value from a given key.\n\n- `set(id: string, value: any)`: Set a value that can be serialized with `JSON.stringify()`\n\n- `flash(id: string, value: any)`: Similar to `set()`, however the value is deleted immediately after it's read once. Best used for one-off alerts or form validation messages (login failure, etc.)\n\n- `forget(id: string)`: Remove a value from the session based on its key\n\n## Troubleshooting\n\n### TypeScript errors\n\nHono has a high upgrade frequency, but the API for middleware this library relies on remains largely unchanged between Hono releases. You may experience a TypeScript error if you use this library with the latest version of Hono. In that case, before you load the middleware into your Hono app, you might want to have TypeScript ignore this error:\n\n```ts\n// @ts-ignore\napp.use('*', sessionMiddleware({\n  // ...\n}))\n```\n\nTypeScript should otherwise work normally.\n\n## Contributing\n\nThis package is built Deno-first, so you'll need to have Deno installed in your development environment. See their [website](https://deno.com/) for installation instructions specific to your platform.\n\nOnce Deno is installed, there is a test server you can run a basic web server to check your changes:\n\n```\ndeno run --allow-net --watch test/deno/server_deno.ts\n```\n\nThere's also a [Playwright](https://playwright.dev/) test suite. By default, it is set up to run a Deno server with the MemoryStore driver. In Github actions, it runs through a series of runtimes and storage drivers when a pull request is made.\n\n```\ncd playwright\nnpm install\nnpx playwright test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcs224%2Fhono_sessions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjcs224%2Fhono_sessions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjcs224%2Fhono_sessions/lists"}