Keep bundles small
Ship only the ensforge actions you use, with standalone actions, per-domain groups and tree-shaking, to keep your bundle small.
ensActions() adds every action except the indexer group to your client, which is the easiest way to start and the largest
thing to ship. For a browser app that reads one or two values, import the actions you use instead.
Prerequisites
- A bundler that tree-shakes ES modules (Vite, Rollup, esbuild, webpack in production mode).
- Your app already ships
viem. ensforge uses it as a peer and does not bundle it.
What each choice costs
ensforge's CI bundles typical imports with viem excluded and fails when one grows more than 5% over its recorded budget. At the time of writing the recorded sizes are:
| Import | Gzipped size |
|---|---|
Actions.record.getText | about 41 kB |
Ensforge.create(...).extend(ensActions()) | about 106 kB |
ensActions() plus indexerActions() and bigname() | about 128 kB |
The numbers move with each release. The point is the ratio: one action costs well under half of the full client.
Import one action
Every action is a function that takes a client first. Pass a bare viem public client, so you do not create an ensforge client at all.
Example (One read, nothing else)
import { Actions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const url = await Actions.record.getText(publicClient, { name: "nick.eth", key: "url" });Actions is a namespace tree (Actions.record.getText). The package marks itself side-effect free
and ships ES modules built so that bundlers drop every action you do not reference. The flat entry
@ensforge/sdk/actions exports the same tree if you prefer named imports:
import { record } from "@ensforge/sdk/actions";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const address = await record.getAddress(publicClient, { name: "nick.eth" });Standalone actions give up client-wide settings (ccipRead, gateways, plan storage). To keep
them, create a client with Ensforge.create and pass it where you passed publicClient. Creating the
client adds no actions until you extend it.
Add only some groups to a client
When you want ens.record.* methods without the rest, extend the client with the domain groups you
need. Each domain has its own decorator.
Example (Records and names only)
import { Ensforge, nameActions, recordActions } from "@ensforge/sdk";
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const publicClient = createPublicClient({ chain: mainnet, transport: http() });
const ens = Ensforge.create({ publicClient }).extend(recordActions()).extend(nameActions());
await ens.record.getAddress({ name: "nick.eth" });ensActions() is all the domains except indexer, plus batch. Add the indexer group with
indexerActions() only if you use it. See Ways to call actions.
Choose the entry that matches your style
The root entry @ensforge/sdk is the Promise API. @ensforge/sdk/effect is the Effect API, for
programs written with Effect. Import it only where you write those programs. See
The Effect API.
Check the result
Build your app and inspect the output with your bundler's analyzer. A page that reads one record should not contain the registration, migration or indexer code.
Troubleshooting
The bundle still includes every action
Something imports ensActions or the whole Actions object (for example by spreading it or
iterating over it). Reference actions by name. Also check that your bundler is not set to treat
@ensforge/sdk as having side effects.
Was this page helpful?