Chaos: a little bit of history

As you may know Pixel2HTML is a 100% remote company, with more than 20 developers around the planet, handling an average of more than 50 projects at different scales (from simply email marketing templates to full responsive react web applications) on a monthly basis.

In the beginnings we delegated the kick off of each project to the assigned developer, thus letting her/him to take a lot of decisions about technology, file structure, code compilation and code climate.

Few years ago, when the majority of our projects involved mainly HTML and CSS there wasn’t a big deal bit this work-flow. But today, in the year 2017, with not only HTML/CSS but, PUG, ES6 Javascript, SCSS, several different Front-End Frameworks & JavaScript libraries setting up projects required a bit more of a standardized process to make sure requirements from clients on different projects were mere and also to ensure deployment and provisioning was a bit more organised. Not to mention keeping our team mentally sane throughout the process 😜

Boilerplate Generator: our initial solution

We knew we needed a tool to solve most of the architectural and technological decisions out of the way and let us focus our brain power in other tasks and problems of the project.

Without a set methodology, no much guidelines, no standardised file structure, no naming conventions and delegating these decisions on each new developer we hired look like the start of a never ending problem. We needed to have a securely way to scale operations and code reviews while hiring more developer to handle more and more complex projects with confidence.

So we decided to start the Pixel2HTML Boilerplate Generator to sort that out.

What I mean by Boilerplate Generator is essentially a set of tools and conventions that standardise certain elements of the web development process.

The internal motto was:

We need a simple and easy to use tool that generates a compendium of cascading and connected SCSS files, with some naming conventions, file structure suggestions, some popular frameworks integrations, plug-ins and library scripts that ensure any project worked on by any member of the team will stay on convention, and be simple enough for anyone else to step into and work with at any time.

Huge, right?

Solving problem #1: Foster code consistency across our projects.

As you may already know of the most common, all time and hardest problems of code development is naming conventions. This can make the most zen-like developers spit fire whilst enganging in never ending discussions in the meet-up of your choice. In the Front-end development world we usually see people who places their images on an img folder, and other one that save images into an images folder inside a global assets folder. Other projects store files on the root folder and then that builds onto a build folder, and other peeps use a cleaner structure using the src and dist strategy.

See what I just did there in the last sentence? 😉

We know that there isn’t a standard to solve this problem, so we analyzed hundreds of previously built projects in order to come up with a file structure standard that we could also fit well into our work-flow.

Having a standarised name and file structure convention is one of the benefits from using a boilerplate generator. If when a developer starts a new project, he/she might do things slightly different (this can be something small, like changing the way you layout your HTML, or something huge, like deciding on a overall new naming convention). This can make it extremely difficult for others in the team to follow your work or even for him/her to go back later and remember how things were written at that time. We wanted to use this as an approach to sort out a bit of the technical debt of new hires and also making life easier to QA and other people in the team.

You can obviously say: Yeah but it’s not too bad right? Now try to multiply this problem of having different standards in one project across 20 developers around the world and in 50 projects per month. Think again perhaps?

Solving problem #2: Eliminating Repetition

This is the most basic and understandable reason for developing a front-end boilerplate generator.

As a developer, every time you start to build a new site you need to through several setup steps such as forming the file structure, creating the external CSS files, linking the HTML to the external CSS, importing any JavaScript libraries you use often, setup all the compilation process (we use gulp pipelines for that), etc. Developing a front-end boilerplate generator we eliminate all of this lost time used for this housekeeping/mundane tasks that are almost always the same. We make it extremely easy to start a new site or project:

Just run a command in your preferred CLI: $ yo pixel2html

Solved problem #3: Ensure the automatization on code building and delivery.

In case you did not know, we work with a Continuous Integration system that rebuilds on each commit our demo servers so that the client can see the changes day by day in order to generate feedback and arrive at a better product.

Standardizing the build and deploy process was also a task in which the necessary process standards had to be reached in order for the task to be 100% automatic and specially, fault-tolerant.

Solved problem #4: Reduce the time to onboarding new developers to our way to build sites for our clients.

Growing up hurts, and hiring developers around the world can be a problem. From the moment a developer becomes a candidate, we do a code test that allows us to see how much they know and how they would adapt to our workflow.

One of the requirements of the test is to use Pixel2HTML Generator, which enables us to test if you have the ability to use a tool that you do not know and also to introduce the tool in the daily work for later, if you are hired and start using it.


Besides problem, we found some nice features doing this tool:

We made an Open Source project for the first time.

The idea was initially to make an internal tool based on Yeoman, a great project that makes this task a bliss.

Rapidly the question arose: Why not do this project an Open Source Project? We are big fans of OSS, we use and we collaborate daily with multiple open source projects, but we did not have our own, to improve it, make it 100% usable for any outside of Pixel2HTML and receive feedback / issues that help us to the process.

After some changes that helped to eliminate our footprint, the repository was born in Github and the package was published in npm.

Today the project is available to be used by anyone who wishes to use it, just by typing npm install -g yo generator-pixel2html

We get a lot of Internal and External collaboration

Part of the decision process on standards and naming conventions was initially de facto and then we took feedback from the daily work of our developers to generate a better tool.

Also, this generated that several of them get some interest in improving it, adding features that they felt necessary or generating personal tools that adapt to their workflow.

There are also needs to generate other generators for different technologies such as Shopify Skeleton and the one we plan to launch shortly to generate projects with Next.js


About 2.0 version

After too much internal use and polishing features we arrived at the version 2.0 of Pixel2HTML Generator rewriting all the codebase in Javascript’s ES6 (ECMA Script 6), integrating WebPack for the compilation of JS files and thus establishing the file structure that best suits modern projects.

The future

The next stage of the process is to add to the compilation routines some linting systems to do a static analysis of the code to unify criteria of syntax and code standards that, although we have, we are not measuring exhaustively.

Part of the idea of this process is not only to raise the quality of the code in general, but also to improve the collaborative process between developers working on the same project, something that has been happening more frequently in large and long projects over time.