Node.js quickstart

1. Install

   npm install rayobrowse playwright

   Node.js 18 or newer. The samples are ES modules with top-level await: save them as .mjs files, or add "type": "module" to your package.json.

2. Launch a browser

   // Save as quickstart.mjs and run: node quickstart.mjs
   import { Rayobrowse } from 'rayobrowse';
   import { chromium } from 'playwright';
   
   const PROXY = 'http://USERNAME:[email protected]:8000';
   
   const client = new Rayobrowse({
     endpoint: 'https://browser.rayobyte.com',
     apiKey: 'rb_live_YOUR_KEY',
   });
   
   const wsUrl = await client.connectUrl({ os: 'windows', proxy: PROXY });
   
   try {
     const browser = await chromium.connectOverCDP(wsUrl);
     const context = browser.contexts()[0];
     const page = context.pages()[0] ?? (await context.newPage());
     await page.goto('https://quotes.toscrape.com/');
     console.log(await page.title()); // Quotes to Scrape
     await browser.close();
   } finally {
     await client.close();
   }

   endpoint is the gateway you are calling and belongs on every client you build. Leave proxy out and connectUrl() throws BrowserCreateError with statusCode 400 and a plain-text body that starts A proxy is required for this account.

   client.close() in finally ends the session even when the page load throws. Playwright’s browser.close() only detaches from a browser it did not launch.

3. Watch it run

   Add vnc: true to the same call and read the live-view URL off the client:

   const liveUrl = await client.connectUrl({ os: 'windows', proxy: PROXY, vnc: true });
   console.log(client.vncUrl);

4. Handle the limits

   import { AuthError, ConcurrencyLimitError, RateLimitError } from 'rayobrowse';
   
   try {
     const wsUrl = await client.connectUrl({ os: 'windows', proxy: PROXY });
   } catch (err) {
     if (err instanceof AuthError) {
       console.error('Key rejected');
     } else if (err instanceof ConcurrencyLimitError || err instanceof RateLimitError) {
       // 5 s for a full account, 60 s for the rate limit
       await new Promise((r) => setTimeout(r, err.retryAfter * 1000));
     } else {
       throw err;
     }
   }

   A 429, too many running browsers or too many creates in a minute, throws one of these two, both with statusCode 429. Catch both: in 0.2.0 the class does not reliably say which limit was hit. retryAfter comes from the retry-after header and is right for either.

await client.close() closes the most recent session, or the id you pass it. Skip it and the browser runs until maxLifetime, 7,200 seconds by default, and all of it counts against your browser hours.

Next: Node.js reference and Limits.