Why ensforge
See what ensforge does for you when you work with ENS, and when a smaller tool such as viem alone is the better choice for you.
ensforge is the SDK for ENS. You ask for a name, an address, a record or a registration, and ensforge does the work in between: it finds the right contracts, reads them in as few requests as possible, plans and checks every write, and tells you exactly what went wrong when something fails.
Everything works the same for every name
ENS has grown over the years. Names can live in different places, be held in different ways, and have their records on-chain or on a server. ensforge hides those differences: one call works for every name.
Example (Reading Two Very Different Names)
import { Ensforge, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());
const nick = await ens.record.getAddress({ name: "nick.eth" });
const jesse = await ens.record.getAddress({ name: "jesse.base.eth" });nick.eth keeps its records on Ethereum. jesse.base.eth is a Basename whose records live off
Ethereum and are fetched through a gateway. The call and
the result type are the same. Writes work the same way: record.set, name.transfer and
subname.create pick the right contracts for the name you pass.
See How a lookup works. For the details ensforge handles under the hood, see ENS versions under the hood.
Typed errors with a code for every failure
Every error ensforge throws has a class, a stable code, a link to its own page and, when
ensforge knows one, a hint to fix it. Every
action declares the errors it can throw, so TypeScript knows them too.
Example (Branching on an Error Code)
import { Ensforge, Errors, ensActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const ens = Ensforge.create({
publicClient: createPublicClient({ chain: mainnet, transport: http() }),
}).extend(ensActions());
try {
await ens.record.getText({ name: "unregistered-example.eth", key: "url", strict: true });
} catch (error) {
if (Errors.hasCode("RESOLVER_NOT_FOUND")(error)) {
console.log(error.hint, error.docsUrl);
}
console.log(Errors.describe(error).title);
}Errors.hasCodenarrows the error to the codes you name.Errors.describeturns any error into a title, message and suggested action you can show to users, soerror.message(written for developers) stays out of your UI.
See How errors work.
Writes you can inspect before sending
Many ENS tasks take more than one transaction. Registering a name approves a payment, commits, waits at least a minute, then registers (commitment). ensforge turns every write into a plan you can look at, simulate, estimate and save before anything is signed.
- Every write is simulated before the wallet prompt, so a write that would fail throws a typed error and sends nothing.
- Wallets that support atomic batches (EIP-5792) get each step's calls as one bundle.
- A plan that stops halfway, because of a rejection or a closed tab, resumes where it stopped with
plan.resume.
See How writes work.
Built on viem, shaped like viem
ensforge takes the viem clients you already have and returns plain values: 0x addresses as viem
Address, amounts as bigint. The API is Promise-based, with one options object per call, as in
viem. Apps on wagmi create the client from their wagmi config in one line.
See Create a client.
Pay only for what you import
Every action is a separate function, and the package has no side effects, so bundlers drop what you do not import. Two ways of importing keep a bundle small:
Actions.record.getText(client, options): one action, no client methods.recordActions()instead ofensActions(): only therecordmethods on the client.
The repository checks these sizes on every change. As of release 1.0, Actions.record.getText alone
costs about 41 kB gzipped and a client with ensActions() about 106 kB, viem excluded.
See Ways to call actions and Keep bundles small.
More than lookups
ensforge covers the whole of ENS from one client:
- Lookups: addresses for any chain, text records, avatars, websites, primary names.
- Registration and renewal of
.ethnames, records, subnames, transfers and primary names on L2s. - Permissions: who can do what with a name, before they try.
- Lists, search and history through an indexer.
- React hooks in
@ensforge/react, and an optional Effect API for Effect programs.
When to use something else
ensforge is not always the right tool. Choose something smaller when:
- You only show a name or an address. viem's built-in ENS actions (
getEnsAddress,getEnsName,getEnsAvatar,getEnsText) cover simple lookups with nothing more to install. - Every kilobyte matters on one page. One ensforge action is about 41 kB gzipped on top of viem, because ensforge runs on Effect internally. viem's ENS actions are smaller.
- You need lists or search but no chain access. Lists of names come from an indexer, not from the chain. If that is all you need, the indexer's own API may be enough.
- Your runtime cannot load ES modules. ensforge needs Node.js 20.19 or later, or a bundler. See Installation.
Moving from another library? See From viem and From ensjs.
Was this page helpful?