Content Manager Layout Synchronization#

syncLayouts reconciles persisted Content Manager layout configurations against the current content-type or component schema on every Strapi server bootstrap. Its job is to keep the stored list and edit view layouts consistent with the live schema — adding newly created fields, dropping removed or invalid ones, and handling field type changes — without reordering fields that were placed intentionally by an admin.

Where it lives#

Call chain#

On every server start, bootstrap.ts calls 1:

bootstrap
  → components.syncConfigurations()
  → content-types.syncConfigurations()
      → configurationService.syncConfigurations()
          → syncConfiguration(conf, schema) [per content-type/component]
              → syncLayouts(conf, schema) ← this article

syncConfiguration returns a merged object of { settings, layouts, metadatas } 2, so syncLayouts only owns the layout slice.

What syncLayouts does#

The function signature is syncLayouts(configuration, schema) 3. Its logic, in order:

1. Empty guard — if configuration.layouts is empty, returns createDefaultLayouts(schema) immediately 4.

2. List layout cleanup — filters the stored list array down to attributes that still pass isListable(schema, attr) 5. Removed or non-listable fields are dropped silently.

3. editRelations backward compatibility — legacy configurations stored relation fields separately in editRelations; these are migrated into elementsToReAppend so they are re-inserted at the end of the edit layout 6. The TODO comment marks this for removal in V5.

4. Edit layout row-by-row validation — each {name, size} element in the stored edit rows is checked:

   • Fields whose attribute no longer exists in the schema (fails hasEditableAttribute) are dropped 7.
   • Fields whose type changed (e.g. string → json) and whose stored size is now disallowed by the new type's size rules are moved to elementsToReAppend instead of being kept in-place 8. This prevents invalid row layouts.
   • Valid fields are kept in their original row position 9.

5. Re-appending displaced fields — appendToEditLayout adds the accumulated elementsToReAppend to the end of the cleaned edit layout, using the field's default size and the MAX_ROW_SIZE = 12 grid constraint 10 11.

6. New attributes — fields present in schema.attributes but absent from configuration.metadatas are considered new. They are appended to the list (up to DEFAULT_LIST_LENGTH = 4) and to the edit layout 12.

7. Fallback — if either cleaned layout is empty after all processing, the corresponding createDefault*Layout is used 13.

Layout data model#

• List layout (list): a flat string[] of attribute names shown in the content-manager list view. Capped at 4 items by default 14.
• Edit layout (edit): a Row[][] — an array of rows, each row an array of {name: string, size: number} objects. Sizes are integers summing to at most MAX_ROW_SIZE = 12 per row 15.

Field size rules#

Field sizing is delegated to the field-sizes service 16. Each field type has a default size and an isResizable flag. Non-resizable fields (e.g., json) must always use their fixed size; placing them at a stored size that differs triggers removal and re-append.

Custom fields use their registered customField key for size lookup rather than their base type 17. This is exercised in the custom field size test.

Tests#

layouts.test.ts covers three scenarios: default generation from empty config, appending a new field to an existing layout, and correct sizing for custom fields.