mask_export for TYPO3

Without mask_export, Mask elements are not versionable and every deployment is a risk

Mask is the standard for custom content elements in TYPO3. But Mask stores its configuration in a JSON file and generates database fields at runtime. In a professional development process with multiple environments (local, staging, production), this creates a problem: how do new content elements get from the development machine to the production server? Manually recreating them in the backend? Copying mask.json via FTP and running Database Compare? Both are error-prone and not reproducible.

mask_export solves this problem. The extension exports all Mask definitions as a standalone TYPO3 extension with its own ext_tables.sql, TCA configurations and Fluid templates. This extension is installed via Composer, versioned through Git and deployed via CI/CD - just like any other TYPO3 extension. This makes Mask enterprise-ready.

Typical use cases

Agencies with CI/CD pipelines. Agencies that deploy TYPO3 projects through GitLab CI, GitHub Actions or Deployer need versionable artifacts. mask_export produces an extension installable via composer require. Every change to a content element creates a new commit that runs through the pipeline: lint, tests, staging deploy, production deploy. No manual backend intervention needed.

Multi-site projects with shared elements. Corporations with 5 to 20 TYPO3 instances (country subsidiaries, brands, affiliates) want to use uniform content elements across all sites. mask_export produces a central extension that is included in all instances. Changes are made once and distributed to all sites. Without mask_export, Mask elements would have to be manually rebuilt on each instance.

Handoff between development and editorial. Developers define content elements on their local system, export them via mask_export and commit the result. Editors work on the staging or production system and use the elements without needing the Mask GUI. The Mask extension itself can even be uninstalled on production systems if only the exported extension is needed.

Technical architecture

mask_export reads mask.json (or config/mask.json since Mask 8) and generates a complete TYPO3 extension. The generated structure contains: ext_emconf.php (extension metadata), ext_tables.sql (database definitions for all Mask fields), Configuration/TCA/Overrides/tt_content.php (TCA configuration), Resources/Private/Templates/ (Fluid templates, copied from the configured Mask template path) and optionally TypoScript setup for frontend rendering.

The export process runs as a TYPO3 CLI command: php typo3/sysext/core/bin/typo3 mask:export. The result is a directory that can be included as a Composer package or as a local extension in typo3conf/ext/. The Mask extension itself is no longer needed after export, as long as no new elements are created or existing ones modified.

Important: mask_export exports only the definition (fields, templates, TCA), not the content (the actual texts, images etc. in tt_content). The data remains in the database and is migrated independently.

Common problems and solutions

Export forgotten after a change. A developer modifies a Mask field on the local system but commits only mask.json, not the new export. On staging, the TCA configuration is then missing. Solution: integrate the mask_export command into a Git hook (pre-commit) or into the CI pipeline. Gosign uses a check in the deployment pipeline that compares whether mask.json and the latest export are in sync.

Fluid templates not included in the export. mask_export copies templates from the configured path by default. If templates reside outside this path (e.g. in a custom theme package), they are not captured. Solution: store all Mask templates in a unified directory and reference it in the Mask configuration.

Conflicts when both Mask and the exported extension are installed. If both Mask and the exported extension are installed on the production system, duplicate TCA registrations can occur. Solution: on systems where editors do not create new elements, install only the exported extension and uninstall Mask. On development systems, both run in parallel, with the export overwriting the previous version.

Migration and version compatibility

mask_export follows Mask’s release cycle: when Mask supports a new TYPO3 version, mask_export is updated promptly. Currently TYPO3 v11, v12 and v13 are supported. The exported extension is compatible with the same TYPO3 version as the Mask version it was generated from.

For projects that want to switch to the native Content Block API on TYPO3 v13, mask_export can serve as an intermediate step: first export Mask elements (clean, file-based structure), then translate the exported TCA configurations into Content Block definitions. The effort per element is low (30 to 60 minutes) when the exported extension serves as reference. Gosign offers this migration path as a standardized service.

An often overlooked advantage of mask_export is testability. When content elements exist as a standalone extension, automated tests can be written: verify TCA configuration (are all fields correctly defined?), test template rendering (does the Fluid template produce valid HTML?) and validate the database schema (do column types match?). In a CI pipeline, such tests catch errors before they reach staging or production. Without mask_export, this kind of testing would only be possible through integration tests against a running TYPO3 instance.

For projects with 20+ Mask elements, Gosign recommends integrating the export process into the development workflow from the start. The initial setup effort (integrate CLI command into CI pipeline, create Git repository for the exported extension, adjust Composer configuration) is approximately 2 to 4 hours. After that, the workflow is fully automated and every Mask change flows into deployment without manual steps. Gosign delivers a preconfigured CI pipeline with mask_export integration as part of every new TYPO3 project setup, so the professional workflow is in place from day one.