Last week the creators of Timber, the plugin that enables WordPress theme developers to write HTML using the Twig Template Engine, released version 1.0 on WordPress.org. The plugin is active on more than 10,000 websites where theme authors have elected to keep PHP files separate from HTML. Timber is built on DRY and MVC principles to solve the problem stated in its unofficial tagline: “Because WordPress is awesome, but the_loop isn’t.”
Over the past four years, the open source project has evolved from being a starter theme to a plugin that can be added to existing themes. It is now used on thousands of websites and has 83 contributors listed on GitHub.
“In 2012 I was getting more into WordPress after doing lots of JS development with Handlebars (a JS templating language),” Timber creator Jared Novack said. “I went to WordCamp Providence to learn more about state-of-the-art WordPress ways. I remember thinking: ‘This is great, but I really miss the cleanliness of Handlebars — I wish someone would make something like that for WordPress.’ That’s when I realized, I was that someone.”
“The syntax felt so natural I almost didn’t need to read the docs (don’t worry, I did),” he said. “I realized what I needed was a way to marry Twig and WordPress, and thus: Timber was born.”
At that time Novack’s company, Upstatement, was beginning development on a big new project for Random House to enable their marketers to generate unique sites from a library of templates. This client project became Timber’s first test case.
“Originally, Timber was a parent theme, like _s. But after we completed the Random House project, I realized I wanted to apply Timber functionality to existing sites,” Novack said. “I converted it into a plugin that could be employed on existing themes which is the form it takes today.”
The plugin allows designers skilled with HTML and CSS to create themes without having extensive knowledge of PHP and WordPress functions. Timber successfully powers sites like Michael Bloomberg’s The Trace, Everytown for Gun Safety, Hotel Tonight, and the Harvard Law Review.
As of Timber 1.0, developers can now include the project as a plugin or require it as a Composer dependency.
“The big news is that 1.0 represents a maturing of the platform — developers can use Timber and Twig with confidence that they’re building on top of a stable and universal platform,” Novack said.
This release sheds years of deprecated functions and methods dating back to the project’s early days in 2013. Novack said that technical and documentation debt were the biggest hurdles in getting to 1.0.
“In hindsight it’s so easy to build stuff, but so hard to build a complete system,” he said. “When Timber started it was just for me and the documentation could just live in my head. I’d add and improve stuff and then live with some of the quirks.”
As the project and its contributors grew, Novack found it difficult to keep up with the growing codebase while running his company. Bringing it to a place of maturity with up-to-date automated testing and documentation took nearly a year.
“Backwards compatibility was also a major challenge,” Novack said. “As ideas and new code got submitted, development slowed as every decision might have implications for existing users. We would deprecate features, but I was hesitant to remove things that I knew were mistakes, but that people were using.”
Developers are encouraged to read the 1.0 Upgrade Guide, as there may be additional steps required depending on how Timber is being used. This release adds a few new features but the most important change is the bulk removal of older sections of the codebase. The upgrade guide outlines all of the object properties and static methods that will need to be updated so that nothing breaks. In the future, Timber-powered themes will be easier to maintain, with fewer quirks and better-documented features.
“The key learning for me is that the ultimate ‘killer feature’ is stability and predictability,” Novack said. “When everything is organized cleanly and developers can use the things that they would intuitively expect — that’s success.”