The ultimate ENS JavaScript library, with viem under the hood.

ENSjs is a TypeScript library for interacting with the Ethereum Name Service. It provides tree-shakeable, composable actions on top of viem, with first-class support for both ENS v1 and ENS v2.

Features

• Composable actions that extend any viem Client
• Full tree-shaking — pay only for the actions you import
• Multicall batching for read actions
• TypeScript-first, with strict types for chain contracts
• ENS v1 + ENS v2 support side by side
• Subgraph and DNS helpers included
• Standalone @ensdomains/ensjs-abi package for ABI snippets

Monorepo layout

Supported chains: mainnet (1) and sepolia (11155111).

Installation

pnpm add @ensdomains/ensjs viem

You'll also need viem ≥ 2.9.2 as a peer dependency. Some features need optional peer dependencies:

Getting started

addEnsContracts extends a viem chain with all ENS contract addresses and subgraph URLs, so you can use it with any viem createPublicClient / createWalletClient.

import { http, createPublicClient } from 'viem'
import { mainnet } from 'viem/chains'
import { addEnsContracts } from '@ensdomains/ensjs'
import { getAddressRecord, getRecords } from '@ensdomains/ensjs/public'

const client = createPublicClient({
  chain: addEnsContracts(mainnet),
  transport: http(),
})

const eth = await getAddressRecord(client, { name: 'ens.eth' })
const records = await getRecords(client, {
  name: 'ens.eth',
  texts: ['com.twitter', 'avatar'],
  contentHash: true,
})

Entry points

The @ensdomains/ensjs package is split into subpath exports so bundlers can drop everything you don't import.

ABIs themselves are published as a standalone package and can be imported directly:

import { permissionedRegistryGetStateSnippet } from '@ensdomains/ensjs-abi/v2/permissionedRegistry'
import { ethRegistrarControllerRegisterSnippet } from '@ensdomains/ensjs-abi/v1/ethRegistrarController'

Action pattern

Every action is a plain function that takes the viem Client first and parameters second.

const result = await actionName(client, {
  /* params */
})

Read actions use getAction + readContract / multicall so they work with whatever batching configuration is on the client. Write actions return a transaction hash and accept the standard viem write parameters (account, chain, gas, etc.).

Development

# Install
pnpm install

# Build everything
pnpm -r build

# Build a single package
pnpm -F @ensdomains/ensjs build
pnpm -F @ensdomains/ensjs-abi build

# Lint (Biome)
pnpm lint

# Type check
pnpm -F @ensdomains/ensjs check:types

# Test the main package
pnpm -F @ensdomains/ensjs test
pnpm -F @ensdomains/ensjs test:watch
pnpm -F @ensdomains/ensjs test src/actions/public/resolver/getRecords.test.ts

# Generate the markdown docs
pnpm -F @ensdomains/ensjs generateDocs

# Versioning (changesets)
pnpm chgset:run
pnpm chgset:version

Tests run against a local devnet with the ENS contracts deployed and test names seeded (ghcr.io/ensdomains/contracts-v2), so Docker needs to be running. test starts the devnet via packages/ensjs/compose.yml and stops it afterwards. If one is already running on localhost:8545, it's reused:

docker compose -f packages/ensjs/compose.yml up -d devnet

Node ≥ 22 is required for the main packages (≥ 18 for query-core). Tooling: pnpm 12, TypeScript strict mode, Biome for formatting and linting, Vitest for tests.

Contributing

See CONTRIBUTING.md for guidance on adding new actions, wiring up new ABI snippets, registering new contract addresses, and the test conventions used across the repo.

Docs

Guides and the API reference live under docs/. The API reference is generated from the source JSDoc with pnpm -F @ensdomains/ensjs generateDocs.

License

MIT