Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createNetClient
✓ import { createNetClient } from 'builder-util-runtime'
✗ const { createNetClient } = require('builder-util-runtime')
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.
ProgressCallbackTransform
✓ import { ProgressCallbackTransform } from 'builder-util-runtime'
✗ import ProgressCallbackTransform from 'builder-util-runtime'
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.
HttpError
✓ import { HttpError } from 'builder-util-runtime'
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.
CancellationToken
✓ import { CancellationToken } from 'builder-util-runtime'
The CancellationToken class provides a mechanism for cooperative cancellation of asynchronous operations, useful for controlling long-running network requests.
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.
import { createWriteStream } from 'fs';
import { createNetClient, ProgressCallbackTransform, HttpError, CancellationToken } from 'builder-util-runtime';
interface RequestOptions {
url: string;
headers?: Record<string, string>;
}
// A simplified representation of safeExecute, as the original might be internal or complex.
// This ensures the download operation is wrapped in a way that handles cancellation.
async function safeExecute<T>(task: () => Promise<T>, cancellationToken?: CancellationToken): Promise<T | undefined> {
if (cancellationToken?.isCancelled) {
console.log('Operation already cancelled.');
return undefined;
}
try {
return await task();
} catch (e) {
if (cancellationToken?.isCancelled) {
console.log('Operation cancelled during execution.');
return undefined;
}
throw e;
}
}
async function downloadFileWithProgress(url: string, outputPath: string) {
const client = createNetClient();
const cancellationToken = new CancellationToken();
const options: RequestOptions = {
url,
headers: {
'User-Agent': 'my-app-downloader/1.0.0',
'Accept': 'application/octet-stream'
},
};
const fileStream = createWriteStream(outputPath);
const progressStream = new ProgressCallbackTransform(0, (progress) => {
console.log(`Downloaded: ${progress.percent.toFixed(2)}% (${(progress.transferred / 1024 / 1024).toFixed(2)}MB / ${(progress.total / 1024 / 1024).toFixed(2)}MB)`);
});
try {
console.log(`Starting download from ${url} to ${outputPath}...`);
await safeExecute(() => client.download(options, fileStream, progressStream, cancellationToken), cancellationToken);
console.log(`Download complete: ${outputPath}`);
} catch (error) {
if (error instanceof HttpError) {
console.error(`HTTP Error ${error.statusCode}: ${error.message}`);
} else if (cancellationToken.isCancelled) {
console.log('Download operation was cancelled.');
} else {
console.error('An unexpected error occurred during download:', error);
}
} finally {
fileStream.close();
}
}
// Example usage: Download a small public file
// Replace with a valid URL to test, e.g., a small image or text file.
const dummyDownloadUrl = "https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png";
const downloadPath = "./downloaded_google_logo.png";
downloadFileWithProgress(dummyDownloadUrl, downloadPath).catch(console.error);
// To demonstrate cancellation (uncomment to test):
// const cancelToken = new CancellationToken();
// downloadFileWithProgress(dummyDownloadUrl, "./cancel_test.png", cancelToken).catch(console.error);
// setTimeout(() => {
// console.log('Attempting to cancel download...');
// cancelToken.cancel();
// }, 500);
Errors
Common errors & fixes
TypeError: (0 , builder_util_runtime_1.createNetClient) is not a function
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.
fixEnsure you are using `import { createNetClient } from 'builder-util-runtime';` and that your project's TypeScript/Babel configuration correctly handles ESM output for Node.js. Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE or ERR_SSL_CERT_HA_SS_IN_VALID
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.
fixCheck 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.
Error: Cannot find module 'builder-util-runtime'
The package is not installed as a direct dependency or a transitive dependency is missing or incorrectly resolved in your `node_modules`.
fixRun `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.
Audit
Dependencies
No dependency data recorded yet.