JavaScript and TypeScript
The vibium npm package drives a real browser from Node.js. It ships
TypeScript types and bundles the vibium binary for your platform.
Requirements
Section titled “Requirements”- Node.js 18 or newer
- Linux x64/arm64, macOS x64/arm64, or Windows x64
Install
Section titled “Install”npm install vibiumChrome for Testing downloads the first time a browser starts. To fetch it
ahead of time, run npx vibium install.
First script
Section titled “First script”Save this as hello.mjs:
import { writeFileSync } from 'node:fs'import { browser } from 'vibium'
// Launch a browser. The window is visible by default.const bro = await browser.start()const vibe = await bro.page()
await vibe.go('https://example.com')writeFileSync('screenshot.png', await vibe.screenshot())
const link = await vibe.find({ role: 'link' })console.log('Found link:', await link.text())await link.click()
await bro.stop()Run it:
node hello.mjsA Chrome window opens, loads the page, clicks the link, and closes. The
script prints Found link: Learn more and leaves screenshot.png in the
folder.
| Call | What it does |
|---|---|
browser.start() | Launches Chrome and returns a Browser |
bro.page() | Returns the default page (tab) |
vibe.go(url) | Navigates to a URL |
vibe.screenshot() | Returns the page as PNG bytes |
vibe.find({ role: 'link' }) | Finds an element by its accessible role |
link.click() | Clicks the element |
bro.stop() | Closes the browser |
Sync API
Section titled “Sync API”The default import is async. vibium/sync exposes the same API without
await, which suits short scripts and the Node REPL:
const { browser } = require('vibium/sync')
const bro = browser.start()const vibe = bro.page()vibe.go('https://example.com')console.log(vibe.find({ role: 'link' }).text())bro.stop()Options
Section titled “Options”Hide the browser window:
const bro = await browser.start({ headless: true })Launch Firefox instead of Chrome:
import { firefox, browser } from 'vibium'
const bro = await firefox.start()// same as: await browser.start({ engine: 'firefox' })See Using Firefox for engine details.
Finding elements
Section titled “Finding elements”find takes semantic locators. They survive markup changes better than CSS:
await vibe.find({ role: 'button', text: 'Sign in' })await vibe.find({ label: 'Email' })await vibe.find({ placeholder: 'Search...' })await vibe.find({ testid: 'checkout' })A bare string is a plain-language description
(vibe.find('the Add to Cart button')), and { css: '...' } takes an
exact CSS selector. Before 26.11.16 a bare string was a CSS selector.
Let the AI drive
Section titled “Let the AI drive”const result = await vibe.run('open the contact page')const verdict = await vibe.check('the page lists an email address')- API Reference: every method, with its CLI and MCP equivalent.
- Client Libraries: the object model shared by all three languages.
- Run and Check and Model Providers.
- Troubleshooting.