Viem: TypeScript Interface for Ethereum

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... not supported.

  cause Attempting to `require()` an ESM-only Viem module in a CommonJS environment.
  fix Migrate your project to use ES Modules (set `"type": "module"` in `package.json` and use `import` statements) or use a bundler that correctly handles ESM-to-CJS transpilation.

• Cannot read properties of undefined (reading 'chainId')

  cause The client was initialized without a `chain` property or an invalid chain object was provided.
  fix Ensure `createPublicClient` or similar client creation functions are called with a valid `chain` object, e.g., `chain: mainnet` imported from `viem/chains`.

• A BigInt can not be serialized as JSON.

  cause Attempting to `JSON.stringify` an object containing a native JavaScript BigInt without a custom replacer. Viem uses native BigInts for large number handling.
  fix When serializing data that may contain BigInts (e.g., for logging or API responses), provide a custom replacer function to `JSON.stringify` that converts BigInts to strings: `JSON.stringify(obj, (key, value) => typeof value === 'bigint' ? value.toString() : value)`.

• Error: Version mismatch, found 'typescript@X.Y.Z', expected 'typescript@>=5.0.4'

  cause Your project's installed TypeScript version does not meet Viem's peer dependency requirement.
  fix Install a compatible TypeScript version: `npm install typescript@^5.0.4 -D` or `yarn add typescript@^5.0.4 -D`.

Warnings

• breaking Viem is an ESM-first library. Projects using CommonJS (require()) may encounter compatibility issues, especially with older Node.js versions or specific bundler configurations.
  Fix: Ensure your project uses ES Modules (`'type': 'module'` in `package.json`) and modern build tools. If CJS is unavoidable, consider dynamic `import()` or dual-package setups, though this adds complexity.
• gotcha The `typescript` peer dependency requires version `>=5.0.4`. Using an older version may lead to `npm ERESOLVE` warnings or compilation errors due to incompatible type definitions or language features.
  Fix: Upgrade your project's TypeScript version to `5.0.4` or newer: `npm install typescript@^5.0.4 -D` or `yarn add typescript@^5.0.4 -D`.
• deprecated In `viem/tempo`, `withFeePayer` has been deprecated in favor of `withRelay`. This change impacts how transaction relaying is configured and used.
  Fix: Update your `viem/tempo` configurations to use `withRelay` instead of `withFeePayer` for transaction relay functionality.
• gotcha While Viem includes internal retry logic for RPC calls, aggressive rate limiting from some providers (e.g., Alchemy returning `HTTP 200` with `{ code: 429 }` in JSON-RPC body) can still cause failures, especially in batch mode.
  Fix: Implement robust error handling and backoff strategies at the application level. Consider upgrading your RPC provider plan or distributing requests across multiple providers if high throughput is critical.

Install

• npm install viem npm
• yarn add viem yarn
• pnpm add viem pnpm

Imports

• createPublicClient, http
  wrong:

  const { createPublicClient, http } = require('viem');

  correct:

  import { createPublicClient, http } from 'viem';

  Viem is an ESM-first library. While CommonJS imports might work in some transpiled environments, native ESM is recommended for optimal compatibility and tree-shaking.
• mainnet
  wrong:

  const { mainnet } = require('viem/chains');

  correct:

  import { mainnet } from 'viem/chains';

  Chain definitions are imported from the `viem/chains` submodule. Use ES Modules.
• parseAbi

  import { parseAbi } from 'viem';

  Use named imports for core utilities like `parseAbi` which are essential for ABI interactions.
• Address, Hash, Hex

  import type { Address, Hash, Hex } from 'viem';

  Always use `import type` for type-only imports to ensure they are stripped during transpilation, preventing runtime issues and improving build performance.

Quickstart

This quickstart demonstrates how to create a public client, connect to the Ethereum mainnet using an HTTP transport, and fetch the current block number. It highlights Viem's core client creation pattern and basic data fetching.

import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

const client = createPublicClient({
  chain: mainnet,
  transport: http(process.env.ETHEREUM_RPC_URL ?? 'https://rpc.ankr.com/eth')
});

async function getBlockNumber() {
  try {
    const blockNumber = await client.getBlockNumber();
    console.log(`Current block number: ${blockNumber}`);
    return blockNumber;
  } catch (error) {
    console.error('Failed to get block number:', error);
    throw error;
  }
}

getBlockNumber();