5.1.0 • Published 5d ago

@ensdomains/ensjs

Licence

MIT

Version

5.1.0

Deps

Size

2.1 MB

Vulns

Weekly

Stars

158

Summary Dependency Versions

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

Package	Description
`@ensdomains/ensjs`	Main library — actions, clients, utils
`@ensdomains/ensjs-abi`	ABI snippets for every ENS contract (v1 + v2)
`@ensdomains/ensjs-react`	React hooks built on `@wagmi/core`
`@ensdomains/ensjs-query-core`	`@wagmi/core` query integration

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:

Package	Needed for
`graphql`	`@ensdomains/ensjs/subgraph`
`@ensdomains/dnsprovejs` (`^0.5.4 \|\| ^1.0.0`)	`getDnsImportData` from `@ensdomains/ensjs/dns`

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.

Import	Contents
`@ensdomains/ensjs`	`addEnsContracts`, error classes
`@ensdomains/ensjs/public`	Shared read actions (resolution, records, reverse, price, availability)
`@ensdomains/ensjs/public/v1`	v1-specific reads
`@ensdomains/ensjs/public/v2`	v2-specific reads
`@ensdomains/ensjs/wallet`	Shared write actions (commit, register, renew, set individual records)
`@ensdomains/ensjs/wallet/v1`	v1-specific writes (wrap/unwrap, fuses, subnames, transfer, `setRecords`, primary name)
`@ensdomains/ensjs/wallet/v2`	v2-specific writes
`@ensdomains/ensjs/subgraph`	Subgraph client + queries (`getSubnames`, `getNamesForAddress`, history, …)
`@ensdomains/ensjs/dns`	DNS helpers (`getDnsOwner`, `importDnsName`, `getDnsImportData`, …)
`@ensdomains/ensjs/utils`	Coders (`getAddress`, `getText`, `getAbi`, `getContentHash`), name utils
`@ensdomains/ensjs/utils/v2`	v2 utils (role encoding, resolver resources, canonical IDs)
`@ensdomains/ensjs/contracts`	Re-exports of ABI snippets
`@ensdomains/ensjs/chain`	Chain types and helpers (`ChainWithEns`, `extendChainWithEns`, `getChainContractAddress`)

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.