{"id":15546,"library":"bitbucket","title":"Bitbucket.js API Client","description":"bitbucket (Bitbucket.js) is a comprehensive JavaScript API client for interacting with the Bitbucket Cloud API, designed for both Node.js and browser environments. The current stable version is 2.12.0. This library aims to provide a robust and type-safe interface, shipping with TypeScript definitions, making it well-suited for modern JavaScript and TypeScript projects. It supports various authentication methods, including username/password and token-based authentication, and provides access to numerous Bitbucket API namespaces such as repositories, pull requests, pipelines, and users. The project draws heavy inspiration from `octokit/rest.js`, suggesting a similar, well-structured, and idiomatic approach to API interactions. While no explicit release cadence is stated, it appears to be actively maintained, with regular updates to reflect the latest Bitbucket API changes and bug fixes. Its key differentiators include its dual Node.js/browser support, extensive API coverage, and strong typing, simplifying complex API interactions.","status":"active","version":"2.12.0","language":"javascript","source_language":"en","source_url":"https://github.com/MunifTanjim/node-bitbucket","tags":["javascript","bitbucket","bitbucket-api","api-client","api","rest","typescript"],"install":[{"cmd":"npm install bitbucket","lang":"bash","label":"npm"},{"cmd":"yarn add bitbucket","lang":"bash","label":"yarn"},{"cmd":"pnpm add bitbucket","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM is preferred for modern Node.js and all browser environments. While CommonJS `require` still works, `import` offers better tree-shaking and future compatibility.","wrong":"const { Bitbucket } = require('bitbucket')","symbol":"Bitbucket","correct":"import { Bitbucket } from 'bitbucket'"},{"note":"This is the correct CommonJS syntax for Node.js environments. Do not mix with ESM `import` in the same file without proper transpilation.","wrong":"import { Bitbucket } from 'bitbucket'","symbol":"Bitbucket","correct":"const { Bitbucket } = require('bitbucket')"},{"note":"The `bitbucket` package ships with TypeScript types. `ClientOptions` is an interface for configuring the API client. `import type` is explicitly for type imports but `import` works too if not ambiguous.","wrong":"import type { ClientOptions } from 'bitbucket'","symbol":"ClientOptions","correct":"import { ClientOptions } from 'bitbucket'"}],"quickstart":{"code":"import { Bitbucket } from 'bitbucket';\n\nconst BITBUCKET_ACCESS_TOKEN = process.env.BITBUCKET_ACCESS_TOKEN ?? '';\n\nif (!BITBUCKET_ACCESS_TOKEN) {\n  console.error('Error: BITBUCKET_ACCESS_TOKEN environment variable is not set.');\n  process.exit(1);\n}\n\nconst clientOptions = {\n  baseUrl: 'https://api.bitbucket.org/2.0',\n  auth: {\n    token: BITBUCKET_ACCESS_TOKEN,\n  },\n  request: {\n    timeout: 10000, // 10 seconds\n  },\n};\n\nconst bitbucket = new Bitbucket(clientOptions);\n\nasync function listMyRepositories() {\n  try {\n    console.log('Fetching repositories...');\n    const { data } = await bitbucket.repositories.listForUser({ username: 'me' });\n    if (data && data.values) {\n      console.log('Found the following repositories:');\n      data.values.forEach(repo => console.log(`- ${repo.name} (${repo.full_name})`));\n    } else {\n      console.log('No repositories found or unexpected response format.');\n    }\n  } catch (err) {\n    if (err.status === 401 || err.status === 403) {\n      console.error('Authentication failed. Check your BITBUCKET_ACCESS_TOKEN and permissions.');\n    } else {\n      console.error(`Error listing repositories: ${err.message}`);\n      if (err.error) {\n        console.error('API Error details:', err.error);\n      }\n    }\n  }\n}\n\nlistMyRepositories();","lang":"typescript","description":"This quickstart demonstrates how to initialize the Bitbucket client with token authentication and list repositories for the authenticated user ('me'). It includes error handling for common API issues like authentication failures."},"warnings":[{"fix":"Consult the release notes and migration guides (if available) on the package's GitHub repository or documentation site when upgrading to a new major version. Test your application thoroughly after any major version upgrade.","message":"Major version updates, particularly from v1 to v2, often introduce breaking changes in API method signatures, response structures, or authentication mechanisms. Always review the official changelog or migration guide when upgrading across major versions to avoid unexpected issues. Specific changes may include renaming methods, altering parameter requirements, or updating the base URL.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Implement custom retry logic with exponential backoff for `429` status codes. Monitor `Retry-After` headers in API responses if provided. Design your application to minimize unnecessary API calls.","message":"Bitbucket API enforces rate limits on requests. Exceeding these limits will result in `429 Too Many Requests` errors. The client library does not inherently handle retry logic or backoff strategies out-of-the-box, which must be implemented by the consumer.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify that your `username`/`password` or `token` is correct and current. Ensure the Bitbucket user or app associated with the token has the necessary scopes/permissions for the API operations being attempted.","message":"Authentication failures often manifest as `401 Unauthorized` or `403 Forbidden` errors. This can be due to incorrect tokens, expired credentials, or insufficient permissions granted to the authenticated user or token.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Proxy Bitbucket API requests through your backend server to avoid CORS issues, or ensure your Bitbucket App/configuration is set up to allow CORS from your specific frontend origin if applicable.","message":"When using the client in a browser environment, be mindful of cross-origin resource sharing (CORS) policies. Direct API calls from a browser to Bitbucket's API might be blocked if the response does not include appropriate CORS headers, especially for non-simple requests.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For Node.js ESM projects, use `import { Bitbucket } from 'bitbucket'`. For CommonJS Node.js, use `const { Bitbucket } = require('bitbucket')`. In a browser with the UMD build, ensure the `Bitbucket` global is available after script loading.","cause":"Incorrectly importing or referencing the Bitbucket class, often when mixing CommonJS `require` syntax with an ESM-only context, or when using the UMD build without global access.","error":"ReferenceError: Bitbucket is not defined"},{"fix":"Verify the method name and namespace against the official documentation (e.g., `bitbucketjs.netlify.app`). Ensure all required parameters are passed as an object to the API method.","cause":"Attempting to call an API method with incorrect arguments or on a non-existent namespace/method. This can also happen if the API client instance is not correctly initialized.","error":"TypeError: bitbucket.repositories.listGlobal is not a function"},{"fix":"Review the `err.error` object in the catch block for specific details from the Bitbucket API about what caused the bad request. Ensure all required parameters for the specific API method are correctly formatted and provided.","cause":"A `400 Bad Request` status indicates that the API request itself was malformed, missing required parameters, or contained invalid data.","error":"Error: Request failed with status code 400"}],"ecosystem":"npm"}