{"id":16302,"library":"balena-request","title":"Balena HTTP Client","description":"balena-request is a low-level HTTP client specifically designed for making requests to Balena servers. It is not intended for direct use by end-users, but rather as an internal dependency for other Balena-io modules, such as the balena SDK. The current stable version is 14.2.0, with frequent patch and minor releases, indicating active development. Key differentiators include its tight integration with the Balena ecosystem, requiring an instantiated `balena-auth` instance for authentication, and providing features like request interceptors, streaming capabilities, and automatic handling of authorization. It supports both Node.js (requiring `>=18.0.0`) and browser environments, though the `isBrowser` option has been deprecated in recent versions. The module exposes a factory function to create a request instance, enabling configurable behavior like debug logging and retries.","status":"active","version":"14.2.0","language":"javascript","source_language":"en","source_url":"git://github.com/balena-io-modules/balena-request","tags":["javascript","balena","request","http","typescript"],"install":[{"cmd":"npm install balena-request","lang":"bash","label":"npm"},{"cmd":"yarn add balena-request","lang":"bash","label":"yarn"},{"cmd":"pnpm add balena-request","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for authentication. An instantiated balena-auth instance must be passed to the factory function.","package":"balena-auth","optional":false}],"imports":[{"note":"The module exports a default factory function, not named exports for the primary client. The `require` pattern also involves calling the default export directly.","wrong":"import { balenaRequest } from 'balena-request';","symbol":"balenaRequest","correct":"import balenaRequest from 'balena-request';"},{"note":"TypeScript types like `Interceptor` are typically imported using `import type`.","wrong":"import { Interceptor } from 'balena-request';","symbol":"Interceptor","correct":"import type { Interceptor } from 'balena-request';"},{"note":"Error types were explicitly exported in v14.2.0 to allow `instanceof` checks.","wrong":"import BalenaRequestError from 'balena-request';","symbol":"BalenaRequestError","correct":"import { BalenaRequestError } from 'balena-request';"}],"quickstart":{"code":"import balenaRequest from 'balena-request';\nimport balenaAuth from 'balena-auth';\n\n// Mock balenaAuth for demonstration purposes.\n// In a real application, you would instantiate and configure balenaAuth.\nconst auth = balenaAuth.createInstance({\n  dataDirectory: process.env.BALENA_DATA_DIR ?? false, // Use false for in-memory in tests/examples\n  // apiKey: process.env.BALENA_API_KEY ?? '', // Or use an API key\n});\n\nasync function makeRequest() {\n  const request = balenaRequest({\n    auth: auth,\n    debug: process.env.DEBUG_BALENA_REQUEST === 'true',\n    // The `isBrowser` option is deprecated and no longer needed for modern environments.\n    // isBrowser: false, \n  });\n\n  try {\n    console.log('Making a request to Balena API...');\n    const result = await request.send({\n      method: 'GET',\n      url: 'https://api.balena-cloud.com/ping',\n      headers: {\n        'Content-Type': 'application/json',\n      },\n      // Note: balena-request automatically handles authorization if auth is provided\n    });\n    console.log('Request successful! Status:', result.statusCode);\n    // console.log('Response body:', result.body);\n  } catch (error) {\n    console.error('Request failed:', error);\n    if (error instanceof balenaRequest.BalenaRequestError) {\n      console.error('This is a specific BalenaRequestError.');\n    }\n  }\n}\n\nmakeRequest();","lang":"typescript","description":"Demonstrates how to import `balena-request`, create a client instance with a mocked `balena-auth` dependency, and execute a simple GET request to the Balena API's `/ping` endpoint."},"warnings":[{"fix":"For most use cases, use the `balena-sdk` package (`npm install --save balena-sdk`) which wraps `balena-request` with a higher-level API.","message":"This module is explicitly designed as a low-level client for internal Balena-io modules and is NOT meant for direct use by end-users. Using it directly may lead to unexpected behavior or require a deep understanding of Balena's internal HTTP client logic. The official `balena-sdk` should be used instead for most applications.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Remove the `isBrowser` option from your `balenaRequest` factory configuration.","message":"The `isBrowser` option passed to the `balenaRequest` factory function was deprecated in v14.0.8. The module now generally handles environment detection automatically or relies on native Fetch API and `node-fetch` for streaming.","severity":"deprecated","affected_versions":">=14.0.8"},{"fix":"Review any custom URL parsing or manipulation logic within interceptors or downstream modules that might implicitly rely on Node.js `url` module behavior. Ensure compatibility with the WHATWG URL API standard.","message":"Internal uses of the deprecated `url.parse` and `url.resolve` Node.js API were replaced with the WHATWG URL API in v14.1.6. While this is an internal change, it could potentially affect applications that rely on specific parsing behaviors or error handling of the older `url` module if custom interceptors or deeply integrated logic are used.","severity":"breaking","affected_versions":">=14.1.6"},{"fix":"Ensure that your environment (especially older Node.js versions or specific browser targets) provides a compatible `fetch` implementation or include necessary polyfills like `abortcontroller-polyfill` if using `AbortController` for request cancellation.","message":"The internal `fetch-ponyfill` dependency was dropped in favor of native `fetch` (in browsers) and `node-fetch` (in Node.js) for streaming downloads in v14.0.8. This change could subtly alter behavior or require new polyfills if the `fetch-ponyfill` was providing specific browser compatibility or older Node.js `fetch` polyfills.","severity":"breaking","affected_versions":">=14.0.8"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure an instantiated `balena-auth` instance is passed as the `auth` option: `balenaRequest({ auth: myAuthInstance, ... })`.","cause":"The `auth` option was not provided or was `undefined` when initializing the `balenaRequest` factory function.","error":"TypeError: Cannot read properties of undefined (reading 'auth')"},{"fix":"Verify your bundling configuration (e.g., Webpack, Rollup) for Balena modules, ensuring proper resolution and transpilation. For Balena Etcher specific issues, try running the application as an administrator or using an alternative flashing tool if the issue persists.","cause":"This error often occurs when `balena-request` or a related Balena module is incorrectly bundled or used in an environment where its internal dependencies or module resolution fails, frequently seen with tools like Etcher or custom bundlers.","error":"Error: (0 , h.requestMetadata) is not a function"},{"fix":"Provide an `auth` instance of `balena-auth` in the options object: `balenaRequest({ auth: balenaAuthInstance, debug: false })`.","cause":"In TypeScript, the `auth` property is a required part of `BalenaRequestOptions` when initializing the client.","error":"TS2345: Argument of type '{ debug: boolean; isBrowser: boolean; }' is not assignable to parameter of type 'BalenaRequestOptions'. Property 'auth' is missing in type '{ debug: boolean; isBrowser: boolean; }' but required in type 'BalenaRequestOptions'."}],"ecosystem":"npm"}