{"id":13798910,"url":"https://github.com/koajs/koa-hbs","last_synced_at":"2025-12-17T14:36:36.153Z","repository":{"id":12754651,"uuid":"15427895","full_name":"koajs/koa-hbs","owner":"koajs","description":"Handlebars templates for Koa.js","archived":false,"fork":false,"pushed_at":"2020-10-02T19:17:52.000Z","size":133,"stargazers_count":161,"open_issues_count":9,"forks_count":40,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-11-17T12:03:24.913Z","etag":null,"topics":["handlebars","hbs","javascript","koa","koa-hbs","koa2","middleware","partials"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/koajs.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}},"created_at":"2013-12-25T01:56:32.000Z","updated_at":"2025-10-29T09:08:47.000Z","dependencies_parsed_at":"2022-09-10T17:01:17.351Z","dependency_job_id":null,"html_url":"https://github.com/koajs/koa-hbs","commit_stats":null,"previous_names":["gilt/koa-hbs","jwilm/koa-hbs"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/koajs/koa-hbs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-hbs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-hbs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-hbs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-hbs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koajs","download_url":"https://codeload.github.com/koajs/koa-hbs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koajs%2Fkoa-hbs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27783740,"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","status":"online","status_checked_at":"2025-12-17T02:00:08.291Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["handlebars","hbs","javascript","koa","koa-hbs","koa2","middleware","partials"],"created_at":"2024-08-04T00:00:56.415Z","updated_at":"2025-12-17T14:36:36.134Z","avatar_url":"https://github.com/koajs.png","language":"JavaScript","funding_links":[],"categories":["仓库"],"sub_categories":["中间件"],"readme":"[koa]:https://github.com/koajs/koa/\n[handlebars]:http://handlebarsjs.com\n\nkoa-hbs [![Build Status](https://travis-ci.org/koajs/koa-hbs.svg?branch=master)](https://travis-ci.org/koajs/koa-hbs)\n=======\n\n[Handlebars][handlebars] templates for [Koa][koa]\n\n## \u0026nbsp;\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e:rocket: \u0026nbsp; Are you ready to tackle ES6 and hone your JavaScript Skills?\u003c/b\u003e \u0026nbsp; :rocket:\u003cbr/\u003e\n  Check out these outstanding \u003ca href=\"https://es6.io/friend/POWELL\"\u003eES6 courses\u003c/a\u003e by \u003ca href=\"https://github.com/wesbos\"\u003e@wesbos\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Usage\nkoa-hbs is middleware. We stash an instance of koa-hbs for you in the library\nso you don't have to manage it separately. Configure the default instance by\npassing an [options](#options) hash to #middleware. To render a template then,\njust `yield this.render('templateName');`. Here's a basic app demonstrating all that:\n\n```javascript\nvar koa = require('koa');\nvar hbs = require('koa-hbs');\n\nvar app = koa();\n\n// koa-hbs is middleware. `use` it before you want to render a view\napp.use(hbs.middleware({\n  viewPath: __dirname + '/views'\n}));\n\n// Render is attached to the koa context. Call `this.render` in your middleware\n// to attach rendered html to the koa response body.\napp.use(function *() {\n  yield this.render('main', {title: 'koa-hbs'});\n})\n\napp.listen(3000);\n```\n\nAfter a template has been rendered, the template function is cached. `#render`\naccepts two arguments - the template to render, and an object containing local\nvariables to be inserted into the template. The result is assigned to Koa's\n`this.response.body`.\n\n## Options\nThe plan for koa-hbs is to offer identical functionality as express-hbs\n(eventaully). These options are supported _now_.\n\n#### `viewPath` _required_\nType: `Array|String`  \nFull path from which to load templates\n\n#### `handlebars`\nType:`Object:Handlebars`  \nPass your own instance of handlebars\n\n#### `templateOptions`\nType: `Object`  \nHash of [handlebars options](http://handlebarsjs.com/execution.html#Options) to\npass to `template()`\n\n#### `extname`\nType:`String`  \nAlter the default template extension (default: `'.hbs'`)\n\n#### `partialsPath`\nType:`Array|String`  \nFull path to partials directory\n\n#### `defaultLayout`\nType:`String`  \nName of the default layout\n\n#### `layoutsPath`\nType:`String`  \nFull path to layouts directory\n\n#### `contentHelperName`\nType:`String`  \nAlter `contentFor` helper name\n\n#### `blockHelperName`\nType:`String`  \nAlter `block` helper name\n\n#### `disableCache`\nType:`Boolean`  \nDisable template caching\n\n## Registering Helpers\nHelpers are registered using the #registerHelper method. Here is an example\nusing the default instance (helper stolen from official Handlebars\n[docs](http://handlebarsjs.com):\n\n```javascript\nhbs = require('koa-hbs');\n\nhbs.registerHelper('link', function(text, url) {\n  text = hbs.Utils.escapeExpression(text);\n  url  = hbs.Utils.escapeExpression(url);\n\n  var result = '\u003ca href=\"' + url + '\"\u003e' + text + '\u003c/a\u003e';\n\n  return new hbs.SafeString(result);\n});\n```\nYour helper is then accessible in all views by using, `{{link \"Google\" \"http://google.com\"}}`\n\nThe `registerHelper`, `Utils`, and `SafeString` methods all proxy to an\ninternal Handlebars instance. If passing an alternative instance of\nHandlebars to the middleware configurator, make sure to do so before\nregistering helpers via the koa-hbs proxy of the above functions, or\njust register your helpers directly via your Handlebars instance.\n\nYou can also access the current Koa context in your helper. If you want to have\na helper that outputs the current URL, you could write a helper like the following\nand call it in any template as `{{requestURL}}`.\n\n```\nhbs.registerHelper('requestURL', function() {\n  var url = hbs.templateOptions.data.koa.request.url;\n  return url;\n});\n```\n\n## Registering Partials\nThe simple way to register partials is to stick them all in a directory, and\npass the `partialsPath` option when generating the middleware. Say your views\nare in `./views`, and your partials are in `./views/partials`. Configuring the\nmiddleware via\n\n```\napp.use(hbs.middleware({\n  viewPath: __dirname + '/views',\n  partialsPath: __dirname + '/views/partials'\n}));\n```\n\nwill cause them to be automatically registered. Alternatively, you may register\npartials one at a time by calling `hbs.registerPartial` which proxies to the\ncached handlebars `#registerPartial` method.\n\n## Layouts\nPassing `defaultLayout` with the a layout name will cause all templates to be\ninserted into the `{{{body}}}` expression of the layout. This might look like\nthe following.\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n  \u003ctitle\u003e{{title}}\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  {{{body}}}\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nIn addition to, or alternatively, you may specify a layout to render a template\ninto. Simply specify `{{!\u003c layoutName }}` somewhere in your template. koa-hbs\nwill load your layout from `layoutsPath` if defined, or from `viewPath`\notherwise. If `viewPath` is set to an Array of paths, **_the first path in the\narray will be assumed to contain the layout named._**\n\nAt this time, only a single content block (`{{{body}}}`) is supported.\n\n## Overriding Layouts using Locals\n\nAs of version 0.9.0, it's possible to override the layout used for rendering,\nusing `locals`. For example:\n\n```js\nrouter.get('/', function *() {\n  yield this.render('foo', {\n    layout: 'bar'\n  });\n });\n ```\n\nSee the [tests](https://github.com/gilt/koa-hbs/blob/master/test/app/index.js#L44)\nfor more.\n\n## Block content\nReserve areas in a layout by using the `block` helper like so.\n\n```html\n{{#block \"sidebar\"}}\n  \u003c!-- default content for the sidebar block --\u003e\n{{/block}}\n```\n\nThen in a template, use the `contentFor` helper to render content into the\nblock.\n\n```html\n{{#contentFor \"sidebar\"}}\n  \u003caside\u003e\n    \u003ch2\u003e{{sidebarTitleLocal}}\u003c/h2\u003e\n    \u003cp\u003e{{sidebarContentLocal}}\u003c/p\u003e\n  \u003c/aside\u003e\n{{/contentFor}}\n```\n\n## Disable Template Caching\nTo disable the caching of templates and partials, use the `disableCache` option.\nSet this option to `true` to disable caching. Default is `false`.\n*Remember to set this option to `false` for production environments, or performance\ncould be impacted!*\n\n## Locals\n\nApplication local variables (```[this.state](https://github.com/koajs/koa/blob/master/docs/api/context.md#ctxstate)```) are provided to all templates rendered within the application.\n\n```javascript\napp.use(function *(next) {\n  this.state.title = 'My App';\n  this.state.email = 'me@myapp.com';\n  yield next;\n});\n```\n\nThe state object is a JavaScript Object. The properties added to it will be\nexposed as local variables within your views.\n\n```\n\u003ctitle\u003e{{title}}\u003c/title\u003e\n\n\u003cp\u003eContact : {{email}}\u003c/p\u003e\n```\n\n## Koa2\n\nKoa2 is supported via the `@next` module version. It is considered experimental\nand **_requires Node v7 or higher_**. You can obtain this version by running:\n\n```bash\nnpm install koa-hbs@next --save\n```\n\nFor information on using this version, please read the branch's\n[README](https://github.com/gilt-labs/koa-hbs/tree/next). If using a version of\nnode older than v7.6, we recommend using\n[harmonica](https://www.npmjs.com/package/harmonica) to enable the `--harmony`\nflags, which activates native `async/await` support.\n\n\nIf you'd rather not use an experimental version, or you need to use an older\nversion of Node, you can reference this example\nrepo that demonstrates how to use `koa-hbs` with Koa2:\n[koa-hbs-koa2-howto](https://github.com/shellscape/koa-hbs-koa2-howto)\n\nCredit to [@chrisveness](https://github.com/chrisveness) for the initial investigation.\n\n## Example\nYou can run the included example via `npm install koa` and\n`node --harmony app.js` from the example folder.\n\n## Unsupported Features\n\nHere's a few things _koa-hbs_ does not plan to support unless someone can\nprovide really compelling justification.\n\n### Async Helpers\n_koa-hbs_ does not support asynchronous helpers. No, really - just load your\ndata before rendering a view. This helps on performance and separation of\nconcerns in your app.\n\n## Handlebars Version\n\nAs of koa-hbs@0.9.0, the version of the Handlebars dependency bundled with this\nmodule has been updated to 4.0.x. If this causes conflicts for your project, you\nmay pass your own instance of Handlebars to the module, or downgrade to the last\n0.8.x version.\n\n## Credits\nFunctionality and code were inspired/taken from\n[express-hbs](https://github.com/barc/express-hbs/).\nMany thanks to [@jwilm](https://github.com/jwilm) for authoring this middleware.\n\n[travis-badge]: https://travis-ci.org/gilt/koa-hbs.png?branch=master\n[repo-url]: https://travis-ci.org/gilt/koa-hbs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fkoa-hbs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoajs%2Fkoa-hbs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoajs%2Fkoa-hbs/lists"}