{"id":16758511,"url":"https://github.com/kessler/pluggage","last_synced_at":"2025-06-22T22:39:42.517Z","repository":{"id":26598460,"uuid":"109315483","full_name":"kessler/pluggage","owner":"kessler","description":"A very slim framework for building pluggable code.","archived":false,"fork":false,"pushed_at":"2024-06-16T11:46:10.000Z","size":491,"stargazers_count":18,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T08:09:25.541Z","etag":null,"topics":["nodejs"],"latest_commit_sha":null,"homepage":null,"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/kessler.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,"publiccode":null,"codemeta":null}},"created_at":"2017-11-02T20:29:02.000Z","updated_at":"2023-12-10T15:06:14.000Z","dependencies_parsed_at":"2024-10-28T11:39:12.458Z","dependency_job_id":"64b49367-3419-49c6-b91e-8db87defa6bd","html_url":"https://github.com/kessler/pluggage","commit_stats":{"total_commits":41,"total_committers":2,"mean_commits":20.5,"dds":"0.19512195121951215","last_synced_commit":"1a2ed39c4edb861c8082acd05596784f5dce7a37"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fpluggage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fpluggage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fpluggage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kessler%2Fpluggage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kessler","download_url":"https://codeload.github.com/kessler/pluggage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244885175,"owners_count":20526282,"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":["nodejs"],"created_at":"2024-10-13T04:05:34.257Z","updated_at":"2025-03-21T23:31:51.833Z","avatar_url":"https://github.com/kessler.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pluggage\r\n\r\n[![npm status](http://img.shields.io/npm/v/pluggage.svg?style=flat-square)](https://www.npmjs.org/package/pluggage)\r\n\r\n**A very slim framework for building pluggable code.**\r\n\r\nIf you want to build an application or a framework that uses plugins for extensibility, you should take a look at pluggage. Pluggage takes care of discovery and lifecycle management of the plugins. Beyond that, pluggage imposes very little on the interaction between plugin and host.\r\n\r\n_`Pluggage` is a combination of `plugin` and `package`, but it also sounds a lot like `luggage`_\r\n\r\n## install\r\n\r\nWith [npm](https://npmjs.org) do:\r\n\r\n```\r\nnpm install --save pluggage\r\n```\r\n\r\n## host/load plugins in your code\r\n\r\nA plugin host manages discovery and lifecycle of plugins. It can also expose an api to them. To install a plugin simply `npm install your-plugin` in the host application.  This can be an npm package or local code installed as a package ([more on that here](LOCAL-CODE-PACKAGE.md))\r\n\r\nUsing `exact` or `prefix` in the `host(...)` options will make pluggage automatically load and initialize packages that were `npm` installed.\r\n\r\n```js\r\nconst pluggage = require('pluggage')\r\n\r\nasync function main() {\r\n    const hostApi = {\r\n        foo: () =\u003e {}\r\n    }\r\n\r\n    // load all plugins who's package name starts with `generator-``\r\n    const host = pluggage.host({ prefix: 'generator-', hostApi })\r\n\r\n    // initialize the plugins\r\n    await host.init()\r\n    await host.shutdown()\r\n\r\n    // load the plugins who's package name exactly match the names specified in the array\r\n    const exactHost = pluggage.host({ exact: ['plugin1', 'plugin2'], hostApi })\r\n}\r\n\r\nmain()\r\n\r\n```\r\n\r\n## Creating a plugin\r\n\r\nA plugin is just a package that exports the `pluggage` interface (using the `pluggage` property). \r\n\r\n```js\r\nconst pluggage = require('pluggage')\r\n\r\nmodule.exports.pluggage = pluggage.plugin({\r\n   init:  async (hostApi) =\u003e {},\r\n   shutdown: async () =\u003e {}\r\n})\r\n```\r\n\r\n#### IMPORTANT: Installing the package in a plugin module\r\nDoing `npm i pluggage` for this scenario is not a good idea. It will cause the host and the plugin to have different instances of what's suppose to be the same class. You're welcome to read more about this kind of problem [here](https://nodejs.org/en/blog/npm/peer-dependencies/#the-problem-plugins).\r\n\r\nWhen developing the pluing module separately (ie not as a local package - [discussed here](LOCAL-CODE-PACKAGE.md)) you should have it as both `dev` and `peer` depedency:\r\n```json\r\n{\r\n    \"peerDependencies\": {\r\n        \"pluggage\": \"1.x\"\r\n    },\r\n    \"devDependencies\": {\r\n        \"pluggage\": \"x.y.z\"\r\n    }\r\n}\r\n```\r\n\r\nlocal packages do not need the _devDepenendencies_.\r\n\r\nThis is a little awkward, and maybe there's a better solution... please share it if you have one.\r\n\r\n## license\r\n\r\n[MIT](http://opensource.org/licenses/MIT) © Yaniv Kessler\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkessler%2Fpluggage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkessler%2Fpluggage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkessler%2Fpluggage/lists"}