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.
ProviderEngine
✓ import * as ProviderEngine from 'web3-provider-engine';
// Or for CommonJS:
const ProviderEngine = require('web3-provider-engine');
✗ import { ProviderEngine } from 'web3-provider-engine';
The package exports a default `ProviderEngine` class, but it's a CommonJS module. For ESM, use `import * as` or direct `require` syntax. Direct named import will result in a TypeError.
RpcSubprovider
✓ import * as RpcSubprovider from 'web3-provider-engine/subproviders/rpc';
// Or for CommonJS:
const RpcSubprovider = require('web3-provider-engine/subproviders/rpc.js');
✗ import { RpcSubprovider } from 'web3-provider-engine/subproviders/rpc';
Subproviders are also CommonJS modules. Use `import * as` for ESM or `require` for CommonJS. Specific file extensions (`.js`) might be needed in some Node.js ESM environments or bundlers for subpath imports.
HookedWalletSubprovider
✓ import * as HookedWalletSubprovider from 'web3-provider-engine/subproviders/hooked-wallet';
// Or for CommonJS:
const HookedWalletSubprovider = require('web3-provider-engine/subproviders/hooked-wallet.js');
✗ import HookedWalletSubprovider from 'web3-provider-engine/subproviders/hooked-wallet';
Subproviders are CommonJS modules. Named imports (even if they appear to be default in CJS) are not directly supported with `import Name from 'module'` in ESM. Use `import * as` or `require`.
This quickstart demonstrates how to initialize `Web3 ProviderEngine`, configure a stack of diverse subproviders including caching, filtering, a mocked wallet, and an Infura-based RPC data source. It then connects the engine to a `Web3.js` instance, showcases basic event handling for new blocks, and makes a sample `eth_chainId` RPC request, emphasizing the modular design and the requirement for an Infura API key since version 16.0.0.
const ProviderEngine = require('web3-provider-engine');
const CacheSubprovider = require('web3-provider-engine/subproviders/cache.js');
const FixtureSubprovider = require('web3-provider-engine/subproviders/fixture.js');
const FilterSubprovider = require('web3-provider-engine/subproviders/filters.js');
const VmSubprovider = require('web3-provider-engine/subproviders/vm.js');
const HookedWalletSubprovider = require('web3-provider-engine/subproviders/hooked-wallet.js');
const NonceSubprovider = require('web3-provider-engine/subproviders/nonce-tracker.js');
const RpcSubprovider = require('web3-provider-engine/subproviders/rpc.js');
const Web3 = require('web3'); // Ensure web3 is installed: npm install web3
// Create a new ProviderEngine instance
var engine = new ProviderEngine();
// Connect it to a Web3.js instance
var web3 = new Web3(engine);
// Add various subproviders to the engine stack:
// 1. Static results for common RPC methods
engine.addProvider(new FixtureSubprovider({
web3_clientVersion: 'ProviderEngine/v0.0.0/javascript',
net_listening: true,
eth_hashrate: '0x00',
eth_mining: false,
eth_syncing: true,
}));
// 2. Caching layer for RPC results
engine.addProvider(new CacheSubprovider());
// 3. Filter handling for log and block subscriptions
engine.addProvider(new FilterSubprovider());
// 4. Nonce tracking for transaction management
engine.addProvider(new NonceSubprovider());
// 5. Ethereum Virtual Machine (VM) for local execution
engine.addProvider(new VmSubprovider());
// 6. Hooked wallet for identity management and transaction signing
engine.addProvider(new HookedWalletSubprovider({
getAccounts: function(cb){ console.log('getAccounts called'); cb(null, ['0x9E75379dE05C552E5C9A367E9FfF1B9C7e5A83D0']); }, // Placeholder account
approveTransaction: function(cb){ console.log('approveTransaction called'); cb(null, true); }, // Auto-approve for demo
signTransaction: function(cb){ console.log('signTransaction called'); cb(null, '0xf86180808094000000000000000000000000000000000000000080801ba0483c6d860d843825a0a4c0384737d9953835032a76f23e74c1067e812d4d8cae6a053c8c7344933a3889151c76c0e5272a7281c7e949d212a4507119e075c12891'); }, // Placeholder signed tx
}));
// 7. RPC data source (Infura) - requires an API key since v16.0.0
engine.addProvider(new RpcSubprovider({
rpcUrl: 'https://mainnet.infura.io/v3/' + (process.env.INFURA_API_KEY ?? ''), // Replace with your Infura project ID
}));
// Set up event listeners
engine.on('block', function(block){
console.log('================================');
console.log('BLOCK CHANGED:', '#'+block.number.toString('hex'), '0x'+block.hash.toString('hex'));
console.log('================================');
});
// Handle network connectivity errors
engine.on('error', function(err){
console.error('ProviderEngine error:', err.stack);
});
// Start the ProviderEngine
engine.start();
// Example usage: Make a simple request using web3.js
web3.eth.getChainId().then(chainId => {
console.log('Successfully connected to Chain ID:', chainId);
}).catch(error => {
console.error('Failed to get Chain ID:', error);
});
// Keep the process alive for a short period to observe block events
// In a real application, you would manage engine lifecycle based on usage.
setTimeout(() => {
console.log('Stopping ProviderEngine after 30 seconds.');
engine.stop();
}, 30000);
Errors
Common errors & fixes
TypeError: ProviderEngine is not a constructor
This error typically occurs when attempting to import `ProviderEngine` using named ESM import syntax (e.g., `import { ProviderEngine } from 'web3-provider-engine';`) in an ESM module, but the package is a CommonJS module with a default export.
fixFor CommonJS modules, use `require` syntax: `const ProviderEngine = require('web3-provider-engine');`. For ESM compatibility, use the `import * as` syntax: `import * as ProviderEngine from 'web3-provider-engine';`. Error: Invalid JSON RPC response: {"jsonrpc":"2.0","error":{"code":-32003,"message":"project ID is required"}}
Using `RpcSubprovider` to connect to Infura after `web3-provider-engine` v16.0.0 without providing a valid Infura API key.
fixEnsure you have an Infura API key and include it in the `rpcUrl` configuration for `RpcSubprovider`, e.g., `rpcUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID'`.
Node.js version must be ^16.20 || ^18.16 || >=20
Attempting to run `web3-provider-engine` version 17.0.0 or higher on an unsupported Node.js version, as the minimum requirement was increased.
fixUpgrade your Node.js environment to a compatible version (e.g., Node.js 16.20, 18.16, 20, or newer) as indicated in the package's `engines` field.
Audit
Dependencies
web3requiredCommonly used alongside Web3 ProviderEngine to interact with the Ethereum blockchain. Note that Web3.js itself is also in a sunsetting phase as of early 2025.