Vibium Sync vs Async API

Vibium ships two APIs that do the same thing in different styles: a synchronous API that runs top to bottom with no await, and an asynchronous API that returns awaitables for event loops and concurrency. Both call the same Go binary and produce identical browser behavior, including auto-waiting. The choice is about how your code reads, not what it can do.

What is the difference between sync and async in Vibium?

The sync API blocks on each command until it finishes, while the async API returns a promise or coroutine you await. In Python, the sync client is from vibium import browser_sync as browser and the async client is from vibium.async_api import browser. In JavaScript, the async client is require("vibium") and the sync client is require("vibium/sync"). Importantly, both clients drive the exact same automation engine, so a sync click() and an async await click() go through the identical actionability checks.

How does the sync API look?

The sync API reads like ordinary procedural code: one statement after another, no event loop. Here it is in Python:

from vibium import browser_sync as browser
 
vibe = browser.launch()
vibe.go("https://example.com")
vibe.find("a").click()
vibe.quit()

And the JavaScript equivalent, using the vibium/sync subpath:

const { browser } = require("vibium/sync");
 
const bro = browser.launch();
const page = bro.page();
page.go("https://example.com");
page.find("a").click();
bro.close();

This style is ideal when you are learning, scripting a quick task, or want the most readable possible flow. It is the style used in Your First Vibium Script in Python and in JavaScript.

How does the async API look?

The async API returns awaitables, so you call it from inside an async function. In Python you run it with asyncio.run():

import asyncio
from vibium.async_api import browser
 
async def main():
    bro = await browser.launch()
    page = await bro.page()
    await page.go("https://example.com")
    await page.find("a").click()
    await bro.close()
 
asyncio.run(main())

In JavaScript, the default require("vibium") import is async:

const { browser } = require("vibium");
 
async function main() {
  const bro = await browser.launch();
  const page = await bro.page();
  await page.go("https://example.com");
  await page.find("a").click();
  await bro.close();
}
 
main();

Notice the method names match the sync version: the difference is the await in front of each call and the enclosing async function.

When should I use sync versus async?

Use sync for simplicity and async for integration. The table below summarizes the trade-off:

If you are not sure, start with sync. You can move a flow to async later by adding await and wrapping it in an async function, since the method names match.

Do sync and async behave differently at runtime?

No. Both APIs talk to the same Vibium Go binary, so element finding, the 30-second default actionability timeout, screenshots, and navigation all behave identically. Vibium auto-waits for elements in both modes; the binary handles polling for visibility, stability, and enabled state regardless of which client called it. The only practical difference is whether your code blocks (sync) or yields control to an event loop (async). To understand why the behavior is identical, see how Vibium works under the hood, where the single shared binary handles all timing server-side.

Can I mix sync and async in one project?

You can use different APIs in different scripts, but do not mix sync and async calls within a single browser session. Pick one client per script: a sync session expects blocking calls, and an async session expects awaited calls. If part of your codebase is async and part is sync, run them as separate Vibium sessions. For comparison with other tools' concurrency models, see Vibium vs Playwright.

Where do I go next?

Now that you know which API to reach for, write a full flow with Your First Vibium Script in Python or JavaScript, or learn how the single Go binary and BiDi make both APIs share one engine.