Transpilex

Context

When I was working at Coderthemes Design LLP, my job was to convert HTML admin templates into different frameworks, around 20 of them. The design team would finish one HTML design, and I had to turn all of its static pages into a project for each framework.

The steps were almost the same every time, only the syntax and the folder structure changed. Still, one framework could take anywhere from 1 to 7 days to finish.

The problem

I was doing the same work again and again: copy the pages, split out the layout and partials, fix every asset path, create the routes and controllers, and then do it all again for the next framework. It was slow, and since it was manual, small mistakes kept slipping in.

How it started

I first wrote a small script for ASP.NET Core and MVC. When I saw that I could automate those two 100%, I kept going and added one framework after another, starting from the easiest.

In the beginning it was more of a helper, because some frameworks could not be finished without manual work. To close that gap, I started creating Cookiecutter templates for the base project of each framework. Transpilex now fills a template with the converted pages, so the output is a complete project that runs.

How it works

It's a Python CLI, published on PyPI. You give it the project name, target framework, UI library, frontend pipeline and the source HTML folder, either as arguments or through interactive prompts. Every framework has its own converter class, and each one knows its file extension, partials path, asset path and how variables are written in its template language.

The supported frameworks are Django, Flask, FastAPI, aiohttp, Laravel, CakePHP, CodeIgniter, Symfony, Yii, core PHP, Node, Ruby on Rails, Spring, Blazor, ASP.NET Core and ASP.NET MVC. Frontend frameworks like React, Next.js or Angular are not part of it, those are handled by Webelix.

The hard parts

Routes, controllers and folder structure

Some frameworks need a route and a controller for every page, in a specific folder structure. I solved this by using the file names together with an array of default names. From a file like apps-calendar.html, it splits the name and creates the route, the folder and the controller for it.

Trade-off: The HTML file names have to follow a naming convention.

Page-specific CSS and JS

Every page should only load the CSS and JS it actually uses, not all of them. I used regex and pattern matching (stored as JSON patterns) to find which assets belong to which page and add them only there.

Trade-off: The patterns need to be updated when a template uses a new way of including assets.

Apart from these two, every framework had its own small problems. I handled those inside that framework's class, with its own functions, so a fix for one framework never breaks another.

Result

A conversion that used to take between 1 and 7 days now takes a few seconds, or a few minutes for big projects. It started as a script to save myself some time and ended up as a tool the whole Webelix workflow depends on.

All the code and the Cookiecutter templates are on GitHub.