{"id":20740163,"url":"https://github.com/bjorntheprogrammer/bun-plugin-html","last_synced_at":"2026-03-07T09:03:45.799Z","repository":{"id":195552466,"uuid":"693191864","full_name":"BjornTheProgrammer/bun-plugin-html","owner":"BjornTheProgrammer","description":"A plugin for bun build which allows html entrypoints","archived":false,"fork":false,"pushed_at":"2025-01-18T11:05:14.000Z","size":7325,"stargazers_count":45,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-20T15:57:35.129Z","etag":null,"topics":[],"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/BjornTheProgrammer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2023-09-18T14:29:04.000Z","updated_at":"2025-06-19T08:46:10.000Z","dependencies_parsed_at":"2023-09-18T17:59:08.690Z","dependency_job_id":"8c8690bd-b7f5-4e9d-b109-195055aa41fe","html_url":"https://github.com/BjornTheProgrammer/bun-plugin-html","commit_stats":null,"previous_names":["bjorntheprogrammer/bun-plugin-html"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/BjornTheProgrammer/bun-plugin-html","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornTheProgrammer%2Fbun-plugin-html","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornTheProgrammer%2Fbun-plugin-html/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornTheProgrammer%2Fbun-plugin-html/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornTheProgrammer%2Fbun-plugin-html/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BjornTheProgrammer","download_url":"https://codeload.github.com/BjornTheProgrammer/bun-plugin-html/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjornTheProgrammer%2Fbun-plugin-html/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30210377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"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":"2024-11-17T06:27:36.436Z","updated_at":"2026-03-07T09:03:45.761Z","avatar_url":"https://github.com/BjornTheProgrammer.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bun Plugin for HTML\n\nThe `bun-plugin-html` is a plugin for the Bun build tool that enables `.html` file entrypoints. This document instructions on how to install, use, and configure the plugin.\n\n\u003e [!IMPORTANT]\n\u003e With bun v1.2 the html loader will be [stabilized](https://github.com/oven-sh/bun/issues/4688). This plugin will still be updated if any issues occur,\n\u003e but it is recommended that you use the built-in loader.\n\n## Installation\n\nYou can install `bun-plugin-html` using the following command:\n\n```bash\nbun add -d bun-plugin-html\n```\n\nEnsure Bun is upgraded to `v1.1.34`, as a bug fix was introduced in this version of Bun.\n\n## Usage\n\nTo use this plugin, import it into your code and add it to the list of plugins when building your project with Bun. Here's an example:\n\n```typescript\nimport html from 'bun-plugin-html';\n\nawait Bun.build({\n    entrypoints: ['./src/index.html', './src/other.html'],\n    outdir: './dist',  // Specify the output directory\n    plugins: [\n        html()\n    ],\n});\n```\n\nThis code snippet builds HTML files from the specified entrypoints and places them in the specified output directory, along with their associated scripts and links.\n\n### Input\n\nHere is an example of an HTML file (`index.html`) that serves as an input:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\"\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1\"\u003e\n    \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"main.css\"\u003e\n    \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"./style.scss\" /\u003e\n    \u003clink rel=\"icon\" type=\"image/x-icon\" href=\"./images/favicon.ico\"\u003e\n    \u003ctitle\u003eHello World!\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eHello World\u003c/h1\u003e\n    \u003cp id=\"js-target\"\u003eThis should be changed by JS\u003c/p\u003e\n    \u003cscript src=\"main.ts\"\u003e\u003c/script\u003e\n    \u003cscript src=\"./js/secondary.ts\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\nAlong with a file structure like the one below, the plugin generates the output as described:\n\n```\n.\n└── src/\n    ├── index.html\n    ├── main.css\n    ├── style.scss\n    ├── main.ts\n    ├── js/\n    │   └── secondary.ts\n    └── images/\n        └── favicon.ico\n```\n\n### Output\n\nThe plugin generates the output in the specified output directory. If certain files are missing, the console will indicate the issue while generating the rest of the files. The generated output would look like this:\n\n```\n.\n└── src/\n    └── ...\n└── dist/\n    ├── index.html\n    ├── main.css\n    ├── style.scss\n    ├── main.js\n    ├── js/\n    │   └── secondary.js\n    └── images/\n        └── favicon.ico\n```\n\nHere's the transformed HTML file in the output directory (`dist/index.html`):\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\"\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1\"\u003e\n    \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"main.css\"\u003e\n    \u003clink rel=\"icon\" type=\"image/x-icon\" href=\"./images/favicon.ico\"\u003e\n    \u003ctitle\u003eHello World!\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eHello World\u003c/h1\u003e\n    \u003cp id=\"js-target\"\u003eThis should be changed by JS\u003c/p\u003e\n    \u003cscript src=\"main.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"./js/secondary.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\nNote that `sass` and `scss` files are transpiled by default.\n\n## Configuration Options\n\nYou can customize the behavior of the `bun-plugin-html` by providing options. Here's the available configuration:\n\n```typescript\ntype BunPluginHTMLOptions = {\n    inline?: boolean | {\n        css?: boolean;\n        js?: boolean;\n    };\n    naming?: {\n        css?: string;\n    };\n    minifyOptions?: HTMLTerserOptions;\n    includeExtensions?: string[];\n    excludeExtensions?: string[];\n    excludeSelectors?: string[];\n    preprocessor?: (processor: Processor) =\u003e void | Promise\u003cvoid\u003e;\n    keepOriginalPaths?: boolean | string[];\n};\n```\n\n### Inline Option\n\nBy setting the `inline` option to `true`, you can choose to inline CSS and/or JS files within your HTML. Here's an example:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"utf-8\"\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1\"\u003e\n    \u003cstyle\u003e\n        body {\n            background-color: #000;\n            color: #fff;\n        }\n    \u003c/style\u003e\n    \u003clink rel=\"icon\" type=\"image/x-icon\" href=\"./images/favicon.ico\"\u003e\n    \u003ctitle\u003eHello World!\u003c/title\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003ch1\u003eHello World\u003c/h1\u003e\n    \u003cp id=\"js-target\"\u003eThis should be changed by JS\u003c/p\u003e\n    \u003cscript\u003e\n        // Content of main.ts\n        console.log(\"Running JS for browser\");\n        document.querySelector(\"#js-target\").innerHTML = \"Changed!\";\n    \u003c/script\u003e\n    \u003cscript\u003e\n        // Content of js/secondary.ts\n        console.log(\"in secondary.ts\");\n    \u003c/script\u003e\n\u003c/body\u003e\n```\n\n### MinifyOptions Option\n\nUse `minifyOptions` to configure [`html-minifier-terser`](https://github.com/terser/html-minifier-terser?tab=readme-ov-file#options-quick-reference).\n\nThe `minifyCSS` and `minifyJS` fields enable further configuration of\n[`clean-css`](https://github.com/clean-css/clean-css?tab=readme-ov-file#constructor-options) and\n[`terser`](https://github.com/terser/terser?tab=readme-ov-file#minify-options), respectively.\nAdditionally minifyHTML is an added option, which can be disabled to skip html minification.\n\nThe following default options are exported as `defaultMinifyOptions`:\n```ts\n{\n    collapseWhitespace: true,\n    collapseInlineTagWhitespace: true,\n    caseSensitive: true,\n    minifyCSS: {},\n    minifyJS: true,\n    minifyHTML: true,\n    removeComments: true,\n    removeRedundantAttributes: true,\n}\n```\n\n`minifyCSS` and `minifyJS` can both be set to either `true`, `false`, a configuration object, or a callback function.\n`minifyHTML` can only be set to either `true`, `false`. The different\nvalues of `minifyCSS` and `minifyJS` behave as follows:\n\n#### MinifyCSS\n\n| Value                                      | Result                      |\n|--------------------------------------------|-----------------------------|\n| `false`                                    | CSS minification is skipped |\n| `true` or `undefined`                      | CSS minification is performed with default options using `clean-css` |\n| `{ opts } `                                | CSS minification is performed with the provided options using `clean-css` |\n| `((text: string, type: string) =\u003e string)` | Your function is called for every CSS element encountered and should return minified content. |\n\n\n#### MinifyJS\n\n| Value                                        | Result                      |\n|----------------------------------------------|-----------------------------|\n| `false`                                      | JS minification is skipped |\n| `true` or `undefined`                        | JS minification is performed by `Bun.build` and inlined scripts will also be processed with default options using `terser` |\n| `{ opts } `                                  | JS minification is performed with the provided options using `terser`. No minification is performed by `Bun.build` |\n| `((text: string, inline: boolean) =\u003e string)`| Your function is called for every JS element encoutered and should return minified content. |\n\n#### MinifyHTML\n\n| Value                                        | Result                      |\n|----------------------------------------------|-----------------------------|\n| `false`                                      | HTML minification is skipped |\n| `true` or `undefined`                        | HTML minification is performed by `terser`|\n\nAn important consideration when using the `minifyHTML` option, is that it will skip minification done by the terser completely.\nThis includes any originally inlined scripts and css. They will still be minified with `clean-css` and `Bun.build` when imported.\n\n### IncludeExtensions Option\n\nThe `includeExtensions` option takes an array of strings. Any files whose extensions match any of those strings will be passed to\n`Bun.build` (in addition to `['.js', '.jsx', '.ts', '.tsx']`).\n\n**Note: you must ensure an appropriate plugin is included for each file extension.**\n\n### ExcludeExtensions Option\n\nThe `excludeExtensions` option takes an array of strings. Any files whose extensions match any of those strings will be ignored by\nthe plugin.\n\nThe extension name follows the same format as the [path.extname](https://nodejs.org/api/path.html#pathextnamepath) return.\n\n### ExcludeSelectors Option\n\nThe `excludeSelectors` option takes an array of strings. Any HTML elements matched by a selector will be ignored by the plugin.\n\n### Naming Option\n\nThe `naming` option takes in an optional template to name css files with. By default css files follow the `chunk` naming [rules](https://bun.sh/docs/bundler#naming). This overrides that default behavior, following the same syntax.\n\nThe example below shows spliting the js, assets, and css into different directories.\n```ts\nawait Bun.build({\n    entrypoints: ['index.html'],\n    outdir: 'dist',\n    naming: {\n        chunk: 'js/[dir]/[name]-[hash].[ext]',\n        asset: 'assets/[name].[ext]',\n        entry: 'main.html'\n    },\n    plugins: [html({\n        naming: {\n            css: 'css/[name].[ext]'\n        }\n    })],\n})\n```\n\n### Preprocessor Option\n\nThe `preprocessor` option takes in a funciton which will be provided a `Processor` class, in which you can modify the files provided to it, before they are processed by `bun-plugin-html`.\n\nThe example below shows processing the css files with tailwind. By default `sass` is transpiled.\n```ts\nawait Bun.build({\n    entrypoints: ['src/index.html'],\n    outdir: 'dist',\n    minify: true,\n    plugins: [html({\n        async preprocessor(processor) {\n            const files = processor.getFiles();\n\n            for (const file of files) {\n                if (file.extension == '.css') {\n                    const contents = await $`bun run tailwindcss -i ${file.path} --content 'src/**/*.{html,js,ts}'`.quiet().text();\n                    processor.writeFile(file.path, contents);\n                }\n            }\n\n            // Add hello.txt to the out dir.\n            // The path provided to writeFile must be an absolute path.\n            processor.writeFile(path.resolve('src/hello.txt'), 'Hello World!')\n        },\n    })]\n})\n```\n\n### Keep Original Paths Option\n\nDetermines whether file paths in the source code are replaced by new paths.\n| Value                                     | Result                      |\n|-------------------------------------------|-----------------------------|\n| `true`                                    | Path replacement is completely skipped. |\n| `string[]`                                | Only the specified file paths are excluded from replacement. |\n| `false` or `undefined`                    | All paths are replaced within the source code. |\n\n### Suppress Errors\nDetermines whether errors are supressed. Default is false.\n\n## License\n\nThis plugin is licensed under MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjorntheprogrammer%2Fbun-plugin-html","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjorntheprogrammer%2Fbun-plugin-html","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjorntheprogrammer%2Fbun-plugin-html/lists"}