ethers-compat

library1.0.0jsnpmunverified

Ethers.js v5/v6 compatibility layer providing a unified API for seamless migration between ethers v5 and v6. Current stable version is 1.0.0. Release cadence is ad-hoc. Key differentiator: write code once that works with both major versions of ethers.js without conditional logic, reducing migration friction. Unlike alternative adapters, it offers a drop-in solution with minimal overhead.

development

npm install ethers-compat

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ETHERS-COMPAT

ethers-compat

developmentjavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CompatibleProvider

✓ import { CompatibleProvider } from 'ethers-compat'

✗ const CompatibleProvider = require('ethers-compat').CompatibleProvider

ESM-only; named export. CommonJS require is not supported.

CompatibleWallet

✓ import { CompatibleWallet } from 'ethers-compat'

Named export. For ethers v5 compatibility, also import 'ethers' separately.

compatVersion

✓ import { compatVersion } from 'ethers-compat'

✗ import compatVersion from 'ethers-compat'

Named export, not default.

ethersCompatible

✓ import { ethersCompatible } from 'ethers-compat'

✗ import { ethersCompatible } from 'ethers'

Utility function to check if ethers version is compatible. Use from this package, not from ethers.

Shows how to create a CompatibleProvider and CompatibleWallet, connect them, and fetch balance in ethers v5/v6 agnostic way.

import { CompatibleProvider, CompatibleWallet, compatVersion } from 'ethers-compat'; async function main() { const provider = new CompatibleProvider('https://mainnet.infura.io/v3/YOUR-PROJECT-ID'); const wallet = new CompatibleWallet(process.env.PRIVATE_KEY ?? ''); const connectedWallet = wallet.connect(provider); const balance = await connectedWallet.getBalance(); console.log('Balance:', balance.toString()); console.log('compatVersion:', compatVersion); } main().catch(console.error);

Debug

Known issues

breakingCompatibleProvider and CompatibleWallet parameters differ between ethers v5 and v6; this library provides unified constructor but underlying API calls may have different signatures.

fix

Refer to ethers v5 vs v6 migration guide for specific method differences not abstracted by this library.

affects: >=1.0.0

gotchaethers-compat does not expose all ethers functionality; only core provider and wallet classes are covered.

fix

If using utilities like formatEther, import directly from 'ethers' instead.

affects: >=1.0.0

deprecatedcompatVersion is deprecated in favor of getCompatVersion() function starting from v2.0.0 (planned).

fix

Use getCompatVersion() instead when upgrading.

affects: >=1.0.0 <2.0.0

Errors

Common errors & fixes

Cannot find module 'ethers-compat' or its corresponding type declarations.

Missing package installation or TypeScript not recognizing module (no types shipped in v1.0.0).

fix

Install ethers-compat: npm install ethers-compat; for TypeScript, add 'declare module "ethers-compat";' or install @types/ethers-compat if available.

TypeError: ethers_compat_1.CompatibleProvider is not a constructor

Using CommonJS require instead of ESM import.

fix

Change to ES module import: import { CompatibleProvider } from 'ethers-compat';

Error: This library requires ethers v5 or v6. Please install one of them.

ethers not installed or incompatible version.

fix

Run: npm install ethers@^5.7.0 or ethers@^6.0.0

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

ethersrequiredpeer dependency - user must have either ethers v5 or v6 installed

Agent activity

59 hits · last 30 days

node

Perplexity

Resources

githubhttps://github.com/ethcompat/ethers-compat ↗

packageethers-compat ↗

homepagehttps://github.com/ethcompat/ethers-compat#readme ↗