Registry / devops / hardhat-migration

hardhat-migration

library1.0.2jsnpmunverified

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.

devops

npm install hardhat-migration

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HARDHAT-MIGRATION

hardhat-migration

devopsjavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

migration

✓ import { migration } from 'hardhat-migration'

✗ const migration = require('hardhat-migration')

ESM-only; CommonJS require will fail at runtime. Plugin is TypeScript-native.

MigrationTask

✓ import { MigrationTask } from 'hardhat-migration'

Named export for defining migration tasks; used in migration files.

migrate

✓ import { migrate } from 'hardhat-migration/tasks'

✗ import { migrate } from 'hardhat-migration'

The migrate task is exported from a subpath to avoid naming conflicts; common mistake to import from root.

Shows setup of hardhat.config.ts with migration path and a simple migration file that deploys a contract.

// hardhat.config.ts import { HardhatUserConfig } from 'hardhat/types'; import 'hardhat-migration'; const config: HardhatUserConfig = { solidity: '0.8.19', migration: { path: './migrations', }, }; export default config; // migrations/1_deploy_contract.ts import { MigrationTask } from 'hardhat-migration'; import { ethers } from 'hardhat'; const task: MigrationTask = async (hre) => { const MyContract = await ethers.getContractFactory('MyContract'); const contract = await MyContract.deploy(); await contract.deployed(); console.log(`Deployed at ${contract.address}`); }; export default task; // Run: npx hardhat migrate --network localhost

Debug

Known issues

breakingMigration files must be TypeScript (.ts) only; JavaScript (.js) files are not supported.

fix

Convert .js migration files to .ts and ensure TypeScript is configured in Hardhat.

affects: >=1.0.0

breakingThe 'hardhat-migration' plugin is ESM-only. Using require() will cause an error.

fix

Use import syntax and ensure your project is ESM or Hardhat is configured for ESM.

affects: >=1.0.0

deprecatedThe 'migrate' import from the main package is deprecated. Use 'hardhat-migration/tasks' instead.

fix

Change import to 'import { migrate } from 'hardhat-migration/tasks'

affects: <1.0.0

gotchaMigration tasks are executed in alphabetical order by filename. Do not rely on numeric prefixes beyond sorting.

fix

Use consistent naming like '001_', '002_' to ensure correct order.

affects: >=1.0.0

gotchaIf you use Hardhat's built-in 'hardhat-deploy', 'hardhat-migration' may conflict with its migrations.

fix

Use only one migration system; remove 'hardhat-deploy' or its migration tasks.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'hardhat-migration'

Plugin not installed or missing from devDependencies.

fix

Run 'npm install --save-dev hardhat-migration' and ensure it's in package.json.

Error: hardhat-migration requires Hardhat >=2.0.0. Current version: 1.x.x

Incompatible Hardhat version installed.

fix

Update Hardhat to version 2.0.0 or higher: 'npm install --save-dev hardhat@^2.0.0'

TypeError: migration is not a function

Importing 'migration' from wrong path. 'migration' is not a default export.

fix

Use named import: 'import { migration } from 'hardhat-migration'

ReferenceError: require is not defined in ES module scope

Using require() in an ESM environment or Hardhat ESM config.

fix

Use import syntax instead of require().

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

hardhatrequiredpeer dependency: required to run as a Hardhat plugin

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/sshmaxime/hardhat-migration ↗

packagehardhat-migration ↗

homepagehttps://github.com/sshmaxime/hardhat-migration ↗