@viem/anvil

AnvilJS

TypeScript wrapper for Foundry Anvil. AnvilJS provides a simple API to create and manage Anvil instances programmatically.

import { createAnvil } from "@viem/anvil";

const anvil = createAnvil({
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});

await anvil.start();
await anvil.stop();

Install

pnpm add @viem/anvil

npm i @viem/anvil

yarn add @viem/anvil

Note Anvil is required to use @viem/anvil. Please refer to the foundry book for Anvil installation instructions.

API

createAnvil

Creates anvil instance.

Name	Description	Type
options	Options used to create anvil instance	CreateAnvilOptions
returns	Anvil instance	Anvil

Usage

import { createAnvil } from "@viem/anvil";

const anvil = createAnvil({
  // All anvil options are supported & typed.
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});

await anvil.start();
await anvil.stop();

getVersion

Get anvil version.

Name	Description	Type
command	Path to anvil command. Default anvil.	string
returns	anvil version	string

Usage

import { getVersion } from "@viem/anvil";

const version = await getVersion();

createProxy

Creates and starts a proxy server that spawns anvil instance on demand (e.g. per test file or per test case).

Name	Description	Type
options	Options used to create proxy server.	CreateProxyOptions
returns	Server instance	Server

Usage

import { createProxy, createPool } from "@viem/anvil";

const server = await createProxy({
  pool: createPool(),
  options: {
    forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
    forkBlockNumber: 12345678n,
  },
});

server.listen(8545, "::", () => {
  console.log("Proxy server listening on http://0.0.0.0:8545");
});

createPool

Creates pool of anvil instances.

Name	Description	Type
options	Options used to create pool.	CreatePoolOptions
returns	Pool	Pool

Usage

import { createPool } from "@viem/anvil";

const pool = createPool();
await pool.start(1, {
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});
await pool.start(2, {
  forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
  forkBlockNumber: 12345678n,
});

startProxy

Creates and starts a proxy server that spawns anvil instance on demand (e.g. per test file or per test case).

Name	Description	Type
options	Options used to spawn anvil instance.	StartProxyOptions
returns	Function to shut down the proxy and all spawned anvil instances.	() => Awaitable<void>

Usage

import { startProxy } from "@viem/anvil";

// Returns a function to shut down the proxy and all spawned anvil instances.
const shutdown = await startProxy({
  port: 8555,
  options: {
    forkUrl: "https://eth-mainnet.alchemyapi.io/v2/<API_KEY>",
    forkBlockNumber: 12345678n,
  },
});

// Shut down the proxy and all spawned anvil instances.
await shutdown();

fetchLogs

Fetches logs for anvil instances.

Name	Description	Type
url	URL to anvil proxy.	string
id	ID of test worker.	number
returns	Logs of anvil instance.	string[]

Usage

import { fetchLogs } from "@viem/anvil";

const logs = await fetchLogs("http://localhost:8545", 1);
// Only print the 20 most recent log messages.
console.log(...logs.slice(-20));

Types

import type {
  Anvil,
  AnvilOptions,
  AnvilProxyOptions,
  AnvilProxyOptionsFn,
  CreateAnvilOptions,
  CreateProxyOptions,
  CreatePoolOptions,
  Pool,
  ProxyRequestContext,
  ProxyRequestHandler,
  ProxyResponse,
  ProxyResponseFailure,
  ProxyResponseSuccess,
  StartProxyOptions,
} from "@viem/anvil";

Contributing

If you're interested in contributing, please read the contributing docs before submitting a pull request.

Authors

• @fubhy (fubhy.eth, Twitter)

License

MIT License