Mask Twig for TYPO3

Why frontend developers prefer Twig over Fluid and how Mask makes it possible

TYPO3 uses Fluid as its template engine - a technology unique within the PHP world. That is simultaneously its strength and its biggest problem: frontend developers coming from the Symfony, Laravel or Node.js ecosystem know Twig or Nunjucks. They do not know Fluid. The mask_twig_nunjucks_connector bridges this gap by letting Mask content elements render with Twig or Nunjucks templates instead of Fluid templates.

For agencies whose frontend team works with Twig and has no desire to learn a new template language for every TYPO3 project, the connector is the pragmatic solution. Existing Twig partials from Symfony projects or Nunjucks components from pattern libraries can be reused directly.

Typical use cases

Agencies with Symfony backend and TYPO3 frontend. An agency develops its web applications in Symfony and uses TYPO3 only for content management. The frontend team has built an extensive Twig component library. Instead of rewriting all components for TYPO3 in Fluid, the connector integrates the existing Twig templates directly into Mask content elements. A header component that exists in Symfony as header.html.twig works in TYPO3 without modification.

Pattern library integration with Nunjucks. A design team maintains a pattern library (e.g. based on Fractal or Storybook) that uses Nunjucks as its template language. The connector allows the same Nunjucks templates to be used both in the pattern library and in TYPO3. Design changes are made once in the pattern library and are automatically visible on the TYPO3 website.

Frontend developer onboarding in TYPO3 projects. A new frontend developer joins a TYPO3 project. Instead of first learning Fluid (syntax, namespaces, ViewHelper concept), they write Twig templates they already master. The project learning curve shrinks from 2 to 3 days to a few hours.

Technical architecture

The mask_twig_nunjucks_connector functions as a rendering bridge between the Mask extension and an alternative template engine. Mask defines custom content elements with backend fields (text, images, relations). By default, Mask renders these elements with Fluid templates. The connector replaces this rendering step.

The technical implementation:

• Twig integration: the connector uses the PHP library twig/twig (the same one Symfony uses). Twig templates are placed in the file system, typically under Resources/Private/Twig/. Mask fields are available as template variables ({{ data.header }}, {{ data.bodytext }}).
• Nunjucks integration: Nunjucks is the JavaScript counterpart to Twig (nearly identical syntax). The connector can render Nunjucks templates server-side via a Node.js bridge or deliver them client-side as JavaScript templates. The server-side variant requires Node.js on the server.
• Variable mapping: Mask fields are automatically mapped to template variables. Simple fields (text, integer, float) are passed directly. FAL references (images, files) are passed as objects with URL, title and alt text. Relations are resolved as arrays.

Dependencies: TYPO3 Core, Mask extension, Composer package twig/twig (for Twig) or Node.js (for server-side Nunjucks). The extension is not available in the official TER but is installed via GitHub/Packagist. The Twig integration is considerably more mature than the Nunjucks variant because Twig runs natively in PHP and requires no external process. In practice, over 90% of connector installations use Twig, not Nunjucks.

Common problems and solutions

Twig template has no access to TYPO3-specific data. Fluid ViewHelpers like f:uri.page, f:translate or f:cObject do not exist in Twig. A Twig template cannot directly access the TYPO3 page tree, translations or other content elements. Solution: all required data must be provided through the variable mapping. The connector can inject additional data (current language, page URL, global settings) into the template context through configuration. For complex TYPO3 functionality, a custom Twig extension point must be written.

Nunjucks rendering is slow. The Node.js bridge for server-side Nunjucks rendering starts a Node process for each request. This is not noticeable with individual content elements, but with pages containing 10+ Mask elements, rendering times add up. Solution: use a persistent Node.js worker process (instead of starting a new one per request) or switch to Twig, which renders natively in PHP and requires no external process.

Mask update breaks template variable names. When Mask renames a field or a field type is changed, template variables change. Fluid templates show empty spots; Twig templates throw errors. Solution: run Twig in strict mode (strict_variables: true) and test templates against the updated variables after every Mask update.

Migration and version compatibility

The mask_twig_nunjucks_connector is a community project with limited adoption. Compatibility depends on the Mask extension: Mask itself is actively maintained and supports TYPO3 v11 and v12. The connector must be checked for compatibility with every Mask update because it hooks into internal rendering processes.

For TYPO3 v13, the long-term perspective is unclear. The TYPO3 community is investing heavily in Fluid development (Fluid 4.0, Standalone Fluid). At the same time, pressure grows from frontend developers who prefer Twig as the template standard.

Gosign recommends the connector for projects where the frontend team works exclusively with Twig and brings an existing component library. For pure TYPO3 projects without external template requirements, Fluid remains the better choice because it is natively supported, has no additional dependencies and can use the entire TYPO3 ViewHelper library. The productivity gain from Twig reuse must outweigh the maintenance effort for the connector - a tradeoff that should be concretely quantified at every project start. With fewer than 10 Mask elements, the connector rarely pays off; with 30+ elements and an existing Twig library, it almost always does.