{"id":20603352,"url":"https://github.com/metalsmith/js-bundle","last_synced_at":"2025-07-23T18:08:54.413Z","repository":{"id":44372072,"uuid":"502208317","full_name":"metalsmith/js-bundle","owner":"metalsmith","description":"A metalsmith plugin that bundles your JS using esbuild","archived":false,"fork":false,"pushed_at":"2025-02-19T21:14:39.000Z","size":2785,"stargazers_count":1,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-18T06:43:06.748Z","etag":null,"topics":["babel","bundling","esbuild","javascript","metalsmith","metalsmith-plugin"],"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/metalsmith.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2022-06-10T23:49:10.000Z","updated_at":"2025-02-19T21:14:43.000Z","dependencies_parsed_at":"2025-04-15T02:01:34.738Z","dependency_job_id":"e1724eb6-fe1b-4649-999c-024e748f65c4","html_url":"https://github.com/metalsmith/js-bundle","commit_stats":{"total_commits":19,"total_committers":3,"mean_commits":6.333333333333333,"dds":"0.10526315789473684","last_synced_commit":"72d50960ec1442729999383e50edbd8ebe7174b0"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":"metalsmith/core-plugin","purl":"pkg:github/metalsmith/js-bundle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fjs-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fjs-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fjs-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fjs-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metalsmith","download_url":"https://codeload.github.com/metalsmith/js-bundle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fjs-bundle/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265871591,"owners_count":23842052,"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":["babel","bundling","esbuild","javascript","metalsmith","metalsmith-plugin"],"created_at":"2024-11-16T09:17:02.327Z","updated_at":"2025-07-23T18:08:54.392Z","avatar_url":"https://github.com/metalsmith.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @metalsmith/js-bundle\n\nA metalsmith plugin that bundles your JS using [esbuild](https://esbuild.github.io) with sensible defaults (and [babel](https://babeljs.io) for ES5)\n\n[![metalsmith: core plugin][metalsmith-badge]][metalsmith-url]\n[![npm: version][npm-badge]][npm-url]\n[![ci: build][ci-badge]][ci-url]\n[![code coverage][codecov-badge]][codecov-url]\n[![license: MIT][license-badge]][license-url]\n\n## Features\n\n- Transpiles ESnext to ES6 with esbuild, and falls back on a Babel compatibility layer for ES5\n- Supports most ESbuild options including custom loaders and plugins\n- Available in CommonJS and ESM\n\n## Installation\n\nNPM:\n\n```\nnpm install @metalsmith/js-bundle\n```\n\nYarn:\n\n```\nyarn add @metalsmith/js-bundle\n```\n\n## Usage\n\nPass `@metalsmith/js-bundle` to `metalsmith.use` :\n\n```js\nimport jsBundle from '@metalsmith/js-bundle'\n\nmetalsmith.use(\n  jsBundle({\n    // defaults\n    entries: {\n      index: 'lib/index.js'\n    }\n  })\n)\n\nconst isProd = metalsmith.env('NODE_ENV') !== 'development'\nmetalsmith.use(\n  jsBundle({\n    // explicit defaults\n    bundle: true,\n    minify: isProd,\n    sourcemap: !isProd,\n    platform: 'browser',\n    target: 'es6',\n    assetNames: '[dir]/[name]',\n    // accessible as process.env.\u003cNAME\u003e in your JS files\n    define: metalsmith.env(),\n    // removes console \u0026 debugger statements\n    drop: isProd ? ['console', 'debugger'] : [],\n    entries: {\n      index: 'lib/index.js'\n    }\n  })\n)\n```\n\nThe key of the `entries` option determines the location of the processed file. For example `index: 'lib/index.js'` will result in `/index.js`, while `'/assets/index': 'lib/index.js'` will result in `/assets/index.js'.\n\nThe paths in the `entries` option should be relative to `metalsmith.directory()`.\n\n### Options\n\n`@metalsmith/js-bundle` provides access to most underlying [esbuild options](https://esbuild.github.io/api/#build-api), with a few notable differences:\n\nThe options `absWorkingDir` (=`metalsmith.directory()`), `outdir` (=`metalsmith.destination()`), `write` (=`false`), and `metafile` (=`true`) can not be set, they are determined by the plugin.\n\nThe option `entryPoints` is renamed to `entries`. Specify `entries` as a `{'target': 'path/to/source.js' }`} object, and mind that the target _should not have an extension_.\n\nThe option `define` is automatically filled with `metalsmith.env()`, but can be overwritten if desired. `metalsmith.env('DEBUG')` would be accessible in the bundle as `process.env.DEBUG`.\n\n### Loading assets\n\nYou can load assets with any of the [ESbuild loaders](https://esbuild.github.io/content-types/) by specifying a loader map. By default there is support for `.js`,`.ts`,`.css`,`.json`,`.jsx`,`.tsx`, and `.txt` loading. It's important to note 2 things:\n\n- assets loaded with any loader but the `file` loader will be \"embedded\" in the resulting JS bundle and removed from the build (=not available for other plugins), increasing bundle size.\n- if you would like to process assets loaded with the `file` loader with other metalsmith plugins (eg [metalsmith-imagemin](https://github.com/ahmadnassri/metalsmith-imagemin))\n  `@metalsmith/js-bundle` needs to be _run first_ and you should not overwrite the default [`assetNames` option](https://esbuild.github.io/api/#asset-names) `[dir]/[name]`.\n\nThe [file loader](https://esbuild.github.io/content-types/#external-file) is the loader you need for most large asset types you wouldn't want to bloat your JS bundle with.\nIf you want to use inline SVG's, you would set its loader to `text`, while if you prefer loading them in image tags, you could set them to `dataurl` (embedded) or `file` (external).\n\nThe [`publicPath` option](https://esbuild.github.io/api/#public-path) will prepend a path to each asset loaded with the `file` loader. This can be useful if you are serving the metalsmith build from a non-root URI.\n\n```js\nmetalsmith.use(\n  jsbundle({\n    entries: { index: 'src/index.js' },\n    loader: {\n      '.png': 'file',\n      '.svg': 'dataurl',\n      '.jpg': 'file', // this will be a relative URI\n      '.yaml': 'text' // this will be a parseable string\n    },\n    publicPath: metalsmith.env('NODE_ENV') === 'development' ? '' : 'https://johndoe.com'\n  })\n)\n```\n\n### ES5 transpilation support\n\nESbuild does not support compiling to ES5 (ie. supporting IE 11 and some older mobile browsers).\nNevertheless you can specify the `target: 'es5'` option and `@metalsmith/js-bundle` will let ESbuild handle bundling and fall back on Babel to provide a compatibility layer. The side effects of this are a slower and bigger build and currently, no support for source maps. However, you can make the target depend on an environment variable and enjoy sourcemaps in development, eg:\n\n```js\nconst isDev = process.env.NODE_ENV === 'development'\n\nmetalsmith.use(\n  jsbundle({\n    entries: { index: 'src/index.js' },\n    target: isDev ? 'es6' : 'es5'\n  })\n)\n```\n\nAt the moment, passing options to Babel is not supported. A Babel production build will have basic minification, but without further (mangling) optimizations. You could choose to use [metalsmith-uglifyjs](https://github.com/ubenzer/metalsmith-uglifyjs) to further optimize it.\n\nAlternatively you could run `@metalsmith/jsbundle` twice, 1 with target es5, and 1 with higher, and decide with an inline script at run-time which bundle to inject.\n\n### Debug\n\nTo enable debug logs, set `metalsmith.env('DEBUG', '@metalsmith/js-bundle*')` or in `metalsmith.json`: `\"env\": { \"DEBUG\": \"@metalsmith/js-bundle*\" }`.\nYou can also pass the live environment variable by running `metalsmith.env('DEBUG', process.env.DEBUG)` or in `metalsmith.json`: `\"env\": { \"DEBUG\": \"$DEBUG\" }`\n\nAlternatively you can set `DEBUG` to `@metalsmith/*` to debug all Metalsmith core plugins.\n\n### CLI usage\n\nTo use this plugin with the Metalsmith CLI, add `@metalsmith/js-bundle` to the `plugins` key in your `metalsmith.json` file:\n\n```json\n{\n  \"plugins\": [\n    {\n      \"@metalsmith/js-bundle\": {\n        \"entries\": {\n          \"app\": \"lib/main.js\"\n        }\n      }\n    }\n  ]\n}\n```\n\n## License\n\n[MIT](LICENSE)\n\n[npm-badge]: https://img.shields.io/npm/v/@metalsmith/js-bundle.svg\n[npm-url]: https://www.npmjs.com/package/@metalsmith/js-bundle\n[ci-badge]: https://github.com/metalsmith/js-bundle/actions/workflows/test.yml/badge.svg\n[ci-url]: https://github.com/metalsmith/js-bundle/actions/workflows/test.yml\n[metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true\n[metalsmith-url]: https://metalsmith.io\n[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/js-bundle\n[codecov-url]: https://coveralls.io/github/metalsmith/js-bundle\n[license-badge]: https://img.shields.io/github/license/metalsmith/js-bundle\n[license-url]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fjs-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetalsmith%2Fjs-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fjs-bundle/lists"}