{"id":48959827,"url":"https://github.com/mindon/biu","last_synced_at":"2026-05-19T07:16:20.020Z","repository":{"id":351256016,"uuid":"1210223590","full_name":"mindon/biu","owner":"mindon","description":"a zero-config, high-performance bundler for HTML files with TypeScript/JavaScript, powered by Bun. It handles module splitting with custom import suffixes and provides built-in minification for HTML, CSS, and JS.","archived":false,"fork":false,"pushed_at":"2026-04-20T10:09:27.000Z","size":192,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-20T12:42:32.981Z","etag":null,"topics":["bun","bundler","typescript","webcomponents"],"latest_commit_sha":null,"homepage":"https://mindon.dev","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/mindon.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T07:50:01.000Z","updated_at":"2026-04-20T10:08:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mindon/biu","commit_stats":null,"previous_names":["mindon/biu"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mindon/biu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindon%2Fbiu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindon%2Fbiu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindon%2Fbiu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindon%2Fbiu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mindon","download_url":"https://codeload.github.com/mindon/biu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mindon%2Fbiu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32208477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["bun","bundler","typescript","webcomponents"],"created_at":"2026-04-18T01:14:44.598Z","updated_at":"2026-05-19T07:16:20.008Z","avatar_url":"https://github.com/mindon.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# biu\n\n`biu` is a zero-config, high-performance bundler for HTML files with\nTypeScript/JavaScript, powered by [Bun](https://bun.sh/). It handles module\nsplitting with custom import suffixes and provides built-in minification for\nHTML, CSS, and JS.\n\nProject repository \u003chttps://github.com/mindon/biu\u003e\n\nEasy to use, just art run `biu --serve` within a directory with a **src/**\ncontaining your HTML and TS/JS files, biu take care of everything else. (default\npreview on \u003chttp://localhost:3000\u003e )\n\nThe oututput directory **./dist** is all static html and JS files ready for\ndeployment.\n\n## Features\n\n- **Zero-config**: Automatically scans and bundles your project.\n- **Smart Module Splitting**: TS/JS files whose basename appears in any HTML are\n  built as independent modules; others are automatically inlined.\n- **Force Inline (`??`)**: Use the `??` import suffix to force inline bundling.\n- **Minification**: Built-in minification for HTML, CSS/SCSS, and\n  TypeScript/JavaScript (including HTML template literals).\n- **Content Hashing**: Output filenames include content hash for cache busting.\n- **Static Directory**: Copy unprocessed static assets directly to the output.\n- **Watch Mode**: Live rebuilds on file changes with debounce.\n- **Dev Server**: Built-in static file server with SPA fallback.\n- **Dependency Management**: Auto-install, interactive confirm, or record-only\n  modes for npm dependencies (`--depends`).\n- **Post-build Scripts**: Run custom `.sh`/`.ts`/`.js` scripts after each build.\n- **Self-compile**: Build a standalone binary with a single command.\n- **Fast**: Built on the lightning-fast Bun runtime.\n\n## Project Structure\n\n```\nbiu.ts                          ← Main entry (~95 lines), orchestrates all modules\nsrc/\n├── constants.ts                ← Version, USAGE, extension sets, env vars\n├── utils.ts                    ← Utilities (contentHash, recursive scan)\n├── cli.ts                      ← CLI argument parsing \u0026 DependsMode types\n├── deps.ts                     ← Dependency detection, install \u0026 record\n├── styles.ts                   ← CSS/SCSS compilation \u0026 minification\n├── assets.ts                   ← Static asset processing \u0026 copying\n├── plugins.ts                  ← Bun build plugins (base + main)\n├── html.ts                     ← HTML processing \u0026 minification\n├── builder.ts                  ← Core build logic (deps, modules, path rewriting)\n├── post-build.ts               ← Post-build script execution\n├── server.ts                   ← Watch mode \u0026 dev server\n├── *_test.ts                   ← Test files for each module\nplugins/\n└── minify-html-literals/       ← HTML template literal minifier (vendored)\ndemo-project/                   ← Example project for testing\n```\n\n### Module Dependencies (bottom-up)\n\n| Module       | Responsibility     | Dependencies                                          |\n| ------------ | ------------------ | ----------------------------------------------------- |\n| `constants`  | Constants \u0026 config | —                                                     |\n| `utils`      | Base utilities     | —                                                     |\n| `cli`        | Argument parsing   | constants                                             |\n| `styles`     | CSS processing     | utils                                                 |\n| `html`       | HTML processing    | styles                                                |\n| `assets`     | Asset processing   | utils                                                 |\n| `plugins`    | Build plugins      | minify-html-literals                                  |\n| `post-build` | Post-build scripts | —                                                     |\n| `server`     | Watch / Serve      | constants                                             |\n| `deps`       | Dependency mgmt    | cli                                                   |\n| `builder`    | Core build         | utils, constants, styles, assets, plugins, html, deps |\n| **`biu.ts`** | **Entry point**    | cli, constants, builder, assets, post-build, server   |\n\n## Installation \u0026 Compilation\n\nSince `biu` is built with Bun, you can compile it into a single executable\nbinary for portability.\n\n1. Ensure you have [Bun](https://bun.sh/) installed.\n2. Clone the repository and navigate to the directory.\n3. Prepare dependencies: `bun i`\n4. Compile with the built-in `--build` command:\n\n```bash\n# Self-compile to ./bin/biu (default)\nbun run biu.ts --build\n\n# Specify output path\nbun run biu.ts --build ./bin/biu\nbun run biu.ts --build /usr/local/bin/\n```\n\nBun's auto-install will fetch any missing dependencies automatically. The\nresulting binary is fully standalone.\n\n## Usage\n\nRun the `biu` binary or use `bun run` directly.\n\n### Command Syntax\n\n```bash\nbiu [src-dir] [out-dir] [--watch] [--static dir] [--serve port] [--depends mode] [--post-build file] [--build outfile]\n```\n\n- `src-dir`: The source directory (default: `./src`).\n- `out-dir`: The output directory (default: `./dist`).\n- `--watch`: Enable watch mode — rebuild on file changes.\n- `--static dir`: Specify a static assets directory to copy as-is into the\n  output (default: `./static`). If the directory exists, its contents are copied\n  before each build. In watch mode the static directory is also monitored.\n- `--depends [mode]`: Control how missing npm dependencies are handled (default:\n  `auto`). See [Dependency Management](#dependency-management) for details.\n- `--post-build \u003cfile\u003e`: Module `.ts`/`.js` or shell script to run after each\n  build. Receives the output directory as the first argument (`$1`).\n- `--serve [port]`: Start a static file server for the output directory on the\n  given port (default: `3000` when no port is specified). Implies `--watch`.\n- `--build [outfile]`: Self-compile `biu.ts` into a standalone binary at the\n  given path (default: `./biu`). Uses `bun build --compile --minify` under the\n  hood.\n- `-v, --version`: Show version info.\n- `-h, --help`: Show help / usage.\n\nOptions can appear in any order.\n\n### Examples\n\n**Basic build:**\n\n```bash\ncd demo-project\nbiu # Equivalent to default ./src and ./dist directories\n# biu ./src ./dist\n```\n\n**Watch mode:**\n\n```bash\nbiu --watch\n```\n\n**Dev server on port 8080:**\n\n```bash\n# biu --serve # default using 3000\nbiu --serve 8080\n```\n\n**Custom static directory + dev server:**\n\n```bash\nbiu --static ./public --serve 4000\n```\n\n**Post-build script:**\n\n```bash\nbiu --post-build ./scripts/deploy.sh\n```\n\n**Compile to binary and run:**\n\n```bash\n# From the biu repo\nbun run biu.ts --build bin/biu\nexport PATH=$PATH:`pwd`/bin\n\n# From a project directory\ncd demo-project\nbiu --serve 3000\n```\n\n**Install globally:**\n\n```bash\nbun run biu.ts --build /usr/local/bin/biu\n\ncd demo-project\nbiu --serve 3000\n```\n\n## Advanced Imports\n\n`biu` supports smart module splitting based on basename visibility in HTML:\n\n- **Independent module**: If a `.ts`/`.js` file's **basename** (e.g. `main.ts`)\n  appears anywhere in any HTML file's content, it is built as an **independent\n  module** with its own hashed output file.\n- **Auto inline**: If the basename never appears in any HTML, and the file is\n  imported by another `.ts`/`.js`, it is **automatically inlined** into its\n  importer — no separate output file is generated.\n- **Force inline (`??`)**: Use the `??` suffix to force a module to be bundled\n  inline regardless of whether its basename appears in HTML:\n  ```typescript\n  import { myUtil } from \"./utils.ts??\";\n  ```\n\nThis means you typically don't need to think about bundling strategy — files\nmentioned in HTML get their own output, and pure helper/utility modules are\nautomatically bundled into the files that use them.\n\n## Dependency Management\n\n`biu` automatically scans your source files for `import`/`require` statements\nand detects referenced npm packages. The `--depends` option controls what\nhappens next:\n\n| Mode               | Flag                        | Behavior                                                                             |\n| ------------------ | --------------------------- | ------------------------------------------------------------------------------------ |\n| **auto** (default) | `--depends=auto` or omitted | Detect missing packages and install them via `bun add`                               |\n| **confirm**        | `--depends=confirm`         | List missing packages, prompt `y/n`; **y** installs, **n** records to `package.json` |\n| **json**           | `--depends=json`            | Record all detected deps to `package.json` (no install)                              |\n| **custom json**    | `--depends=my-deps.json`    | Record to a custom `.json` file in `package.json` format                             |\n| **txt**            | `--depends=deps.txt`        | Record to a `.txt` file, one `package,version` per line                              |\n\n### Examples\n\n```bash\n# Auto-install (default)\nbiu src dist\n\n# Interactive confirm before installing\nbiu src dist --depends=confirm\n\n# Record to package.json only\nbiu src dist --depends=json\n\n# Record to a custom JSON file\nbiu src dist --depends=my-deps.json\n\n# Record to a text file\nbiu src dist --depends=deps.txt\n```\n\nIn **json** and **txt** modes, existing files are merged — new entries are added\nwithout overwriting previously recorded dependencies.\n\nIn **confirm** mode the prompt looks like:\n\n```\n📦 Missing dependencies detected:\n   • dayjs\n   • lodash-es\n\n   install dir: /path/to/project\nInstall these dependencies? (y/n):\n```\n\n## Static Directory\n\nFiles under the static directory (default `./static`) are copied verbatim into\nthe output directory **before** the build runs. This is useful for assets that\nshould not be processed or hashed — e.g. `robots.txt`, `manifest.json`,\nthird-party scripts, etc.\n\n```bash\n# Use the default ./static directory\nbiu\n\n# Specify a different directory\nbiu --static ./public\n```\n\n## Dev Server\n\n`--serve` starts a lightweight HTTP server powered by `Bun.serve` that serves\nthe output directory:\n\n- `/` maps to `/index.html`.\n- Requests without a file extension fall back to `/index.html` (SPA-friendly).\n- Proper MIME types are automatically detected by Bun.\n- `--serve` automatically enables watch mode, so changes trigger a rebuild.\n\n## Environment Variables\n\n### `BIU_ASSETS_EXTS`\n\nAdd extra static asset extensions beyond the built-in set (images, fonts, audio,\nvideo, etc.). Extensions can be specified with or without a leading dot,\nseparated by commas, spaces, or semicolons.\n\n```bash\nBIU_ASSETS_EXTS=\".glb .gltf .hdr\" biu\nBIU_ASSETS_EXTS=\"glb,gltf,hdr\" biu\n```\n\n### `BIU_EXCLUDED`\n\nA regex pattern to exclude files from processing. Case-insensitive.\n\n```bash\nBIU_EXCLUDED=\"test|spec\" biu\n```\n\n## Testing\n\nTests are written with Bun's built-in test runner. Each module in `src/` has a\ncorresponding `*_test.ts` file.\n\n```bash\n# Run all tests\nbun test src/\n\n# Run a specific test file\nbun test src/html_test.ts\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindon%2Fbiu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmindon%2Fbiu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmindon%2Fbiu/lists"}