Single Content Sync

A comprehensive content export/import module that allows exporting any content entity with all its entity references to YAML format and importing it to another environment.

single_content_sync
12,368 sites
76
drupal.org
gui api utility
content export import sync migration YAML deployment content staging entity reference multilingual
Drupal 9 Drupal 10 Drupal 11

Install

Drupal 11, 10, 9 v1.4.14
composer require 'drupal/single_content_sync:^1.4'

Overview

Single Content Sync provides an easy and powerful way to export and import content entities between different Drupal environments. The module exports content in YAML format, including all referenced entities such as media, taxonomy terms, paragraphs, and files.

Key capabilities include exporting single content items with their complete entity reference tree, supporting translations, bulk export operations via Views Bulk Operations, and automated import during deployments via hook_update_N. The module features a plugin system for extending support to custom entity types and field types, along with events for customizing the export/import process.

Content is identified by UUID, allowing existing content to be updated and new content to be created during import. The module can export as a single YAML file (with file URLs as absolute paths) or as a ZIP archive containing all file assets.

Features

  • Export any content entity (nodes, media, taxonomy terms, blocks, etc.) to YAML format with all entity references
  • Import content from YAML or ZIP files via admin UI, programmatically, or Drush commands
  • Automatic recursive export of all referenced entities including paragraphs, media, files, and taxonomy terms
  • Translation support - export and import all translations of multilingual content
  • Bulk export multiple content items at once using Views Bulk Operations
  • ZIP export option includes all file assets (images, documents, videos)
  • UUID-based content synchronization - updates existing content or creates new
  • Site UUID validation to prevent accidental import to wrong environments
  • Plugin system for custom entity type and field type support via SingleContentSyncBaseFieldsProcessor and SingleContentSyncFieldProcessor plugins
  • Event system (ExportEvent, ImportEvent, ExportFieldEvent, ImportFieldEvent) for customizing export/import behavior
  • Drush commands for command-line export/import operations
  • Configurable export modes for embedded entities and menu links (none, stub, or full)
  • Export tab on entity canonical pages for quick single-entity export
  • Support for Layout Builder sections, Paragraphs, Metatag, Webform, and many contrib field types
  • Intelligent handling of internal links in formatted text fields - resolves entity references during import

Use Cases

Content staging between environments

Export content from a development or staging environment and import it into production. Use the ZIP export option to include all file assets. The site UUID check can be disabled if moving content between different site instances, or enabled to ensure content only moves between cloned environments.

Content backup and restoration

Export important content items as YAML files stored in version control or backup storage. Content can be restored by importing the YAML file, with the UUID ensuring the original content is updated rather than duplicated.

Automated deployment of default content

Store content YAML/ZIP files in a custom module's assets folder and import them during deployment using hook_update_N or hook_deploy. Example: \Drupal::service('single_content_sync.importer')->importFromFile($module_path . '/assets/homepage.yml');

Multilingual content synchronization

Export content with the 'Include all translations' option to capture all language versions. When imported, translations are recreated maintaining the same language relationships.

Bulk content export via Views

Use Views Bulk Operations with the 'Export content' action to select and export multiple content items at once. Useful for exporting specific content sets like all articles in a category or all products.

Content migration from another Drupal site

Export content from a source Drupal site and import into a target site. Disable site UUID check when importing. The module handles entity reference resolution, creating stub entities for missing references.

Drush-based content sync in CI/CD

Use drush content:export and drush content:import commands in automated deployment pipelines. Export content during build phase and import during deployment, ensuring consistent content across environments.

Custom entity type support

Implement a SingleContentSyncBaseFieldsProcessor plugin for custom entity types to enable export/import support. The plugin defines how base fields are exported and mapped during import.

Custom field type support

Implement a SingleContentSyncFieldProcessor plugin for custom or contrib field types not supported out of the box. The plugin handles field value transformation during export and entity creation during import.

Tips

  • Use ZIP export when content includes files (images, documents) to ensure all assets are included and properly imported.
  • Enable Site UUID check in production to prevent accidental content overwrites from non-cloned environments.
  • Use the 'stub' export mode for embedded entities to reduce export file size while maintaining reference integrity.
  • Store exported YAML files in your custom module's assets folder for deployment-time content import.
  • Use Drush commands with --dry-run option first to preview what will be exported without creating files.
  • Subscribe to ImportEvent to add custom validation or transformation logic before content is saved.
  • Use the bulk export action with Views to export filtered content sets (e.g., all published articles from 2024).
  • When creating custom field processor plugins, extend SingleContentSyncFieldProcessorPluginBase for base functionality.
  • The YAML editor in export/import forms provides syntax highlighting - use it to quickly review content structure.
  • For complex migrations, consider combining this module with core Migrate for more control over the process.

Technical Details

Admin Pages 3
Single Content Sync Settings /admin/config/content/single-content-sync

Configure which entity types and bundles can be exported, set the export mode for embedded entities and menu links, and configure the file storage schema for import/export operations.

Import content /admin/content/import

Import content from another environment by uploading a YAML or ZIP file, or by pasting YAML content directly. Content is checked by UUID - existing content is updated and new content is created.

Export /{entity_type}/{entity_id}/export

Export a single content entity to YAML format. The form displays a preview of the exported content and provides options to download as YAML or ZIP file. Dynamic route available on all content entity canonical pages.

Permissions 4
Allow user to export all content

Grants access to export any allowed content entity type

Allow user to import all content

Grants access to import content via the admin UI

Administer Single Content Sync settings

Grants access to configure module settings including allowed entity types

{Entity type}: Export entity

Dynamic permission generated for each content entity type that has an export link template. Allows fine-grained control over which entity types a user can export.

Hooks 4
hook_content_export_field_value_alter

Alter the field value during export. DEPRECATED in 1.4.0, use SingleContentSyncFieldProcessor plugin or ExportFieldEvent instead.

hook_content_export_entity_alter

Alter the entity base fields during export. DEPRECATED in 1.4.0, use SingleContentSyncBaseFieldsProcessor plugin or ExportEvent instead.

hook_content_import_entity_alter

Alter the entity during import before it is saved. DEPRECATED in 1.4.0, use SingleContentSyncBaseFieldsProcessor plugin or ImportEvent instead.

hook_content_import_field_value_alter

Alter field value during import. DEPRECATED in 1.4.0, use SingleContentSyncFieldProcessor plugin or ImportFieldEvent instead.

Drush Commands 2
drush content:export

Export all content of a given entity type. By default exports all nodes to DRUPAL_ROOT/scs-export directory.

drush content:import

Import content from a YAML or ZIP file at the given path.

Troubleshooting 7
Import fails with 'Content source site has another UUID' error

This occurs when Site UUID check is enabled and content comes from a different Drupal installation. Either disable 'Site UUID check' in the settings at /admin/config/content/single-content-sync, or export from the same site instance.

Entity type not appearing in export options

The entity type must have a canonical URL link template. Check the settings page to ensure the entity type is enabled for export. Custom entity types need to define a 'canonical' link template in their entity definition.

Base fields not exported for custom entity type

Implement a SingleContentSyncBaseFieldsProcessor plugin for your entity type, or use the ExportEvent event subscriber to add custom base field handling. The module displays a warning when base fields are not exportable.

Referenced entities not being created on import

Ensure the referenced entity's bundle exists on the target site. The module creates stub entities for missing references, but the bundle must be defined. Check that all required field types have appropriate field processor plugins.

ZIP import fails with structure error

Ensure the ZIP file does not contain an extra parent directory. YAML files should be at the root of the ZIP, with assets in an 'assets' subfolder. The ZIP should be created by the module's export function.

Files not importing correctly

When importing without ZIP (YAML only), files are referenced by absolute URL. Ensure the source URLs are accessible. For local file transfer, use ZIP export which includes all file assets.

Translations not importing

Ensure the target language is enabled on the target site before import. Check that the 'Include all translations' option was enabled during export. Verify the content type has translation enabled.

Security Notes 6
  • Only grant 'export single content' permission to trusted users as exported content may include sensitive field data.
  • Only grant 'import single content' permission to trusted administrators as import can create/modify any content.
  • Be cautious when disabling Site UUID check as it allows importing content from any source.
  • Exported YAML files may contain sensitive information - store them securely and don't commit to public repositories.
  • The module does not validate file contents during import - ensure ZIP files come from trusted sources.
  • User references in exported content use email addresses which may be considered PII.