{"id":16328773,"url":"https://github.com/webdriverio/bx","last_synced_at":"2025-04-14T13:57:12.654Z","repository":{"id":222733437,"uuid":"752113288","full_name":"webdriverio/bx","owner":"webdriverio","description":"Command line tool to run JavaScript, TypeScript or HTML files in the browser.","archived":false,"fork":false,"pushed_at":"2025-04-07T12:08:08.000Z","size":923,"stargazers_count":11,"open_issues_count":6,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-12T10:22:41.040Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webdriverio.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},"funding":{"tidelift":"npm/webdriverio","open_collective":"webdriverio"}},"created_at":"2024-02-03T04:10:03.000Z","updated_at":"2025-04-07T12:08:06.000Z","dependencies_parsed_at":"2024-04-15T13:02:06.027Z","dependency_job_id":"a7a3aa6c-9de3-4cdc-91ee-e9f3c612654f","html_url":"https://github.com/webdriverio/bx","commit_stats":{"total_commits":172,"total_committers":4,"mean_commits":43.0,"dds":0.2965116279069767,"last_synced_commit":"ef9c5451ae84eb3ffc4e8c743c86881f302242d4"},"previous_names":["webdriverio/bx","christian-bromann/bx"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fbx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fbx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fbx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webdriverio%2Fbx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webdriverio","download_url":"https://codeload.github.com/webdriverio/bx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248893678,"owners_count":21179065,"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":[],"created_at":"2024-10-10T23:14:31.144Z","updated_at":"2025-04-14T13:57:12.630Z","avatar_url":"https://github.com/webdriverio.png","language":"TypeScript","funding_links":["https://tidelift.com/funding/github/npm/webdriverio","https://opencollective.com/webdriverio"],"categories":["TypeScript"],"sub_categories":[],"readme":"# 🌐 bx - a browser runner [![CI](https://github.com/webdriverio/bx/actions/workflows/ci.yml/badge.svg)](https://github.com/webdriverio/bx/actions/workflows/ci.yml)\n\nWith Node.js, Deno or Bun there are so many JavaScript environments to choose from. However, nothing is as good as the browser environment. `bx` gives you an execution runtime for the browser.\n\n# Install\n\nNo install needed, just run it directly via `npx`, e.g.:\n\n```sh\nnpx bx \"console.log(navigator.userAgent)\"\n```\n\n# Usage\n\nWith `bx` you can easily run scripts (JS or TS) within different browser environments:\n\n```sh\n\u003e echo \"console.log(navigator.userAgent)\" \u0026\u003e script.js\n\u003e npx bx ./script.js\nMozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36\n```\n\nYou can easily switch browsers via the `--browserName` parameter:\n\n```sh\n\u003e npx bx ./script.js --browserName firefox\nMozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:121.0) Gecko/20100101 Firefox/121.0\n```\n\nIt even allows you to run `.html` files, e.g. given this file:\n\n```html\n\u003cscript type=\"module\"\u003e\n  console.log(document.querySelector(\"b\").textContent);\n\u003c/script\u003e\n\u003cb\u003eHello World!\u003c/b\u003e\n```\n\nRunning this with `bx` results in:\n\n```sh\n\u003e npx bx ./html.html\nHello World!\n```\n\n# Run Programmatically\n\nYou can also run `bx` programmatically, e.g. to hydrate components within the browser.\n\n## Hydrate Web Components\n\nFor example, to hydrate a [Lit](https://lit.dev/) component through a [Koa](https://koajs.com/) server, you can run this script:\n\n```ts\nimport path from \"node:path\";\nimport Koa from \"koa\";\n\nimport { run } from \"bx\";\n\nconst __dirname = path.dirname(new URL(import.meta.url).pathname);\nconst app = new Koa();\n\napp.use(async (ctx) =\u003e {\n  if (ctx.path === \"/favicon.ico\") {\n    return;\n  }\n\n  ctx.body = await run(async () =\u003e {\n    /**\n     * runs in the browser\n     */\n    const { render } = await import(\"@lit-labs/ssr\");\n    const { html } = await import(\"lit\");\n    await import(\"./component.ts\");\n\n    const dom = await render(html`\u003csimple-greeting\u003e\u003c/simple-greeting\u003e`);\n    return Array.from(dom).join(\"\\n\");\n  }, {\n    browserName: \"chrome\",\n    rootDir: __dirname,\n  });\n});\n\napp.listen(3000);\nconsole.log(\"Server running at http://localhost:3000/\");\n```\n\n## Run Benchmark Tests in Browser\n\nAnother interesting use case is running benchmarks within different browsers using tools like Tinybench. For example:\n\n```ts\nimport { run } from 'bx'\n\nasync function benchmarkTest() {\n    const { Bench } = await import('tinybench');\n    const bench = new Bench({ time: 100 });\n\n    bench\n        .add('faster task', () =\u003e {\n            console.log('I am faster')\n        })\n        .add('slower task', async () =\u003e {\n            await new Promise(r =\u003e setTimeout(r, 1)) // we wait 1ms :)\n            console.log('I am slower')\n        })\n\n    await bench.run();\n    return bench.results;\n}\n\nconst [fasterTaskChrome, slowerTaskChrome] = await run(benchmarkTest, {\n    browserName: 'chrome'\n})\nconst [fasterTaskFirefox, slowerTaskFirefox] = await run(benchmarkTest, {\n    browserName: 'firefox'\n})\n\nconsole.log(`Chrome: faster task ${fasterTaskChrome.mean}ms, slower task ${slowerTaskChrome.mean}ms`)\nconsole.log(`Firefox: faster task ${fasterTaskFirefox.mean}ms, slower task ${slowerTaskFirefox.mean}ms`)\n```\n\nwhich prints out:\n\n```\nChrome: faster task 0.015639662257872562ms, slower task 4.015384614467621ms\nFirefox: faster task 0.007285443683520326ms, slower task 4.761904761904762ms\n```\n\n# Session Management\n\nIf you like to speed up your execution, you can create browser sessions on your system and run scripts through them immediately without having to spin up the browser. You can create a session via:\n\n```sh\n# create a session with random session name, e.g. \"chrome-1\"\nnpx bx session --browserName chrome\n# create a session with custom name\nnpx bx session --browserName chrome --name chrome\n```\n\nYou can now run scripts faster by providing a session name:\n\n```sh\nnpx bx ./script.ts --sessionName chrome\n```\n\nTo view all opened sessions, run:\n\n```sh\nnpx bx session\n```\n\nKill specific or all sessions via:\n\n```sh\nnpx bx session --kill chrome\nnpx bx session --killAll\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdriverio%2Fbx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebdriverio%2Fbx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebdriverio%2Fbx/lists"}