TypeChain is a tool for generating TypeScript typings for Ethereum smart contracts. It helps developers interact with smart contracts in a type-safe manner, reducing runtime errors and improving the development experience.
Generating TypeScript typings for smart contracts
This command generates TypeScript typings for smart contracts using the Ethers.js target. The generated typings are placed in the 'src/types' directory, and the input JSON files are located in the 'artifacts' directory.
npx typechain --target ethers-v5 --out-dir src/types './artifacts/**/*.json'Using generated typings in a TypeScript project
This code demonstrates how to use the generated TypeScript typings in a TypeScript project. It imports the typings for a contract named 'MyContract', interacts with the contract using Ethers.js, and logs the result of calling a method on the contract.
import { MyContract } from './types/MyContract';
async function main() {
const myContract: MyContract = await ethers.getContractAt('MyContract', '0x123...');
const value = await myContract.myMethod();
console.log(value);
}Ethers.js is a library for interacting with the Ethereum blockchain and its ecosystem. While it does not generate TypeScript typings for smart contracts, it provides a comprehensive set of tools for interacting with Ethereum, including contract interaction, wallet management, and more. TypeChain can generate typings specifically for use with Ethers.js.
Web3.js is a collection of libraries that allow you to interact with a local or remote Ethereum node using HTTP, IPC, or WebSocket. Similar to Ethers.js, it does not generate TypeScript typings for smart contracts but provides a wide range of functionalities for interacting with the Ethereum blockchain. TypeChain can also generate typings for use with Web3.js.
Truffle is a development environment, testing framework, and asset pipeline for Ethereum. It provides a suite of tools for developing smart contracts, including compilation, deployment, and testing. While Truffle does not generate TypeScript typings, it can be used in conjunction with TypeChain to provide a complete development workflow.
🔌 TypeScript bindings for Ethereum smartcontracts
Contributed with:
ethers.js, truffle, Web3.js 1.0, Web3.js 2.0 or you can create
your own targetnpm install --save-dev typechain
You will also need to install a desired target for example typechain-target-ethers.
Learn more about targets
| Package | Version | Description |
|---|---|---|
typechain |  | Core package |
@typechain/ethers-v4 |  | Ethers ver 4 support |
@typechain/truffle-v4 |  | Truffle ver 4 support |
@typechain/web3-v1 |  | Web3 ver 1 support |
@typechain/web3-v2 |  | Web3 ver 2 support |
typechain --target=(ethers|truffle|web3-v1|web3-v2|path-to-custom-target) [glob]
glob - pattern that will be used to find ABIs, remember about adding quotes: typechain "**/*.json", examples:
./abis/**/*.abi, ./abis/?(Oasis.abi|OasisHelper.abi)--target - ethers, truffle, web3-v1 or path to your custom target. typechain will try to load package named
typechain-target-${target}, so make sure that desired package is installed.--outDir - put all generated files to a specific dirTypeChain always will rewrite existing files. You should not commit them. Read more in FAQ section.
Example:
typechain --target ethers --outDir app/contracts './node_modules/neufund-contracts/build/contracts/*.json'
Interacting with blockchain in Javascript is a pain. Web3 interface is sluggish and when using it with Typescript it gets even worse. Often, you can't be sure what given method call will actually do without looking at ABI file. TypeChain is here to solve these problems (as long as you use Typescript).
TypeChain is code generator - provide ABI file and you will get Typescript class with flexible interface for interacting with blockchain. Depending on the target parameter it can generate typings for truffle, web3 1.0.0 or ethers.
Install typechain with yarn add --dev typechain and install desired target.
Run typechain --target=your_target (you might need to make sure that it's available in your path if you installed it
only locally), it will automatically find all .abi files in your project and generate Typescript classes based on
them. You can specify your glob pattern: typechain --target=your_target "**/*.abi.json". node_modules are always
ignored. We recommend git ignoring these generated files and making typechain part of your build process.
That's it! Now, just import contract bindings as any other file
import { MyAwesomeContract } from './contracts/MyAwesomeContract' and start interacting with it. We use named exports
because of this.
Use ethers target to generate wrappers for ethers.js lib.
Truffle target is great when you use truffle contracts already. Check out truffle-typechain-example for more details. It require installing typings for truffle library itself.
Now you can simply use your contracts as you did before and get full type safety, yay!
Generates typings for contracts compatible with latest stable Web3.js version. Typings for library itself are now part
of Web3 1.0.0 library so nothing additional is needed. For now it needs explicit cast as shown
here, this will be fixed
after improving official typings.
Generates typings for contracts compatible with (unstable) Web3.js 2.x.x version. Typings for library itself are now
part of Web3 2.0.0 library so nothing additional is needed.
Usage example.
This might be useful when you're creating a library for users of your smartcontract and you don't want to lock yourself into any API provided by Web3 access providing library. You can generate basically any code (even for different languages than TypeScript!) that based on smartcontract's ABI.
For users of 0.x.x versions: the only breaking change is extraction of targets for separate packages so now you need to
install typechain-target-${name} for each target.
A: NO — we believe that no generated files should go to git repository. You should git ignore them and make
typechain run automatically for example in post install hook in package.json:
"postinstall":"typechain"
When you update ABI, just regenerate files with TypeChain and Typescript compiler will find any breaking changes for you.
A: You can create your own target and generate basically any code.
A: We will automatically format generated classes with prettier to match your coding preferences (just make sure to
use .prettierrc file).
Furthermore, we will silent tslint for generated files with /* tslint:disable */ comments.
You may want to use ts-generator api to kick off whole process by api:
import { tsGenerator } from 'ts-generator'
import { TypeChain } from 'typechain/dist/TypeChain'
async function main() {
const cwd = process.cwd()
await tsGenerator(
{ cwd },
new TypeChain({
cwd,
rawConfig: {
files: 'your-glob-here',
outDir: 'optional out dir path',
target: 'your-target',
},
}),
)
}
main().catch(console.error)
yarn # install all dependencies
yarn test # runs tests + linting
yarn test:fix # autofix any errors + run tests
DEBUG=typechain typechain
FAQs
🔌 TypeScript bindings for Ethereum smartcontracts
The npm package typechain receives a total of 256,620 weekly downloads. As such, typechain popularity was classified as popular.
We found that typechain demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Popular npm packages like eslint-config-prettier were compromised after a phishing attack stole a maintainer’s token, spreading malicious updates.
Security News
/Research
A phishing attack targeted developers using a typosquatted npm domain (npnjs.com) to steal credentials via fake login pages - watch out for similar scams.
Security News
Knip hits 500 releases with v5.62.0, refining TypeScript config detection and updating plugins as monthly npm downloads approach 12M.