{"id":14989662,"url":"https://github.com/nfantone/mu-koan","last_synced_at":"2025-04-12T01:41:11.073Z","repository":{"id":57304719,"uuid":"53069056","full_name":"nfantone/mu-koan","owner":"nfantone","description":"An opinionated Koa v2 JSON API boilerplate to achieve enlightenment","archived":false,"fork":false,"pushed_at":"2020-05-17T19:13:07.000Z","size":162,"stargazers_count":6,"open_issues_count":16,"forks_count":1,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-04-07T00:37:35.295Z","etag":null,"topics":["enlightenment","json-api-boilerplate","koa","middleware"],"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/nfantone.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":"2016-03-03T17:20:38.000Z","updated_at":"2020-05-19T03:02:42.000Z","dependencies_parsed_at":"2022-09-20T18:53:09.309Z","dependency_job_id":null,"html_url":"https://github.com/nfantone/mu-koan","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfantone%2Fmu-koan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfantone%2Fmu-koan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfantone%2Fmu-koan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfantone%2Fmu-koan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nfantone","download_url":"https://codeload.github.com/nfantone/mu-koan/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505742,"owners_count":21115352,"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":["enlightenment","json-api-boilerplate","koa","middleware"],"created_at":"2024-09-24T14:18:43.523Z","updated_at":"2025-04-12T01:41:11.051Z","avatar_url":"https://github.com/nfantone.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mu-kōän 公案\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/nfantone/mu-koan.svg)](https://greenkeeper.io/)\n[![Build Status](https://travis-ci.org/nfantone/mu-koan.svg?branch=develop)](https://travis-ci.org/nfantone/mu-koan) [![codecov.io](https://codecov.io/github/nfantone/mu-koan/coverage.svg?branch=develop)](https://codecov.io/github/nfantone/mu-koan?branch=develop) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://github.com/nfantone/mu-koan/blob/master/LICENSE) [![js-semistandard-style](https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg?style=flat-square)](https://github.com/Flet/semistandard)\n\n\u003e An opinionated Koa v2 JSON API boilerplate to achieve enlightenment.\n\nmu-kōän serves as kickstarter set for Koa 2.0.0+ applications aimed at creating _stateless_ REST JSON APIs. It includes a set of predefined Koa middlewares allowing for quicker bootstrapping with sensible defaults.\n\n```sh\nnpm i --save mu-koan\n```\n\n\u003e mu-kōän requires [node](https://nodejs.org) 6.0.0+, matching [Koa requirements](https://github.com/koajs/koa/blob/master/package.json#L61).\n\n## Usage\nCreate a new Koa app, configure it the way you want and pass it as an argument to the `bootstrap` exported function, wich will add its own middlewares and initialize routes.\n\n```javascript\n'use strict'\n// Import some configuration\n// For a detail of available options, see\n// section below.\nconst CONFIG = require('./config.json')\nconst middlewares = require('mu-koan');\nconst Koa = require('koa');\n\nlet app = new Koa();\n// ...\n// Configure other middlewares on `app`.\n// For a list of already included middlewares\n// by mu-kōän checkout package.json or the section below:\n// https://github.com/nfantone/mu-koan/tree/feature/module#features\n\nmiddlewares.bootstrap(app, CONFIG);\n\n// Start Koa server\napp.listen();\n```\n\n\u003e You can take a look at a minimal running `mu-koan` sample app at [app.js](./app.js)\n\n\n### Advanced Usage\nMiddleware order declaration is important and some of them need to be placed as close to the top of the chain as possible (like global error handlers). By default, mu-kōän declares all of its packed middlewares in a single call to `bootstrap`. However, if you need to declare custom middlewares somewhere in between you can make use of the `initialize` method.\n\nDeclare them _before_ calling `bootstrap`, but after `initialize`.\n\n```js\nconst custom = require('./middlewares/custom');\n\nlet app = new Koa();\n\nmiddlewares.initialize(app, CONFIG);\n\n// Declare custom middleware here, after initialize\napp.use(custom());\n\nmiddlewares.bootstrap(app, CONFIG);\n```\n\nThis way, \"global\" middlewares are still declared at the top (by calling `initialize`), but your custom functions run immediately after, just before any other set by mu-kōän.\n\n\u003e Internally, `bootstrap` calls `initialize` if it hasn't already been call on that Koa app instance. So you'll always end up declaring all included middlewares, either way.\n\n## Configuration\nThe following properties are used to configure the different middlewares packed by `mu-koan`:\n\n```javascript\n{\n  \"bodyParser\": {\n    // See https://www.npmjs.com/koa-bodyparser for more\n    \"jsonLimit\": \"2mb\"\n  },\n  \"jwt\": {\n    // Note that actual koa-jwt options are nested within \"options\"\n    \"options\": {\n      // See https://www.npmjs.com/koa-jwt for more\n      \"passthrough\": true,\n      \"secret\": \"(w_E8Qd--@cBvgr8\"\n    },\n    // Exclude JWT verification from certain paths\n    \"unless\": {\n      // See https://github.com/Foxandxss/koa-unless#current-options for more\n      \"path\": [\"/status\"]\n    }\n  },\n  \"cors\": {\n    // See https://www.npmjs.com/kcors for more\n    \"allowedMethods\": \"GET\"\n  },\n  \"helmet\": {\n    // See https://github.com/helmetjs/helmet#top-level-helmet for more\n    \"frameguard\": false\n  }\n  \"morgan\": {\n    \"options\": {\n      // See https://github.com/expressjs/morgan#options for more\n      \"immediate\": true\n    },\n    // See https://www.npmjs.com/koa-morgan for more\n    \"format\": \"combined\"\n  },\n  \"cacheControl\": {\n    // See https://github.com/DaMouse404/koa-cache-control#options for more\n    \"public\": true,\n    \"maxAge\": 3600\n  },\n  // Path to favicon file needed by https://www.npmjs.com/koa-favicon\n  \"favicon\": \"./favicon.ico\"\n}\n```\n\n## Logging\nmu-kōän prints out log messages using a `winston` logger. It can be provided as a second optional `options` argument to the`bootstrap` function.\n\n```javascript\n'use strict'\nconst middlewares = require('mu-koan');\nconst winston = require('winston');\nconst Koa = require('koa');\n\n// Configure a winston logger\nwinston.loggers.add('some-logger', {\n  console: {\n    level: 'silly',\n    colorize: true,\n    label: 'mu-koan'\n  }\n});\n\nlet app = new Koa();\n\n// `logger` option below can also be a `winston.Logger` instance or `undefined`/`null`\nconst server = middlewares.bootstrap(app, { logger: 'some-logger' });\n```\n\nActual logger configuration is not handled by mu-kōän. The option can be either a `String` or a `winston.Logger` instance. In the former case, the value will be used to fetch a logger by means of `winston.loggers.get(options.logger)`.\n\nIf none is provided, the _default_ `winston` logger will be used.\n\n\u003e Learn more about handling multiple loggers at [the official Winston docs](https://www.npmjs.com/package/winston#working-with-multiple-loggers-in-winston)\n\n## Features\nThe boilerplate adds support for the following to a barebones Koa app:\n\n- Body parsing ([koa-bodyparser](https://www.npmjs.com/package/koa-bodyparser))\n- Pretty JSON responses ([koa-json](https://www.npmjs.com/package/koa-json))\n- Global error handling ([koa-json-error](https://www.npmjs.com/package/koa-json-error))\n- Cache control ([koa-cache-control](https://www.npmjs.com/package/koa-cache-control))\n- Compression ([koa-compress](https://www.npmjs.com/package/koa-compress))\n- CORS ([kcors](https://www.npmjs.com/package/kcors))\n- ETag and conditional `GET` ([koa-etag](https://www.npmjs.com/package/koa-etag))\n- RTT headers ([koa-response-time](https://www.npmjs.com/package/koa-response-time))\n- Access logging ([koa-morgan](https://www.npmjs.com/package/koa-morgan)))\n- JWT authentication ([koa-jwt](https://www.npmjs.com/package/koa-jwt))\n- Favicon ([koa-favicon](https://www.npmjs.com/package/koa-favicon))\n- Security headers ([koa-helmet](https://www.npmjs.com/package/koa-helmet))\n\n\n---\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnfantone%2Fmu-koan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnfantone%2Fmu-koan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnfantone%2Fmu-koan/lists"}