/js-sdk-best-practices

name: brightdata-sdk-js
description: |
  Web data extraction and discovery using the Bright Data JavaScript/TypeScript
  SDK (`@brightdata/sdk`). Use when the user is working in Node.js/TypeScript and
  asks to "scrape", "get data from", "extract", "search for", or "find"
  information from websites. Also use when the user mentions specific platforms
  like Amazon, LinkedIn, Instagram, Facebook, TikTok, YouTube, Reddit, Pinterest,
  ChatGPT, Perplexity, or DigiKey, or asks for "bulk data", "historical data", or
  "dataset" from JS. Covers scraping, SERP search, AI discovery, datasets,
  browser automation, and Scraper Studio. For Python, use brightdata-sdk; for the
  terminal CLI, use brightdata-cli.
metadata:
  author: brightdata
  version: "1.0"
  package: "@brightdata/sdk"
  repository: https://github.com/brightdata/sdk-js

Bright Data JavaScript SDK

Access web data through a unified Node.js/TypeScript SDK (`@brightdata/sdk`). One client, several services: web unlocking (`scrapeUrl`), platform scraping (`scrape.<platform>`), SERP search (`search.google/bing/yandex`), AI discovery (`discover`), datasets, browser automation, and Scraper Studio.

**Requires Node.js ≥ 20.** Ships ESM + CommonJS with full TypeScript types. The client is exported as `bdclient` (lowercase — not a typo).

Setup gate (do first)

npm install @brightdata/sdk     # or: pnpm add / yarn add

The client reads the `BRIGHTDATA_API_TOKEN` env var, or you pass `{ apiKey }`. Get a token at https://brightdata.com/cp/setting/users.

// ESM (package.json "type": "module", or .mjs)
import { bdclient } from '@brightdata/sdk';

// CommonJS (.cjs / "type": "commonjs")
const { bdclient } = require('@brightdata/sdk');

const client = new bdclient();             // reads BRIGHTDATA_API_TOKEN
// const client = new bdclient({ apiKey: '...' });
try {
  const html = await client.scrapeUrl('https://example.com');
} finally {
  await client.close();                    // always close (or `await using`)
}

`await using client = new bdclient()` (TS 5.2+ / Node ≥20) auto-closes at scope end.

Service Selection (decide first, then look up the method)

Pick the service BEFORE reaching for a specific method. Most routing mistakes come from skipping this step and pattern-matching on keywords.

Have a URL?
  ├── On a supported platform (Amazon, LinkedIn, Facebook, Instagram, YouTube,
  │   TikTok, Reddit, Pinterest, ChatGPT, Perplexity, DigiKey)?
  │     → Platform scraping: client.scrape.<platform>.<method>(urls, opts?)
  │
  ├── Generic page (no dedicated platform scraper)?
  │     → Web unlocker: client.scrapeUrl(url, { dataFormat: 'markdown' })
  │
  └── Need login / JS / click-scroll-fill / CAPTCHA / multi-step nav?
        → Browser API: client.browser.getConnectUrl() (connect via Playwright)

No URL?
  ├── Want entities matching natural-language criteria
  │   ("find AI startups in Berlin", "competitors of Acme")?
  │     → Discover: client.discover(query, { intent })
  │
  ├── Want web pages / search-result links ("search Google for X")?
  │     → SERP: client.search.google(query) [or .bing / .yandex]
  │
  ├── Want to search WITHIN a platform ("Amazon products by keyword",
  │   "LinkedIn jobs", "Instagram reels by profile")?
  │     → Platform discovery: client.scrape.<platform>.discover*(filters)
  │       or amazon.productSearch(...)  (NOTE: client.search is SERP-only here)
  │
  └── Want bulk/historical data at scale?
        → Datasets: client.datasets.<name>.query(filter) → .download(snapshotId)

Edge cases:

• Supported-platform URL BUT user mentions login/click/scroll/JS → Browser API (the interaction trumps the platform).
• Supported-platform scrape returns 403/blocked → fall back to `client.scrapeUrl()` (web unlocker).
• "Find/research who are X" with a URL alongside ("competitors of acme.com") → still Discover; the URL is context, not the scrape target.

⚠️ Key differences from the Python SDK

If you know the Python SDK (`brightdata-sdk`), the JS surface differs — do not port names blindly:

| Concept | Python | JavaScript | |---|---|---| | Client | `SyncBrightDataClient` / `BrightDataClient` | `bdclient` (single, all async) | | Web unlocker | `client.scrape_url(url=...)` | `client.scrapeUrl(url, opts)` | | Platform search | `client.search.amazon.products(...)` | **none** — use `scrape.amazon.productSearch` / `discover*` | | `client.search` | SERP **and** platform search | **SERP only** (google/bing/yandex) | | Batch | `*_trigger` methods + `job.wait()` | pass a `string[]` to one call, or `*Trigger` + `job.wait()` | | Naming | `snake_case` | `camelCase` | | Datasets | `client.datasets.amazon_products` | `client.datasets.amazonProducts` |

Method Names: Verify Before Asserting

Before claiming a platform method exists/doesn't exist, **consult `references/scrapers.md`** — it lists every platform's verified methods. The SDK ships TypeScript types, so in a typed project you can also let the compiler/editor confirm a method exists.

Each platform exposes up to three method styles (see `references/scrapers.md`):

• **`collect<Thing>(input, opts?)`** — returns the rows directly (`object[]`).
• **`<thing>(input, opts?)`** — orchestrated (trigger → poll → download); returns `{ data, status, rowCount }`. **Default to this.**
• **`discover<Thing>By<X>(filters, opts?)`** — find items by keyword/category/URL filter instead of by direct URL.

**Likely hallucinations** (do NOT write these — verify in `references/scrapers.md`):

| Wrong | Right | |---|---| | `client.search.amazon.products(...)` | `client.scrape.amazon.productSearch(...)` (no platform search router in JS) | | `client.scrape.linkedin.people(...)` | `client.scrape.linkedin.profiles(urls)` | | `client.scrape.chatgpt...` | `client.scrape.chatGPT...` (camelCase G+T) | | `client.datasets.amazon_products` | `client.datasets.amazonProducts` | | `BrightDataClient` / `new BdClient()` | `bdclient` (all lowercase) |

Useful s