TypeScript
Requirements
Wagmi is designed to be as type-safe as possible! Things to keep in mind:
- Types currently require using TypeScript >=5.0.4.
- TypeScript doesn't follow semver and often introduces breaking changes in minor releases.
- Changes to types in this repository are considered non-breaking and are usually released as patch changes (otherwise every type enhancement would be a major version!).
-
It is highly recommended that you lock your
wagmi
andtypescript
versions to specific patch releases and upgrade with the expectation that types may be fixed or upgraded between any release. - The non-type-related public API of Wagmi still follows semver very strictly.
To ensure everything works correctly, make sure your
tsconfig.json
has
strict
mode set to
true
.
Config Types
By default React Context does not work well with type inference. To support strong type-safety across the React Context boundary, there are two options available:
-
Declaration merging to "register" your
config
globally with TypeScript. -
config
property to pass yourconfig
directly to hooks.
Declaration Merging
Declaration merging
allows you to "register" your
config
globally with TypeScript. The
Register
type enables Wagmi to infer types in places that wouldn't normally have access to type info via React Context alone.
To set this up, add the following declaration to your project. Below, we co-locate the declaration merging and the
config
set up.
Since the
Register
type is global, you only need to add it once in your project. Once set up, you will get strong type-safety across your entire project. For example, query hooks will type
chainId
based on your
config
's
chains
.
You just saved yourself a runtime error and you didn't even need to pass your
config
. 🎉
Hook
config
Property
For cases where you have more than one Wagmi
config
or don't want to use the declaration merging approach, you can pass a specific
config
directly to hooks via the
config
property.
As you expect,
chainId
is inferred correctly for each
config
.
This approach is more explicit, but works well for advanced use-cases, if you don't want to use React Context or declaration merging, etc.
Const-Assert ABIs & Typed Data
Wagmi can infer types based on
ABIs
and
EIP-712
Typed Data definitions, powered by
Viem
and
ABIType
. This achieves full end-to-end type-safety from your contracts to your frontend and enlightened developer experience by autocompleting ABI item names, catching misspellings, inferring argument and return types (including overloads), and more.
For this to work, you must either
const-assert
ABIs and Typed Data (more info below) or define them inline. For example,
useReadContract
's
abi
configuration parameter:
If type inference isn't working, it's likely you forgot to add a
const
assertion or define the configuration parameter inline. Also, make sure your ABIs, Typed Data definitions, and
TypeScript configuration
are valid and set up correctly.
TIP
Unfortunately
TypeScript doesn't support importing JSON
as const
yet
. Check out the
Wagmi CLI
to help with this! It can automatically fetch ABIs from Etherscan and other block explorers, resolve ABIs from your Foundry/Hardhat projects, generate React Hooks, and more.
Anywhere you see the
abi
or
types
configuration property, you can likely use const-asserted or inline ABIs and Typed Data to get type-safety and inference. These properties are also called out in the docs.
Here's what
useReadContract
looks like with and without a const-asserted
abi
property.
You can prevent runtime errors and be more productive by making sure your ABIs and Typed Data definitions are set up appropriately. 🎉