{"id":12215,"library":"typechain","title":"TypeChain","description":"TypeChain is a foundational development tool for the Ethereum ecosystem, providing TypeScript bindings for smart contracts. It enables developers to generate static, type-safe interfaces for their Solidity contracts, significantly reducing runtime errors and improving developer experience through autocompletion and compile-time checks. The current stable version is 8.3.2, with frequent patch releases addressing bug fixes and minor updates to support new features or align with major dependency versions (like Ethers.js and Hardhat). TypeChain is highly extensible, supporting various popular web3 libraries and frameworks such as Ethers.js (v5 and v6), Hardhat, Truffle, and Web3.js through dedicated 'targets'. This broad compatibility and its ability to work with both simple JSON ABI files and complex Truffle/Hardhat artifacts distinguish it from more tightly coupled alternatives, making it a ubiquitous tool in professional smart contract development workflows.","status":"active","version":"8.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/ethereum-ts/Typechain","tags":["javascript","ethereum","TypeScript","bindings","smartcontract","blockchain","typescript"],"install":[{"cmd":"npm install typechain","lang":"bash","label":"npm"},{"cmd":"yarn add typechain","lang":"bash","label":"yarn"},{"cmd":"pnpm add typechain","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for type checking and compilation of generated bindings.","package":"typescript","optional":false}],"imports":[{"note":"TypeChain itself is primarily a CLI tool and a build-time generator. The most common 'imports' for users are for the *generated* TypeScript types, which reside in the output directory (e.g., 'typechain-types'). The exact path varies based on your project structure and contract name.","symbol":"GeneratedContract","correct":"import { MyContract } from '../typechain-types/contracts/MyContract'"},{"note":"When using TypeChain with Hardhat, you typically enable the plugin in `hardhat.config.ts`. If your Hardhat config is an ESM file, use `import`. For CommonJS (the default for older Hardhat setups), `require` is correct. This refers to the plugin registration, not importing specific symbols from the plugin.","wrong":"require('@typechain/hardhat')","symbol":"Hardhat plugin enablement","correct":"import '@typechain/hardhat'"},{"note":"This symbol is used for advanced programmatic integration of TypeChain, not typically imported by end-users. Most users rely on the TypeChain CLI or framework-specific plugins (like `@typechain/hardhat`) to invoke TypeChain's generation process.","symbol":"runTypeChain","correct":"import { runTypeChain } from 'typechain'"}],"quickstart":{"code":"import { HardhatUserConfig, task } from 'hardhat/config';\nimport '@nomicfoundation/hardhat-toolbox';\nimport '@typechain/hardhat'; // Import the Hardhat TypeChain plugin\n\nconst config: HardhatUserConfig = {\n  solidity: \"0.8.20\",\n  networks: {\n    hardhat: {\n      chainId: 1337, // Example local network ID\n    },\n  },\n  typechain: {\n    outDir: 'typechain-types', // Output directory for generated types\n    target: 'ethers-v6', // Specify the target library (e.g., ethers.js v6)\n    alwaysConsiderOverloadedFunctions: true,\n  },\n};\n\n// Example Hardhat task demonstrating usage of TypeChain generated types\ntask(\"deploy\", \"Deploys a sample contract\").setAction(async (taskArgs, hre) => {\n  const [deployer] = await hre.ethers.getSigners();\n  console.log(\n    \"Deploying contracts with the account:\",\n    deployer.address\n  );\n\n  // Accessing a generated contract factory type (e.g., Greeter__factory)\n  // Ensure your contract is named 'Greeter.sol' in the 'contracts' directory\n  const GreeterFactory = await hre.ethers.getContractFactory(\"Greeter\");\n  const greeter = await GreeterFactory.deploy(\"Hello, Hardhat!\");\n\n  await greeter.waitForDeployment();\n\n  console.log(`Greeter deployed to ${greeter.target}`);\n\n  // Using type-safe method calls on the deployed contract instance\n  const message = await greeter.greet();\n  console.log(\"Contract message:\", message);\n});\n\nexport default config;\n\n/*\n// Example Solidity contract: contracts/Greeter.sol\n// SPDX-License-Identifier: MIT\n// pragma solidity ^0.8.20;\n// \n// contract Greeter {\n//     string private _greeting;\n// \n//     constructor(string memory greeting_) {\n//         _greeting = greeting_;\n//     }\n// \n//     function greet() public view returns (string memory) {\n//         return _greeting;\n//     }\n// \n//     function setGreeting(string memory greeting_) public {\n//         _greeting = greeting_;\n//     }\n// }\n*/","lang":"typescript","description":"Demonstrates `typechain` integration with Hardhat by configuring the plugin, specifying an Ethers.js v6 target, and then using the generated TypeScript bindings for deploying and interacting with a sample smart contract."},"warnings":[{"fix":"Ensure `typescript` is installed at version `>=4.3.0` in your project's `devDependencies` to meet TypeChain's requirements.","message":"TypeChain requires TypeScript version 4.3 or newer. Using older versions will result in compilation errors or incorrect type generation, as TypeChain leverages modern TypeScript features.","severity":"breaking","affected_versions":"<=8.x.x"},{"fix":"If using Hardhat, add `node16Modules: true` to your TypeChain configuration in `hardhat.config.ts`. If running TypeChain directly, pass the `--node16-modules` CLI flag.","message":"When using the `@typechain/ethers-v6` target with ESM module resolution (e.g., in a Node.js project configured with `type: 'module'`), you must explicitly enable the `--node16-modules` flag or `node16Modules: true` in your configuration for correct output. This ensures proper ESM resolution for the generated types.","severity":"gotcha","affected_versions":">=8.2.0"},{"fix":"Install the correct TypeChain Ethers target (e.g., `npm install --save-dev @typechain/ethers-v6`) and configure your `typechain` settings (`target: 'ethers-v6'`) to align with your project's Ethers.js dependency.","message":"Breaking changes exist between `ethers-v5` and `ethers-v6` TypeChain targets due to significant API differences in Ethers.js. Always ensure that the TypeChain target (`@typechain/ethers-v5` or `@typechain/ethers-v6`) matches the Ethers.js version used in your project to avoid type mismatches and runtime errors.","severity":"breaking","affected_versions":">=8.x.x"},{"fix":"Install all necessary TypeChain target packages as dev dependencies. For example: `npm install --save-dev typechain @typechain/hardhat @typechain/ethers-v6`.","message":"The core `typechain` package provides the generator logic, but framework-specific bindings and integration (e.g., for Hardhat, Truffle, Ethers.js) require installing additional 'target' packages. Failing to install the correct target will prevent TypeChain from generating usable types for your chosen environment.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install --save-dev @typechain/hardhat` to install the plugin. Then, ensure it's imported in `hardhat.config.ts` using `import '@typechain/hardhat';` (for ESM) or `require('@typechain/hardhat');` (for CommonJS).","cause":"The Hardhat TypeChain plugin has not been installed or correctly imported/required in your `hardhat.config.ts`.","error":"Cannot find module '@typechain/hardhat' or its corresponding type declarations."},{"fix":"Verify your `ethers` dependency version (e.g., `ethers@^6.0.0`) and set the TypeChain target accordingly in your `hardhat.config.ts` (e.g., `target: 'ethers-v6'`). Regenerate types after making changes.","cause":"This error typically indicates a mismatch between the Ethers.js version installed in your project and the TypeChain target configured. For instance, using `ethers@^6.0.0` with types generated by `@typechain/ethers-v5`.","error":"Property 'connect' does not exist on type 'BaseContract' (or similar type mismatch errors when interacting with Ethers.js contracts)."},{"fix":"Ensure `@nomicfoundation/hardhat-toolbox` is installed (`npm install --save-dev @nomicfoundation/hardhat-toolbox`) and imported in `hardhat.config.ts`: `import '@nomicfoundation/hardhat-toolbox';`.","cause":"This often occurs if `@nomicfoundation/hardhat-toolbox` or relevant Hardhat plugins (like `@nomiclabs/hardhat-ethers`) are not installed or correctly imported, preventing Hardhat from exposing the `ethers` object on its runtime environment.","error":"TypeError: Cannot read properties of undefined (reading 'getContractFactory') or Property 'ethers' does not exist on type 'HardhatRuntimeEnvironment'."}],"ecosystem":"npm"}