strapi-plugin-content-manager-layout-sync

Strapi v5 plugin that synchronizes Content Manager field order with the order defined in your schema attributes (Content-Type Builder).

Why

When new fields are added in schemas, Content Manager layout can drift and place fields at the end. This plugin reorders layouts to match schema order for:

• Content types (content_types::uid)
• Components (components::uid)

It preserves existing configuration metadata (labels, placeholders, etc.) and only updates layouts.list and layouts.edit for requested UIDs.

Features (MVP)

• Service sync(uid, options)
• Service syncMany(uids, options)
• dryRun mode to return diffs without saving
• apply mode to persist changes
• Secure admin endpoint: POST /content-manager-layout-sync/layout-sync/run
• Dedicated admin action permission: plugin::content-manager-layout-sync.sync
• Admin UI page with:
  • UIDs textarea
  • Dry run toggle
  • Sync now button
  • JSON summary output
• Unit tests for merge/order algorithm

Installation

npm install strapi-plugin-content-manager-layout-sync

Enable it in your Strapi app if needed through plugin resolution.

Permissions

Grant this admin action to roles that can run sync:

• plugin::content-manager-layout-sync.sync

API

Endpoint

POST /content-manager-layout-sync/layout-sync/run

Request body

{
  "uids": ["api::article.article", "shared.hero"],
  "dryRun": true,
  "includeChildren": false
}

• uids optional. If omitted or empty, plugin syncs all non-internal content-types plus all components.
• dryRun optional, default true.
• includeChildren optional, default false. When true, content-type/component seeds also sync nested component UIDs found in component and dynamic zone attributes.

You can also use partial seed values when they resolve uniquely (for example "page" or "hero").

Response example

{
  "dryRun": true,
  "apply": false,
  "total": 2,
  "changed": 1,
  "failed": 0,
  "results": [
    {
      "uid": "api::article.article",
      "kind": "contentType",
      "dryRun": true,
      "applied": false,
      "changed": true,
      "storeKey": "content_types::api::article.article",
      "diff": {
        "list": {
          "changed": true,
          "added": [],
          "removed": [],
          "moved": ["title", "slug"],
          "before": ["slug", "title"],
          "after": ["title", "slug"]
        },
        "edit": {
          "changed": true,
          "added": ["cover"],
          "removed": [],
          "moved": ["title", "slug"],
          "before": ["slug", "title", "body"],
          "after": ["title", "slug", "cover", "body"]
        }
      }
    }
  ]
}

Server service usage

Inside Strapi runtime:

await strapi
  .plugin('content-manager-layout-sync')
  .service('layoutSync')
  .sync('api::article.article', { dryRun: true, apply: false });

await strapi
  .plugin('content-manager-layout-sync')
  .service('layoutSync')
  .syncMany(['api::article.article', 'shared.hero'], { dryRun: false, apply: true });

Behavior and safety defaults

• dryRun defaults to true in endpoint.
• No key deletion in strapi::core-store.
• Only requested UIDs are modified.
• Existing config metadata is preserved.
• Internal UIDs (admin::, strapi::) are excluded from automatic full sync.
• System fields are excluded from final visual layout (id, documentId, createdAt, updatedAt, publishedAt, createdBy, updatedBy, locale, localizations).
• Input validation: max 250 UIDs/request, UID length max 200, and only [a-zA-Z0-9._:-] chars.
• Ambiguous partial UID matching is intentionally not auto-expanded to avoid accidental bulk changes.

Dynamic Zones and Components

• Dynamic Zone fields are regular attributes in the content-type layout and are synchronized when you run sync for that content-type UID.
• Components used inside Dynamic Zones have their own layout config and UID (for example default.hero).
• If you want component layouts synchronized too, run sync for those component UIDs as well, or run with empty uids so syncMany includes all components automatically.

Example request including both content-type and component UIDs:

{
  "uids": ["api::page.page"],
  "dryRun": true,
  "includeChildren": true
}

Limitations

• The plugin synchronizes order and layout rows; it does not redesign custom tabs/advanced custom layouts.
• For unknown/removed fields in existing layouts, sync keeps only schema-backed fields.
• Complex field-size customizations are preserved when valid (1-12).
• For open-source distribution, English UI copy is recommended by default; additional locales can be provided via translations.

Development

npm install
npm run test
npm run build
npm run verify

Publish scripts

npm run release:check
npm pack --dry-run
npm publish --access public

Release checklist

1. Bump version with semver (npm version patch|minor|major).
2. Update CHANGELOG.md.
3. Run npm run release:check.
4. Validate package contents with npm pack --dry-run.
5. Confirm peer dependency compatibility (@strapi/strapi v5).
6. Publish to npm.
7. Tag release in git.

License

MIT