{"id":12363,"library":"viem","title":"Viem: TypeScript Interface for Ethereum","description":"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.","status":"active","version":"2.48.1","language":"javascript","source_language":"en","source_url":"https://github.com/wevm/viem","tags":["javascript","eth","ethereum","dapps","wallet","web3","typescript"],"install":[{"cmd":"npm install viem","lang":"bash","label":"npm"},{"cmd":"yarn add viem","lang":"bash","label":"yarn"},{"cmd":"pnpm add viem","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Viem leverages advanced TypeScript features for strong type inference from ABIs and EIP-712 typed data.","package":"typescript","optional":true}],"imports":[{"note":"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.","wrong":"const { createPublicClient, http } = require('viem');","symbol":"createPublicClient, http","correct":"import { createPublicClient, http } from 'viem';"},{"note":"Chain definitions are imported from the `viem/chains` submodule. Use ES Modules.","wrong":"const { mainnet } = require('viem/chains');","symbol":"mainnet","correct":"import { mainnet } from 'viem/chains';"},{"note":"Use named imports for core utilities like `parseAbi` which are essential for ABI interactions.","symbol":"parseAbi","correct":"import { parseAbi } from 'viem';"},{"note":"Always use `import type` for type-only imports to ensure they are stripped during transpilation, preventing runtime issues and improving build performance.","symbol":"Address, Hash, Hex","correct":"import type { Address, Hash, Hex } from 'viem';"}],"quickstart":{"code":"import { createPublicClient, http } from 'viem';\nimport { mainnet } from 'viem/chains';\n\nconst client = createPublicClient({\n  chain: mainnet,\n  transport: http(process.env.ETHEREUM_RPC_URL ?? 'https://rpc.ankr.com/eth')\n});\n\nasync function getBlockNumber() {\n  try {\n    const blockNumber = await client.getBlockNumber();\n    console.log(`Current block number: ${blockNumber}`);\n    return blockNumber;\n  } catch (error) {\n    console.error('Failed to get block number:', error);\n    throw error;\n  }\n}\n\ngetBlockNumber();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Viem is an ESM-first library. Projects using CommonJS (require()) may encounter compatibility issues, especially with older Node.js versions or specific bundler configurations.","severity":"breaking","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your `viem/tempo` configurations to use `withRelay` instead of `withFeePayer` for transaction relay functionality.","message":"In `viem/tempo`, `withFeePayer` has been deprecated in favor of `withRelay`. This change impacts how transaction relaying is configured and used.","severity":"deprecated","affected_versions":">=2.47.18"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` an ESM-only Viem module in a CommonJS environment.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported."},{"fix":"Ensure `createPublicClient` or similar client creation functions are called with a valid `chain` object, e.g., `chain: mainnet` imported from `viem/chains`.","cause":"The client was initialized without a `chain` property or an invalid chain object was provided.","error":"Cannot read properties of undefined (reading 'chainId')"},{"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)`.","cause":"Attempting to `JSON.stringify` an object containing a native JavaScript BigInt without a custom replacer. Viem uses native BigInts for large number handling.","error":"A BigInt can not be serialized as JSON."},{"fix":"Install a compatible TypeScript version: `npm install typescript@^5.0.4 -D` or `yarn add typescript@^5.0.4 -D`.","cause":"Your project's installed TypeScript version does not meet Viem's peer dependency requirement.","error":"Error: Version mismatch, found 'typescript@X.Y.Z', expected 'typescript@>=5.0.4'"}],"ecosystem":"npm"}