{"id":37599904,"url":"https://github.com/cdklabs/node-backpack","last_synced_at":"2026-05-04T20:02:04.332Z","repository":{"id":37022348,"uuid":"479962550","full_name":"cdklabs/node-backpack","owner":"cdklabs","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-12T22:05:29.000Z","size":3805,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":14,"default_branch":"main","last_synced_at":"2026-01-12T23:51:10.533Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cdklabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-10T08:53:01.000Z","updated_at":"2026-01-12T22:05:32.000Z","dependencies_parsed_at":"2023-09-24T02:07:02.857Z","dependency_job_id":"4e23adb0-69a4-4051-9108-6b7cc3b2511d","html_url":"https://github.com/cdklabs/node-backpack","commit_stats":null,"previous_names":[],"tags_count":580,"template":false,"template_full_name":"amazon-archives/__template_Apache-2.0","purl":"pkg:github/cdklabs/node-backpack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fnode-backpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fnode-backpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fnode-backpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fnode-backpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cdklabs","download_url":"https://codeload.github.com/cdklabs/node-backpack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cdklabs%2Fnode-backpack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-16T10:01:47.420Z","updated_at":"2026-05-04T20:02:04.327Z","avatar_url":"https://github.com/cdklabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-bundle\n\n\u003e **NOTE:** This tool should only be used on packages in this repository,\n\u003e and is not intended for external usage.\n\nYou can use this tool to help create bundled packages with minimal dependencies and appropriate license attributions.\n\n## Why\n\nWhen shipping nodejs applications, there is currently no easy way to ensure your users are\nconsuming the exact dependency closure your package was tested against.\n\nThis is because many libraries define their dependencies with a range, rather than a fixed version.\nNPM has provided an install time lock file called [shrinkwrap](https://docs.npmjs.com/cli/v8/commands/npm-shrinkwrap)\nto help mitigate this, however, this file is only respected by NPM itself, and not by other package managers such as Yarn.\n\n## What\n\nThis package wires up several popular tools to offer a simpler entrypoint for\ncreating self-contained nodejs packages.\n\nThe resulting packages are still npm installable packages, but you can use this tool to\nreplace the entrypoints you specify with a bundled version of them, embedding their dependencies inline.\nNote that embedding dependencies means you are effectively redistributing third-party software.\nThis could have licensing implications, and it is your responsibility to provide proper\nand typically requires proper attribution of the bundled dependencies,\nwhile validating their licenses allow such redistribution.\n\nYou can use this tool to help achieve the following tasks:\n\n- Bundle the entrypoints inside the package.\n\n  \u003e Currently done with [esbuild](https://esbuild.github.io), but is subject to change.\n\n- Validate and create THIRD_PARTY_LICENCES file with third-party attributions for packages with declared licensing information.\n\n  \u003e Currently done with [license-checker](https://www.npmjs.com/package/license-checker), but is subject to change.\n\n- Detect circular imports that are exhibited in your package, or in your dependency closure.\n\n  \u003e Currently done with [madge](https://www.npmjs.com/package/madge), but is subject to change.\n  \u003e This is necessary because circular imports mess up the declaration order of types in the bundled file.\n\n### Disclaimer\n\nFeatures of this package rely on the dependencies' declared licensing information, and the fulsomeness of\nthe generated attribution is dependent on the dependencies’ declarations.\nThis tool is not a substitute for your code attribution processes, but you can use it to help\nstreamline attribution items for dependencies that have license declarations.\nThe user of this package remains responsible for complying to their dependencies' licensing requirements,\nincluding any attribution obligations.\n\nWe strongly recommend that you check all of your code into source control, and follow your ordinary code attribution processes.\n\n## Alternative Approaches\n\nWe considered two other alternatives before eventually going down this route:\n\n### Bundled Dependencies\n\nAside from a shrinkwrap file, NPM also offers a feature called `bundledDependencies`\nto vendor in your dependencies inside the `node_modules` directory of your package.\n\n\u003e See [bundledDependencies](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#bundledependencies)\n\nWhile this approach seems to be supported across all package managers, that won't be\nthe case for Yarn 2.x and above, or more concretely,\nfor the [Plug'n'Play](https://yarnpkg.com/features/pnp) feature.\n\n\u003e See [dont use bundled dependencies](https://yarnpkg.com/migration/guide#dont-use-bundledependencies)\n\n### Static Binaries\n\nAnother option would have been to produce platform specific static binaries that embed both\ndependencies as well as a node runtime.\n\nThis approach is valid, but really depends on the use case. For example if you need your package\nto still be installable by npm, it doesn't really fit. Also, it's not relevant for libraries,\nonly CLI applications.\n\n## How\n\nRun the tool from the root directory of your package.\n\n```console\n$ node-bundle --help\nUsage: node-bundle COMMAND\n\nCommands:\n  node-bundle validate  Validate the package is ready for bundling\n  node-bundle write     Write the bundled version of the project to a temp\n                        directory\n  node-bundle pack      Write the bundle and create the tarball\n\nOptions:\n  --entrypoint       List of entrypoints to bundle                       [array]\n  --external         Packages in this list will be excluded from the bundle and\n                     added as dependencies (example: fsevents:optional)\n                                                           [array] [default: []]\n  --allowed-license  List of valid licenses                [array] [default: []]\n  --resource         List of resources that need to be explicitly copied to the\n                     bundle (example:\n                     node_modules/proxy-agent/contextify.js:bin/contextify.js)\n                                                           [array] [default: []]\n  --dont-attribute   Dependencies matching this regular expressions wont be\n                     added to the notice file                           [string]\n  --test             Validation command to sanity test the bundle after its\n                     created                                            [string]\n  --help             Show help                                         [boolean]\n  --version          Show version number                               [boolean]\n```\n\nYou can also use the programmatic access:\n\n```ts\nimport { Bundle } from '@aws-cdk/node-bundle';\n\nconst bundle = new Bundle({\n  packageDir: process.cwd(),\n  allowedLicenses: ['Apache-2.0', 'MIT'],\n});\n\nbundle.pack();\n```\n\n### Integrate with your build process\n\nWe recommend to integrate this tool in the following way:\n\n1. Add a `node-bundle validate` command as a post compile step.\n2. Set your packaging command to `node-bundle pack`.\n\nThis way, you can validate local dev builds not to break any functionality needed for bundling.\nIn addition, developers can run `node-bundle validate --fix` to automatically fix any (fixable) violations\nand commit that to source control.\n\nFor example, if a dependency is added but the attribution file has not been re-generated,\nyou can use `node-bundle validate` to catch this, and regenerate it with `node-bundle validate --fix`.\n\n## Take into account\n\nBy default, the tool will use the `main` directive of the `package.json` as\nthe entrypoint. This will help you ensure that all top level exports of the\npackage are preserved.\n\nDeep imports such as `const plugins = require('your-package/lib/plugins')` are considered\nprivate and should not be used by your consumers. However, if you absolutely have to\npreserve those as well, you should pass custom multiple entry-points for each deep import.\nNote that this will balloon up the package size significantly.\n\nIf you are bundling a CLI application that also has top level exports, we suggest to extract\nthe CLI functionality into a function, and add this function as an export to `index.js`.\n\n\u003e See [aws-cdk](https://github.com/aws/aws-cdk-cli/blob/main/packages/aws-cdk/bin/cdk) as an example.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdklabs%2Fnode-backpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcdklabs%2Fnode-backpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcdklabs%2Fnode-backpack/lists"}