{"id":20597063,"url":"https://github.com/tradle/lambda-plugins","last_synced_at":"2026-05-26T13:40:30.621Z","repository":{"id":42018303,"uuid":"457643595","full_name":"tradle/lambda-plugins","owner":"tradle","description":"Loader for additional npm packages based on configuration in lamdba function.","archived":false,"fork":false,"pushed_at":"2022-04-29T04:58:06.000Z","size":310,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-01-17T00:53:11.348Z","etag":null,"topics":["lambda-functions","serverless"],"latest_commit_sha":null,"homepage":"","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/tradle.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":"2022-02-10T05:31:14.000Z","updated_at":"2022-02-18T15:01:43.000Z","dependencies_parsed_at":"2022-08-12T02:31:08.939Z","dependency_job_id":null,"html_url":"https://github.com/tradle/lambda-plugins","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradle%2Flambda-plugins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradle%2Flambda-plugins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradle%2Flambda-plugins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tradle%2Flambda-plugins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tradle","download_url":"https://codeload.github.com/tradle/lambda-plugins/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242231440,"owners_count":20093636,"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":["lambda-functions","serverless"],"created_at":"2024-11-16T08:20:05.839Z","updated_at":"2026-05-26T13:40:30.575Z","avatar_url":"https://github.com/tradle.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @tradle/lambda-plugins\n\nLoader for additional npm packages based on configuration in lamdba function.\n\n## How it works\n\nGiven a **list of npm packages** to load, this script will use npm install to\ninstall the packages in the temporary directory and provide an accessor to the plugins to load.\n\n## Usage with serverless\n\nIn this example we load the plugins from the envionment variable `PLUGINS` defined\nin the lambda settings. In your project you can load definitions from DynamoDB/S3/etc.\n\n```js\nimport { loadPlugins } from '@tradle/lambda-plugins'\n\nexport async function example (event) {\n  const plugins = await loadPlugins(\n    JSON.parse(process.env.PLUGINS ?? '{}')\n  )\n\n  for (const pluginName in plugins) {\n    const plugin = plugins[pluginName]\n    plugin.name === pluginName\n    plugin.path // File path where the package is loaded from\n    await plugin.package() // Loads the package.json for the package\n    await plugin.data() // Loads the data\n  }\n\n  // ... the rest of your lambda code.\n}\n```\n\nIn this example the [npm packages][] are separated by a ` `, examples could be:\n\n- `PLUGINS={}` ... to load nothing\n- `PLUGINS={\"moment\":\"2.29.1\"}` ... to load the [`moment`][] package.\n- `PLUGINS={\"moment\":\"2.29.1\", \"lodash\":\"4.17.17\"}` ... to load both the `moment` and\n    the [`lodash`][] package.\n- `PLUGINS={\"moment\":\"https://github.com/lodash/lodash/archive/refs/tags/4.0.0.tar.gz\"}`\n    ... to load the _(old)_ `lodash` package via https.\n- `PLUGINS={\"quick-lru\":\"github:sindresorhus/quick-lru#771392878fc0e2325b1172d04260e87afe94c8f7\"}`\n    ... to load the `quick-lru` package directly from github.\n- `PLUGINS={\"moment\":\"s3://private-bucket/lodash-4.0.0.tar.gz\"}` ... to load the `lodash`\n    package from a secret, _ficitional_ s3 bucket.\n\netc.\n\n[moment]: https://npmjs.com/package/moment\n[lodash]: https://npmjs.com/package/lodash\n[quick-lru]: https://github.com/sindresorhus/quick-lru\n[npm packages]: https://docs.npmjs.com/cli/v7/commands/npm-install#description\n\n## S3 Bucket loading\n\nYou can publish private packages to s3. These s3 packages get downloaded directly,\nbypassing npm. In order for this to work you need to make sure that the lambda\nhas permission to access this bucket:\n\n```yml\n- Effect: 'Allow'\n  Action:\n    - \"s3:GetObject\"\n  Resource:\n    'arn:aws:s3:::private-bucket/*'\n```\n\n## Options\n\nBy default it will install the packages in the `/tmp` folder. You can override\nthis by using the `{ tmpDir }` option:\n\n```js\nawait loadPlugins(plugins, { tmpDir: '/other/tmp/dir' })\n```\n\nThe `/tmp` folder persists between requests and every time `loadPlugins` is called,\nit checks the timestamp of the previous run and only checks if new plugins need to\nbe installed if the last run was more than 2 minutes ago. You can override this by\nusing the `{ maxAge: 1000 }` option:\n\n```js\nawait loadPlugins(plugins, { maxAge: 1000 })\n```\n\nBy default the loading of plugins does not allow loose semver-version definitions.\nVersions installed using semvers like `~1.0.0` or `1` or `\u003e=1` are not allowed.\nIf you still want to use these, you need to pass the `strict = false` option.\n\n```js\nawait loadPlugins(plugins, { strict: false })\n```\n\nBy default there will be also no error if the installation of the plugins happens\nto fail. In order to enable errors you need to pass `failQuietly=false`.\n\n```js\nawait loadPlugins(plugins, { failQuietyl: false })\n```\n\nTo install private packages you will need to specify an authentication token.\n\n```js\nawait loadPlugins(plugins, { registryTokens: { 'host': 'token' } })\n```\n\nIn practice it may look like:\n\n```js\nawait loadPlugins(plugins, { registryTokens: { \"registry.npmjs.org/\": \"npm_Fo2387C3auJep6agQr41NCDHXW2BDz1S07mf\" } } )\n```\n\nDepending on the registry, there are different ways to get a token. Here is the\ndocumentation for \n\n- [npm access token](https://docs.npmjs.com/creating-and-viewing-access-tokens)\n- [github registry token](https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages#authenticating-to-the-destination-repository)\n\n## Flow\n\nHere is a flow explanation:\n\n```\n[request]\n→ does /tmp/plugins exist?\n Yes → was updated within the last 2 minutes?\n |  Yes → start\n |  No  → is /tmp/plugins is up-to-date?\n |     Yes → start\n |     No -\\  \n |         |→ load plugins\n |         \\→ start\n No -\\\n     |→ load plugins\n     \\→ start\n```\n\nFurthermore, this package uses `debug` and by adding the `DEBUG=*` environment\nvariable you can get insight on what happens.\n\n## Development\n\nThe code here uses a pretty straightforward development model. The only thing that may not be\nobvious is the example code in `sls-aws-example`. In order for that to work, we need do releases\nmanually. When you do a release:\n\n1. Change the version number in the [package.json](./package.json)\n2. In the `sls-aws-example` change the dependency to the same version as in the `package.json`.\n3. Run `npm i` in the `sls-aws-example`.\n4. Now add all files necessary should be prepared for the git commit.\n\nNaturally when doing changes on this repo you should provide tests and expand on the example.\nTo test the changes you have made with the example, run the `npm run update-parent` command\nin the `sls-aws-example` before deploying it to AWS.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftradle%2Flambda-plugins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftradle%2Flambda-plugins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftradle%2Flambda-plugins/lists"}