VHS Development for TYPO3

Why the VHS development version is a double-edged sword for TYPO3 agencies

VHS (ViewHelpers Supplementary) is the most comprehensive Fluid extension for TYPO3 with over 300 ViewHelpers. The development version delivers new ViewHelpers and bug fixes before they flow into a stable release. For developers working on current projects and waiting for a specific bug fix or new feature, this is an advantage. For production websites, it is a risk: development versions are not fully tested and can change incompatibly between commits.

The decision to use VHS Development in a project is therefore not technical but organizational: does the team have the capacity to test changes to the library promptly and react when something breaks? And is there the organizational discipline to replace the development version with a stable release before go-live?

Typical use cases

Bug fix access before the next stable release. A project uses the VHS ViewHelper v:format.trim, which has a bug in the stable version - whitespace in multiline strings is not handled correctly. The fix already exists in the development branch, but the next stable release is not planned for 4 weeks. The team temporarily switches to VHS Development to use the bug fix immediately and returns to the stable release afterward.

Evaluation of new ViewHelpers for a relaunch project. A TYPO3 relaunch begins in 3 months. The development team evaluates whether new VHS ViewHelpers (e.g. for responsive image handling or JSON-LD output) can simplify the template code. The development version is installed in a local development environment, tested and the results feed into the architecture decision. If a new ViewHelper is missing from the stable release, the team can plan their own implementation as a fallback in time.

Contributing to VHS development. Agencies that contribute custom ViewHelpers to VHS or report bugs work with the development version to test their patches against the current codebase. Without the development version, meaningful contributing is not possible. Pull requests are opened against the development branch, and only there can the contributor verify that their fix has no side effects.

Technical architecture

VHS Development is not a separate extension but the current development state of the VHS repository on GitHub (FluidTYPO3/vhs). Installation is done via Composer with dev-main or a specific branch:

• composer require fluidtypo3/vhs:dev-main installs the current development state
• composer require fluidtypo3/vhs:dev-feature-xyz installs a specific feature branch
• The minimum-stability setting in composer.json must be set to dev, which affects all packages

VHS itself has the TYPO3 Core (Fluid Template Engine) as its only hard dependency. The over 300 ViewHelpers cover areas such as:

• Content: rendering content elements, FAL access, media handling
• Format: string manipulation, dates, numbers, JSON, Markdown
• Iterator: array operations, sorting, filtering, pagination
• Page: page tree navigation, breadcrumb, sitemap
• Media: image manipulation, video embedding, audio
• Security: access checks, login status, frontend user groups

The development version may contain ViewHelpers whose API is still changing. Parameters may be renamed, return values changed or ViewHelpers removed entirely. In the stable release, the API is frozen. Between two stable releases, the development branch typically changes the signatures of 5 to 15 ViewHelpers. Anyone using these in production templates risks errors after a Composer update.

Common problems and solutions

Composer update breaks existing templates. A composer update pulls the latest development version, in which a ViewHelper parameter has been renamed. All templates using this parameter throw errors. Solution: consistently commit the Composer lock file and install VHS Development with a fixed commit reference: composer require fluidtypo3/vhs:dev-main#abc1234. This prevents the latest version from being automatically pulled.

minimum-stability dev affects other packages. If minimum-stability in composer.json is set to dev, other packages can also install unstable versions. Solution: keep "minimum-stability": "stable" and define VHS Development explicitly as an exception: "fluidtypo3/vhs": "dev-main as 6.99.0". The alias pattern allows installation without a global stability change.

CI/CD pipeline fails with development version. Automated tests and deployments based on Composer installations can fail with the development version if GitHub is temporarily unreachable or the branch was force-pushed. Solution: use a local Composer mirror (Satis) for CI/CD pipelines or switch to the stable release.

Migration and version compatibility

VHS stable releases follow the TYPO3 LTS cycles: VHS 6.x supports TYPO3 v11, VHS 7.x supports TYPO3 v12. The development branch targets the next major version.

Switching from VHS Development back to stable is typically straightforward, provided no ViewHelpers are used that exist only in the development version. Gosign recommends: before switching to stable, check all used VHS ViewHelpers against the stable documentation. The VHS changelog on GitHub lists all changes between development and release.

For TYPO3 v13, a VHS 8.x release is planned. Teams working with the development version today should check their templates for deprecated ViewHelpers. Claus Due and the FluidTYPO3 team typically announce breaking changes in the GitHub milestone.

Gosign recommends the following strategy for handling VHS Development: use the development version on development environments and in feature branches to evaluate new ViewHelpers. Use only stable releases on staging and production. If a critical bug fix is only available in development, pin the specific commit as a Composer reference and leave a TODO comment in the code that surfaces during the next stable release review. This pattern prevents development dependencies from silently reaching production.