viem

library2.48.1jsnpmunverified

Viem is a comprehensive, TypeScript-first interface for interacting with the Ethereum blockchain, designed to simplify dApp development. Currently stable at version 2.48.1, it exhibits a rapid release cadence with frequent patch updates and minor feature additions, reflecting active development. It provides robust abstractions over the JSON-RPC API, first-class APIs for smart contract interaction, and native BigInt support for handling large numbers without external libraries like BigNumber.js. Key differentiators include its deep integration with TypeScript for type inference from ABIs and EIP-712 typed data, strong alignment with official Ethereum terminology, and out-of-the-box support for local development environments such as Anvil, Hardhat, and Ganache. Viem aims to be a lightweight and highly type-safe alternative to other Ethereum libraries, focusing on developer experience and correctness through its strong type system.

http-networking serialization database

npm install viem

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VIEM

viem

http-networkingjavascriptv2.48.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

createPublicClient, http

✓ import { createPublicClient, http } from 'viem';

✗ const { createPublicClient, http } = require('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

✓ import { mainnet } from 'viem/chains';

✗ const { mainnet } = require('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.

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();

Debug

Known issues

breakingViem 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.

affects: >=1.0.0

gotchaThe `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`.

affects: >=1.0.0

deprecatedIn `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.

affects: >=2.47.18

gotchaWhile 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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')

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.

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'

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`.

Upgrade

Version history

2.48.1latest on npm

Audit

Dependencies

typescriptoptionalViem leverages advanced TypeScript features for strong type inference from ABIs and EIP-712 typed data.

Agent activity

24 hits · last 30 days

node