|
| 1 | +# Buidler to Hardhat plugin migration guide |
| 2 | + |
| 3 | +This is a short guide explaining how to turn a Buidler plugin into a Hardhat one. |
| 4 | + |
| 5 | +## Updating its dependencies |
| 6 | + |
| 7 | +### Core package |
| 8 | + |
| 9 | +References to the `@nomiclabs/buidler` package should be replaced with the `hardhat` package in your `package.json`, and your `import`s or `require`s. |
| 10 | + |
| 11 | +For example, you would import the `extendEnvironment` function this way: |
| 12 | + |
| 13 | +```typescript |
| 14 | +import { extendEnvironment } from "hardhat/config"; |
| 15 | +``` |
| 16 | + |
| 17 | +### Plugins |
| 18 | + |
| 19 | +Similarly, references to buidler plugins should be replaced with their corresponding hardhat plugins. |
| 20 | +For example, `@nomiclabs/buidler-ethers` would be `@nomiclabs/hardhat-ethers`. |
| 21 | + |
| 22 | +## Adapting your plugin's source code |
| 23 | + |
| 24 | +The first change you need to make, is to stop exporting a function in your plugin's `index.ts`. Place your function's body at the top-level of your `index.ts` file. |
| 25 | + |
| 26 | +Then, replace all types or imported names that include `Buidler` with `Hardhat` in your plugin source code. |
| 27 | + |
| 28 | +For example, the `BuidlerRuntimeEnvironment` should be replaced with the `HardhatRuntimeEnvironment`. We suggest using `hre` instead of `bre` as its variable name. |
| 29 | + |
| 30 | +### Artifacts |
| 31 | + |
| 32 | +The `readArtifact` and `readArtifactSync` functions were moved to the `HardhatRuntimeEnvironment` so you must replace their uses like this: |
| 33 | + |
| 34 | +```js |
| 35 | +const tokenArtifact = await hre.artifacts.readArtifact("Token"); |
| 36 | +``` |
| 37 | + |
| 38 | +The artifact format is now supplemented with build information and debug artifacts in Hardhat which allows you to read things like contract symbols. See the [documentation](https://hardhat.org/docs/artifacts) for more information. |
| 39 | + |
| 40 | +## Updating your plugin's tests |
| 41 | + |
| 42 | +Apart from updating types and names, fixture projects need their `buidler.config.js` renamed to `hardhat.config.js`. |
| 43 | + |
| 44 | +### Changes needed to your test projects' config |
| 45 | + |
| 46 | +The compiler configuration is now expected in the `solidity` field instead of `solc`. Note that Hardhat projects allow multiple solidity versions in its compilation pipeline. For more information see its [documentation](https://hardhat.org/docs/compilation). |
| 47 | + |
| 48 | +Besides that, the compiler settings now go inside a `settings` field. For example, a configuration like this: |
| 49 | + |
| 50 | +``` |
| 51 | +module.exports = { |
| 52 | + solc: { |
| 53 | + version: "0.7.2" |
| 54 | + optimizer: { |
| 55 | + enabled: true, |
| 56 | + runs: 200 |
| 57 | + } |
| 58 | + } |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +needs to be replaced with this: |
| 63 | + |
| 64 | +```js |
| 65 | +module.exports = { |
| 66 | + solidity: { |
| 67 | + version: "0.7.2" |
| 68 | + settings: { |
| 69 | + optimizer: { |
| 70 | + enabled: true, |
| 71 | + runs: 200 |
| 72 | + } |
| 73 | + } |
| 74 | + } |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +## Adapting your type extensions |
| 79 | + |
| 80 | +Hardhat introduced a few changes in how type extensions are created and used. |
| 81 | + |
| 82 | +These are the necessary changes to update your plugin. |
| 83 | + |
| 84 | +First, you need rename your `src/type-extenstions.d.ts` file to `src/type-extensions.ts`. |
| 85 | + |
| 86 | +Then, you need to add an `import "./type-extensions";` in your `src/index.ts` file, or the main entrypoint to your plugin as defined in your `package.json`. |
| 87 | + |
| 88 | +### Extending Hardhat types |
| 89 | + |
| 90 | +Hardhat types are meant to be imported from `hardhat/types`, but when extending them, |
| 91 | +you should import them from the module that declares them. |
| 92 | + |
| 93 | +For example, if you want you use the `HardhatRuntimeEnvironment` type, you should import it with: |
| 94 | + |
| 95 | +```typescript |
| 96 | +import { HardhatRuntimeEnvironment } from "hardhat/types"; |
| 97 | +``` |
| 98 | + |
| 99 | +But if you want to extend it, you should import the module that declares it |
| 100 | +instead, which is `hardhat/types/runtime`. |
| 101 | + |
| 102 | +```typescript |
| 103 | +import "hardhat/types/runtime"; |
| 104 | + |
| 105 | +declare module "hardhat/types/runtime" { |
| 106 | + export interface HardhatRuntimeEnvironment { |
| 107 | + newField: number; |
| 108 | + } |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +### Adapting your config extensions |
| 113 | + |
| 114 | +Config types are handled slightly differently in Hardhat. |
| 115 | + |
| 116 | +For each config element/type, there's two Typescript types defined. One |
| 117 | +that ends with `UserConfig`, that represents the user's input, and another |
| 118 | +one that ends with just `Config`, which represents the configuration values |
| 119 | +after any resolution and default values have been applied. The first kind of |
| 120 | +types is used by users when writing their config. The second one is used |
| 121 | +during the execution of tasks, tests and scripts, and is present in the |
| 122 | +Hardhat Runtime Environment. |
| 123 | + |
| 124 | +For example, `HardhatUserConfig` represents the entire config written by the |
| 125 | +user, and all of its fields are optional. `HardhatConfig`, is the result |
| 126 | +of resolving/normalizing it, and applying default values. None of its fields |
| 127 | +are optional. |
| 128 | + |
| 129 | +Some types have been renamed to match this new pattern: |
| 130 | + |
| 131 | +- `ProjectPaths` is now `ProjectPathsUserConfig` |
| 132 | +- `Networks` is now `NetworksUserConfig` |
| 133 | +- Both have their resolved versions: `ProjectPathsConfig` and |
| 134 | + `NetworksConfig`, respectively. |
| 135 | + |
| 136 | +You can find an example of how to properly extend these types, |
| 137 | +resolve/normalize the users's config, and apply default values in the |
| 138 | +`src/type-extensions.ts` and `src/index.ts` files. |
| 139 | + |
| 140 | +### How type extensions are loaded in Hardhat |
| 141 | + |
| 142 | +Previously, type extensions were loaded by plugin users by adding references to a plugin-owned `type-extensions.d.ts` in their `tsconfig.json`. |
| 143 | + |
| 144 | +Now, they're loaded automatically when importing the plugin in a hardhat config file. For example: |
| 145 | + |
| 146 | +```typescript |
| 147 | +import "@nomiclabs/hardhat-ethers" |
| 148 | +``` |
| 149 | + |
| 150 | +This is enough to import the type extensions included in the `@nomiclabs/hardhat-ethers` plugin. |
| 151 | + |
| 152 | +## Adapting your `README.md` |
| 153 | + |
| 154 | +Make sure to update the README to point to the new Hardhat site (https://hardhat.org), and that the Typescript Support section has been updated. |
0 commit comments