Registry / devops / strapi-plugin-migrate

strapi-plugin-migrate

library3.6.3jsnpmunverified

A plugin for Strapi CMS that facilitates content migration between environments, including user roles and permissions. Current stable version is 3.6.3, with irregular releases. Key differentiators include support for migrating Strapi's built-in user-permissions data and handling of relational content. Competes with Strapi's native transfer features, but offers a simpler migration path for non-Enterprise users.

devops

npm install strapi-plugin-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STRAPI-PLUGIN-MIGR

strapi-plugin-migrate

devopsjavascriptv3.6.3

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.

migrate

✓ import migrate from 'strapi-plugin-migrate/strapi-server';

✗ const migrate = require('strapi-plugin-migrate');

Use the server-side entry point for Strapi admin panel registration.

migrateConfig

✓ import { config } from 'strapi-plugin-migrate';

Named export for configuration object.

migrateTypes

✓ import type { Migration } from 'strapi-plugin-migrate/dist/types';

✗ import { Migration } from 'strapi-plugin-migrate';

Type exports are under /dist/types for TypeScript projects.

default export (plugin)

✓ export default { bootstrap, config } from 'strapi-plugin-migrate';

Plugin registration file exports a default object.

Shows how to configure and run a migration between two Strapi instances, including entity mapping.

// strapi.config.admin.auth.providers import migrate from 'strapi-plugin-migrate/strapi-server'; const config = { migrations: [ { name: 'MoveContent', from: { url: 'https://source-strapi.com', token: process.env.SOURCE_API_TOKEN ?? '' }, to: { url: 'https://target-strapi.com', token: process.env.TARGET_API_TOKEN ?? '' }, collections: ['article', 'category'], entityMapping: { 'article': { author: { type: 'email' } } } } ] }; export default { config, bootstrap: ({ strapi }) => { // Plugin bootstrap } };

Debug

Known issues

gotchaEntity mapping syntax changed between 2.x and 3.x. The 'type' field is now required.

fix

Update entity mapping to use { fieldName: { type: 'string' } } format.

affects: >=3.0.0

deprecatedThe collection() and singleType() methods are deprecated; use collections array instead.

fix

Replace collection('article') with collections: ['article'] in config.

affects: >=3.5.0

gotchaAuthentication tokens must have full API access; tokens with limited permissions cause silent failures.

fix

Generate tokens with 'find' and 'create' permissions on all content types.

affects: >=3.0.0

breakingIn v3, the plugin no longer supports migrating users and roles by default; a separate config is needed.

fix

Add 'includeUsersAndRoles: true' to migration configuration.

affects: >=3.0.0

gotchaWhen migration fails, the plugin does not rollback automatically; data may be partially migrated.

fix

Manually review and cleanup target before retrying.

affects: all

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'forEach')

Missing or invalid migration config object

fix

Ensure migration config has a 'migrations' array with valid entries.

Error: Entity mapping format invalid. Expected object with type.

Using old v2 format for entity mapping

fix

Use format: { field: { type: 'string' } } or other valid type.

TypeError: strapi.plugins.migrate is not a function

Plugin not properly registered or installed

fix

Run npm install strapi-plugin-migrate and add to config/plugins.js.

401 Unauthorized: Invalid token

API token is invalid or lacks required permissions

fix

Generate new token with full content-type permissions in Strapi admin.

Upgrade

Version history

3.6.3latest on npm

Audit

Dependencies

strapi-plugin-migraterequiredPlugin runs inside a Strapi application; Strapi version >=4.x required

Agent activity

13 hits · last 30 days

node

Resources

githubgit://github.com/ijsto/strapi-plugin-migrate ↗

packagestrapi-plugin-migrate ↗

homepagehttps://github.com/ijsto/strapi-plugin-migrate#readme ↗