Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import migrations from 'ipfs-repo-migrations'
✗ const migrations = require('ipfs-repo-migrations')
This package is primarily designed for ESM consumption, targeting Node.js >=16.0.0. While bundlers can resolve CJS environments, direct `require()` calls in Node.js may lead to incompatibility issues.
Migrations
✓ import type { Migrations } from 'ipfs-repo-migrations'
For TypeScript projects, import the `Migrations` interface to accurately type the default exported `migrations` object, providing full API autocompletion and type safety.
migrate
✓ import migrations from 'ipfs-repo-migrations'; await migrations.migrate(...)
✗ import { migrate } from 'ipfs-repo-migrations'
The `migrate` function is a method of the default exported `migrations` object, not a named export from the module itself. Access it via the imported `migrations` object.
This quickstart demonstrates how to use `ipfs-repo-migrations` to check the current repository version and perform a migration to the latest available version using a mock datastore.
import migrations from 'ipfs-repo-migrations';
import { MemoryDatastore } from 'datastore-core/memory';
import { FsDatastore } from 'datastore-fs'; // Requires 'datastore-fs' package for Node.js
async function runRepoMigration() {
const repoPath = './my-ipfs-repo'; // Define your IPFS repository path
// Choose an appropriate datastore implementation based on your environment.
// FsDatastore is common for Node.js, MemoryDatastore for testing or browsers.
const datastore = process.env.NODE_ENV === 'test'
? new MemoryDatastore()
: new FsDatastore(repoPath); // Ensure 'datastore-fs' is installed for Node.js
const repoOptions = {
path: repoPath, // The path to the repository, often used by the datastore
datastore: datastore, // The underlying storage backend for the repository
root: datastore // The root datastore instance for the IPFS repository
};
try {
// In a real application, you would read the current version from the repo config.
const currentRepoVersion = 7;
const latestVersion = migrations.getLatestMigrationVersion();
console.log(`Current repository version: ${currentRepoVersion}`);
console.log(`Latest available migration version: ${latestVersion}`);
if (currentRepoVersion < latestVersion) {
console.log('Outdated repository detected! Initiating migration...');
await migrations.migrate(repoPath, repoOptions, latestVersion, {
ignoreLock: false, // Set to true with caution; generally, allow locking to prevent corruption
onProgress: (version: number, percent: number, message: string) => {
console.log(`Migration [v${version}]: ${message} (${percent.toFixed(2)}%)`);
},
isDryRun: false // Set to true to simulate the migration without applying changes
});
console.log(`Repository successfully migrated to version ${latestVersion}.`);
} else {
console.log('Repository is already up-to-date or newer. No migration needed.');
}
} catch (error) {
console.error('An error occurred during migration:', error);
// Implement error handling, potentially logging details or attempting a rollback
} finally {
// Ensure that any open datastore connections are properly closed.
if (datastore.close) {
await datastore.close();
}
}
}
runRepoMigration();
Debug
Known issues
breakingVersion 15.0.0 (and related ipfs-repo v17.0.0) introduced a breaking change by updating the `multiformats` dependency to `v11.x.x`. This may require downstream applications to update their `multiformats` usage.fixEnsure your project's `multiformats` dependency is updated to `v11.x.x` or compatible versions. Review `multiformats` changelog for specific API changes if direct usage exists.
affects: >=15.0.0
breakingVersion 14.0.0 (and related ipfs-repo v16.0.0) included a breaking change updating `multiformats` to `v10.x.x` and all `@ipld/*` dependencies. This could impact CID handling and data serialization.fixUpgrade `multiformats` to `v10.x.x` and review `@ipld/*` package versions. Re-encode or re-validate CIDs if your application interacts directly with their internal structure.
affects: >=14.0.0 <15.0.0
gotchaThis package requires Node.js version 16.0.0 or higher. Running in older Node.js environments may lead to compatibility issues or unexpected errors.fixUpgrade your Node.js environment to version 16.0.0 or newer. Use `nvm` or a similar tool to manage Node.js versions.
affects: >=1.0.0
gotchaMigrations for `js-ipfs-repo` often involve significant data transformations. Performing migrations on a live or actively used repository without proper backups can lead to data loss or corruption.fixAlways back up your IPFS repository before running any migration. Consider using the `isDryRun: true` option to test the migration process without committing changes first.
affects: >=1.0.0
Errors
Common errors & fixes
Error: The repo is locked, likely because it is open in another process!
The IPFS repository is currently in use by another IPFS daemon or application, which has placed a lock file to prevent concurrent access and potential data corruption.
fixEnsure no other IPFS processes are running that might be accessing the repository. If you are certain no other process is active, you can try passing `{ ignoreLock: true }` to the migration function, but exercise extreme caution as this can lead to data corruption if another process is indeed active. TypeError: Cannot read properties of undefined (reading 'migrate')
This usually indicates that the `ipfs-repo-migrations` module was imported incorrectly, or the imported `migrations` object is not the expected API object.
fixEnsure you are using the correct ESM import syntax: `import migrations from 'ipfs-repo-migrations'`. If using CommonJS, ensure your bundler correctly handles the import or consider restructuring to use ESM.
ERR_REQUIRE_ESM: require() of ES Module .../node_modules/ipfs-repo-migrations/dist/index.js from ... not supported.
Attempting to `require()` an ES Module (ESM) in a CommonJS context without proper configuration or transpilation. `ipfs-repo-migrations` is primarily an ESM package.
fixConvert your project or relevant files to use ES Modules with `import` statements. Alternatively, if staying with CommonJS, ensure your `package.json` specifies `"type": "module"` for relevant files or use a transpiler like Babel.
Audit
Dependencies
multiformatsrequiredCore dependency for handling CIDs, multicodecs, and other foundational IPFS data structures. Breaking changes in this library often necessitate new repo migrations.
@ipld/*requiredDependencies related to InterPlanetary Linked Data (IPLD) components, which define how data is structured and linked within the IPFS ecosystem. Changes here can affect repo structure.