{"id":17182,"library":"builder-util-runtime","title":"Electron Builder Runtime Utilities","description":"builder-util-runtime is an internal utility package within the electron-builder ecosystem, providing core HTTP client functionalities, download progress tracking, and cancellation capabilities. It is primarily used by electron-builder and electron-updater for managing asset downloads, update checks, and publishing operations, rather than being directly consumed by end-user applications. The package ships with TypeScript type declarations, facilitating its use in TypeScript projects. It is part of the larger electron-builder monorepo, which typically follows an 8-week release cadence for major versions, aligning with Chromium's schedule, ensuring frequent updates and maintenance. The current stable version, as a dependency, is 9.6.0. Its main differentiators are its tight integration with the Electron build and update process and its focus on robust HTTP handling for Electron applications.","status":"active","version":"9.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/electron-userland/electron-builder","tags":["javascript","typescript"],"install":[{"cmd":"npm install builder-util-runtime","lang":"bash","label":"npm"},{"cmd":"yarn add builder-util-runtime","lang":"bash","label":"yarn"},{"cmd":"pnpm add builder-util-runtime","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is predominantly ESM-first, and while CommonJS might work in some contexts, direct named imports from 'builder-util-runtime' are the recommended and most reliable approach, especially since Node.js 12+ is required. Using require() can lead to `undefined` or incorrect module resolution if the CJS export isn't explicitly configured for named exports.","wrong":"const { createNetClient } = require('builder-util-runtime')","symbol":"createNetClient","correct":"import { createNetClient } from 'builder-util-runtime'"},{"note":"ProgressCallbackTransform is a named export. Attempting a default import will result in 'undefined' or a runtime error. This class is crucial for tracking download progress for large files.","wrong":"import ProgressCallbackTransform from 'builder-util-runtime'","symbol":"ProgressCallbackTransform","correct":"import { ProgressCallbackTransform } from 'builder-util-runtime'"},{"note":"HttpError is an error class exported for handling HTTP-specific errors during network operations. It's a named export, primarily used for robust error handling in download and update processes.","symbol":"HttpError","correct":"import { HttpError } from 'builder-util-runtime'"},{"note":"The CancellationToken class provides a mechanism for cooperative cancellation of asynchronous operations, useful for controlling long-running network requests.","symbol":"CancellationToken","correct":"import { CancellationToken } from 'builder-util-runtime'"}],"quickstart":{"code":"import { createWriteStream } from 'fs';\nimport { createNetClient, ProgressCallbackTransform, HttpError, CancellationToken } from 'builder-util-runtime';\n\ninterface RequestOptions {\n  url: string;\n  headers?: Record<string, string>;\n}\n\n// A simplified representation of safeExecute, as the original might be internal or complex.\n// This ensures the download operation is wrapped in a way that handles cancellation.\nasync function safeExecute<T>(task: () => Promise<T>, cancellationToken?: CancellationToken): Promise<T | undefined> {\n  if (cancellationToken?.isCancelled) {\n    console.log('Operation already cancelled.');\n    return undefined;\n  }\n  try {\n    return await task();\n  } catch (e) {\n    if (cancellationToken?.isCancelled) {\n      console.log('Operation cancelled during execution.');\n      return undefined;\n    }\n    throw e;\n  }\n}\n\nasync function downloadFileWithProgress(url: string, outputPath: string) {\n  const client = createNetClient();\n  const cancellationToken = new CancellationToken();\n\n  const options: RequestOptions = {\n    url,\n    headers: {\n      'User-Agent': 'my-app-downloader/1.0.0',\n      'Accept': 'application/octet-stream'\n    },\n  };\n\n  const fileStream = createWriteStream(outputPath);\n  const progressStream = new ProgressCallbackTransform(0, (progress) => {\n    console.log(`Downloaded: ${progress.percent.toFixed(2)}% (${(progress.transferred / 1024 / 1024).toFixed(2)}MB / ${(progress.total / 1024 / 1024).toFixed(2)}MB)`);\n  });\n\n  try {\n    console.log(`Starting download from ${url} to ${outputPath}...`);\n    await safeExecute(() => client.download(options, fileStream, progressStream, cancellationToken), cancellationToken);\n    console.log(`Download complete: ${outputPath}`);\n  } catch (error) {\n    if (error instanceof HttpError) {\n      console.error(`HTTP Error ${error.statusCode}: ${error.message}`);\n    } else if (cancellationToken.isCancelled) {\n      console.log('Download operation was cancelled.');\n    } else {\n      console.error('An unexpected error occurred during download:', error);\n    }\n  } finally {\n    fileStream.close();\n  }\n}\n\n// Example usage: Download a small public file\n// Replace with a valid URL to test, e.g., a small image or text file.\nconst dummyDownloadUrl = \"https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png\";\nconst downloadPath = \"./downloaded_google_logo.png\";\n\ndownloadFileWithProgress(dummyDownloadUrl, downloadPath).catch(console.error);\n\n// To demonstrate cancellation (uncomment to test):\n// const cancelToken = new CancellationToken();\n// downloadFileWithProgress(dummyDownloadUrl, \"./cancel_test.png\", cancelToken).catch(console.error);\n// setTimeout(() => {\n//   console.log('Attempting to cancel download...');\n//   cancelToken.cancel();\n// }, 500);","lang":"typescript","description":"Demonstrates downloading a file with progress tracking and cancellation using builder-util-runtime's HTTP utilities. This showcases basic network operations that the package facilitates internally for Electron-based applications."},"warnings":[{"fix":"Minimize direct dependencies on this package. If direct use is necessary, pin to exact versions and monitor `electron-builder`'s changelog for related updates.","message":"As an internal utility within the electron-builder monorepo, builder-util-runtime's API is not guaranteed to be stable for direct consumption. Breaking changes may occur in patch or minor releases without explicit deprecation notices, as its primary consumers are electron-builder and electron-updater themselves. Direct usage should be approached with caution and thorough testing.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Always use `import { SymbolName } from 'builder-util-runtime'` syntax for all exports to ensure correct module resolution in both TypeScript and modern JavaScript environments.","message":"The package leans towards an ESM-first architecture, shipping with `main` and `module` entries. While CJS `require()` might resolve, it can lead to unexpected `undefined` imports or module resolution issues, especially with named exports. Node.js >=12.0.0 is required, and modern Node.js environments favor ESM imports.","severity":"gotcha","affected_versions":">=9.0.0"},{"fix":"Update to a current version of `electron-builder` and `builder-util-runtime` (>=9.0.0) and migrate to supported publishing providers such as GitHub Releases, Amazon S3, or DigitalOcean Spaces. Ensure your build configuration reflects the change.","message":"Older versions of `builder-util-runtime` included support for Bintray, which was sunset. Any integrations relying on Bintray publishing options would have ceased to function.","severity":"deprecated","affected_versions":"<9.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { createNetClient } from 'builder-util-runtime';` and that your project's TypeScript/Babel configuration correctly handles ESM output for Node.js.","cause":"This typically occurs when attempting to use CommonJS `require()` syntax or incorrect destructuring to import an ESM named export, leading to the module object being imported but the function itself not being correctly resolved or called.","error":"TypeError: (0 , builder_util_runtime_1.createNetClient) is not a function"},{"fix":"Check your network environment for proxy settings. You might need to set `NODE_TLS_REJECT_UNAUTHORIZED='0'` (use with caution in production) or configure trusted certificates for Node.js, possibly by setting the `ELECTRON_GET_UNSAFE_HTTP` environment variable or providing custom `agent` options to the HTTP client if the API supports it.","cause":"Network requests made by `builder-util-runtime` can fail due to SSL certificate issues, often caused by corporate proxies, firewalls, or misconfigured system root certificates, rather than a bug in the library itself.","error":"Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE or ERR_SSL_CERT_HA_SS_IN_VALID"},{"fix":"Run `npm install builder-util-runtime` or `yarn add builder-util-runtime`. If it's a transitive dependency, try `npm install` or `yarn install` in your root project to ensure all dependencies are correctly hoisted and linked. Verify your `package.json` for proper declarations.","cause":"The package is not installed as a direct dependency or a transitive dependency is missing or incorrectly resolved in your `node_modules`.","error":"Error: Cannot find module 'builder-util-runtime'"}],"ecosystem":"npm","meta_description":null}