{"id":48131,"library":"hardhat-migration","title":"Hardhat Migration Plugin","description":"Hardhat Migration is a TypeScript plugin for Hardhat that provides a structured migration framework for smart contract deployments. It allows developers to write migrations as TypeScript files, with support for transaction tracking, rollbacks, and network-specific configurations. The current stable version is 1.0.2, released in 2023. It is community-maintained and offers a simple, filesystem-based migration approach, differentiating itself from other deployment tools by focusing on ease of use and TypeScript integration. Peer dependency: Hardhat ^2.0.0.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/sshmaxime/hardhat-migration","tags":["javascript","ethereum","smart-contracts","hardhat","hardhat-plugin","typescript"],"install":[{"cmd":"npm install hardhat-migration","lang":"bash","label":"npm"},{"cmd":"yarn add hardhat-migration","lang":"bash","label":"yarn"},{"cmd":"pnpm add hardhat-migration","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: required to run as a Hardhat plugin","package":"hardhat","optional":false}],"imports":[{"note":"ESM-only; CommonJS require will fail at runtime. Plugin is TypeScript-native.","wrong":"const migration = require('hardhat-migration')","symbol":"migration","correct":"import { migration } from 'hardhat-migration'"},{"note":"Named export for defining migration tasks; used in migration files.","wrong":"","symbol":"MigrationTask","correct":"import { MigrationTask } from 'hardhat-migration'"},{"note":"The migrate task is exported from a subpath to avoid naming conflicts; common mistake to import from root.","wrong":"import { migrate } from 'hardhat-migration'","symbol":"migrate","correct":"import { migrate } from 'hardhat-migration/tasks'"}],"quickstart":{"code":"// hardhat.config.ts\nimport { HardhatUserConfig } from 'hardhat/types';\nimport 'hardhat-migration';\n\nconst config: HardhatUserConfig = {\n  solidity: '0.8.19',\n  migration: {\n    path: './migrations',\n  },\n};\n\nexport default config;\n\n// migrations/1_deploy_contract.ts\nimport { MigrationTask } from 'hardhat-migration';\nimport { ethers } from 'hardhat';\n\nconst task: MigrationTask = async (hre) => {\n  const MyContract = await ethers.getContractFactory('MyContract');\n  const contract = await MyContract.deploy();\n  await contract.deployed();\n  console.log(`Deployed at ${contract.address}`);\n};\n\nexport default task;\n\n// Run: npx hardhat migrate --network localhost","lang":"typescript","description":"Shows setup of hardhat.config.ts with migration path and a simple migration file that deploys a contract."},"warnings":[{"fix":"Convert .js migration files to .ts and ensure TypeScript is configured in Hardhat.","message":"Migration files must be TypeScript (.ts) only; JavaScript (.js) files are not supported.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use import syntax and ensure your project is ESM or Hardhat is configured for ESM.","message":"The 'hardhat-migration' plugin is ESM-only. Using require() will cause an error.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Change import to 'import { migrate } from 'hardhat-migration/tasks'","message":"The 'migrate' import from the main package is deprecated. Use 'hardhat-migration/tasks' instead.","severity":"deprecated","affected_versions":"<1.0.0"},{"fix":"Use consistent naming like '001_', '002_' to ensure correct order.","message":"Migration tasks are executed in alphabetical order by filename. Do not rely on numeric prefixes beyond sorting.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use only one migration system; remove 'hardhat-deploy' or its migration tasks.","message":"If you use Hardhat's built-in 'hardhat-deploy', 'hardhat-migration' may conflict with its migrations.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.2':47 '2.0.0':83 '2023':50 'allow':23 'approach':64 'base':62 'communiti':54 'community-maintain':53 'configur':41 'contract':20,88 'current':43 'depend':81 'deploy':21,69 'develop':24 'differenti':65 'eas':74 'ethereum':85 'file':30 'filesystem':61 'filesystem-bas':60 'focus':72 'framework':17 'hardhat':1,4,11,82,89,91 'hardhat-plugin':90 'integr':79 'javascript':84 'maintain':55 'migrat':2,5,16,27,63 'network':39 'network-specif':38 'offer':57 'peer':80 'plugin':3,9,92 'provid':13 'releas':48 'rollback':36 'simpl':59 'smart':19,87 'smart-contract':86 'specif':40 'stabl':44 'structur':15 'support':32 'tool':70 'track':35 'transact':34 'typescript':8,29,78,93 'use':76 'version':45 'write':26","created_at":"2026-06-07T16:55:04.362822+00:00","updated_at":"2026-06-07T16:55:04.362822+00:00","problems":[{"fix":"Run 'npm install --save-dev hardhat-migration' and ensure it's in package.json.","cause":"Plugin not installed or missing from devDependencies.","error":"Error: Cannot find module 'hardhat-migration'"},{"fix":"Update Hardhat to version 2.0.0 or higher: 'npm install --save-dev hardhat@^2.0.0'","cause":"Incompatible Hardhat version installed.","error":"Error: hardhat-migration requires Hardhat >=2.0.0. Current version: 1.x.x"},{"fix":"Use named import: 'import { migration } from 'hardhat-migration'","cause":"Importing 'migration' from wrong path. 'migration' is not a default export.","error":"TypeError: migration is not a function"},{"fix":"Use import syntax instead of require().","cause":"Using require() in an ESM environment or Hardhat ESM config.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/sshmaxime/hardhat-migration","github":"https://github.com/sshmaxime/hardhat-migration","docs":null,"changelog":null,"pypi":null,"npm":"hardhat-migration","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}