Structure Sync
Exports and imports structural content (taxonomy terms, custom blocks, menu links) as configuration for synchronization across environments.
structure_sync
Install
composer require 'drupal/structure_sync:^2.0'
Overview
Structure Sync addresses a common challenge in Drupal development: synchronizing content that is structural in nature but stored as content entities rather than configuration. While Drupal's Configuration Management system handles configuration entities like content types and views, it doesn't manage content entities such as taxonomy terms, custom blocks, and menu links.
This module bridges that gap by providing both an administrative interface and Drush commands to export these structural content items to a configuration file (structure_sync.data.yml). The exported data can then be committed to version control and imported on other environments, enabling consistent structural content across development, staging, and production sites.
The module supports three different import modes: Full (creates new items, updates existing ones, deletes items not in config), Safe (only creates new items without modifying or deleting existing ones), and Force (deletes all existing items and recreates them from config). This flexibility allows teams to choose the appropriate synchronization strategy for their workflow.
Features
- Export taxonomy terms from all or selected vocabularies to configuration, including custom fields and hierarchical parent-child relationships
- Export custom blocks (block_content entities) with all their field values to configuration
- Export menu links with full metadata including link options, weights, expanded state, and parent relationships
- Import content with three distinct modes: Full (sync), Safe (additive only), Force (destructive recreate)
- Drush command integration for CI/CD pipeline automation and scripted deployments
- Selective export/import allowing granular control over which vocabularies, blocks, or menus to synchronize
- UUID-based entity matching ensures consistent identification across environments
- Handles entity reference fields in taxonomy terms by storing name/vocabulary pairs instead of IDs
- Optional logging of all export/import operations for audit trails
- Batch processing for large imports to prevent timeouts
- Automatic cache clearing after imports to ensure changes take effect immediately
Use Cases
Multi-environment deployment workflow
When developing a site with multiple environments (local, development, staging, production), use Structure Sync to ensure taxonomy terms, menu structures, and reusable blocks are consistent. On your development environment, create and organize your terms, menus, and blocks, then run 'drush export:all' followed by 'drush config:export'. Commit the resulting structure_sync.data.yml to your repository. On staging/production, pull the changes and run 'drush config:import' followed by 'drush import:all --choice=full' to synchronize the structural content.
Initial site setup with predefined structure
When building a new site that requires a specific taxonomy structure (e.g., categories, tags, regions), create all terms on a development site, export them, and include them in your site's installation profile or configuration. New installations will have the complete taxonomy structure available immediately after running configuration import and structure sync import.
Content staging with selective synchronization
Use the Safe import mode when you want to add new structural content from development to production without affecting existing content that may have been modified. This is useful when production has additional terms or menu items created by content editors that shouldn't be removed.
Site migration and cloning
When cloning a site or migrating between hosting providers, Structure Sync ensures that structural content is preserved and can be restored. Export all structural content before migration, and after setting up the new environment with configuration, import the structural content to fully restore the site's organization.
CI/CD pipeline integration
Integrate Structure Sync into your continuous deployment pipeline. After configuration imports complete, run 'drush import:all --choice=full' to ensure structural content is synchronized automatically. This eliminates manual steps and ensures consistent deployments.
Team collaboration with shared structural content
In team development environments, Structure Sync allows team members to share taxonomy structures, menu configurations, and reusable blocks through version control. When one developer creates new terms or menu items needed for a feature, they export and commit, and other developers can import to get the same structure.
Tips
- Always run 'drush config:export' after exporting structural content to save the structure_sync.data configuration to files
- Use Safe import mode when first syncing to a production site to avoid accidentally deleting user-created content
- For complete synchronization, use Full import mode which updates existing items and removes items not in config
- The Force import mode is useful for development resets but should be used with extreme caution on production sites
- Export and import order matters: taxonomies should generally be imported before content that references them
- Custom blocks must have the block type (bundle) already configured before import - this is handled by regular config import
- After importing menu links, clear caches to ensure menus display correctly: drush cache:rebuild
- Consider enabling logging during initial setup to track what the module is doing, then disable for production performance
- The module flushes all caches automatically after taxonomy and menu link imports to ensure changes are visible
Technical Details
Admin Pages 4
/admin/structure/structure-sync/general
Configure global options for the Structure Sync module. Currently provides control over whether operations are logged to the Drupal watchdog.
/admin/structure/structure-sync/taxonomies
Export and import taxonomy terms across all vocabularies. Supports hierarchical terms with parent-child relationships and custom fields attached to terms.
/admin/structure/structure-sync/blocks
Export and import custom block content (block_content entities). Handles all fields attached to block types including body content and custom fields.
/admin/structure/structure-sync/menu-links
Export and import menu link content items. Preserves menu hierarchy, link options, weights, and enabled/expanded states.
Permissions 1
Drush Commands 8
drush export:taxonomies
Export all taxonomy terms to configuration. Exports terms from all vocabularies with their fields, hierarchy, and metadata.
drush import:taxonomies
Import taxonomy terms from configuration. Prompts for import style (Full, Safe, or Force) unless specified via option.
drush export:blocks
Export all custom blocks (block_content entities) to configuration including all field values.
drush import:blocks
Import custom blocks from configuration. Prompts for import style unless specified via option.
drush export:menus
Export all menu link content items to configuration with full metadata and hierarchy.
drush import:menus
Import menu links from configuration. Prompts for import style unless specified via option.
drush export:all
Export all structural content (taxonomies, blocks, and menu links) to configuration in one operation.
drush import:all
Import all structural content (taxonomies, blocks, and menu links) from configuration. Prompts for import style once, applies to all content types.
Troubleshooting 7
You must export content first before importing. Run 'drush export:taxonomies' (or blocks/menus) and then 'drush config:export' to save the data to configuration files.
The vocabulary configuration must be imported before taxonomy terms can be imported. Run 'drush config:import' first to import vocabulary definitions, then run the structure sync import.
Menu links with parent references require the parent to exist first. Structure Sync handles this by sorting links and creating parents before children. If issues persist, try the Force import style to recreate the entire menu structure.
Only fields with names starting with 'field_' are exported. Base fields and computed fields are excluded. Ensure your custom fields follow Drupal's field naming convention.
Large imports use Drupal's batch API to prevent timeouts. If using the web UI and still experiencing timeouts, use Drush commands instead which have no web server timeout limitations.
Safe import mode only checks for existing terms by name and vocabulary combination. If you need to update existing terms, use Full import mode instead. Force mode will delete all existing terms first.
Structure Sync handles term reference fields specially by storing name/vid pairs instead of TIDs. The module runs a second pass after initial import to resolve these references. If issues persist, run the import again.
Security Notes 4
- The module requires 'administer site configuration' permission, which is a powerful permission that should only be granted to trusted administrators
- Exported configuration may contain sensitive information if blocks contain private content - review structure_sync.data.yml before committing to public repositories
- Force import mode deletes all existing content of that type - use with extreme caution and ensure backups exist
- The module trusts the integrity of the configuration files - ensure your deployment pipeline validates configuration before import