Integrating third party templates with your front end build system

I'm not by definition a front end developer, although because I do back end development, things like program structure and build systems are interesting to me regardless of whether they target servers or browsers.  So while I can't make something look pretty, I still enjoy managing the complexity of JavaScript/ES transpiled apps.

This is a seemingly trivial post in an area that I feel doesn't get enough attention sometimes.

We recently purchased and started using a premade template for some minor projects at work.  It actually looks quite nice, has a responsive layout and isn't too terrible.  My usual complaints of "too much markup" and "lots of busy spaghetti scripting" still hold true, but most of this seems to be quite fire-and-forget.

I ended up not being involved with the first few integrations of the template and while overall it ended up working, any trained eye could see where some of the cut lines were missed.

I had resolved that for the next integration of the template in a new project, we'd do it the right way™!

Module Loaders and Package Managers

In our projects, we use the extremely powerful JSPM dependency and module loader framework.

If you're new to the idea of things like JSPM, DUO, require.js, WebPack or Browserify, you can think of them as tools that help you manage complexity when modularizing browser projects.  Most of it centres around module loading, but is further improved by building dependency graphs, inlining resources, and transpilation.

I think it's very easy for people to get confused by JSPM without realizing that it exists to address two or three very simple concerns that other module loading toolkits gloss over.  Another benefit of JSPM is that it plays nicely with NPM and is future facing.  My advice to anyone struggling with it is to take the time to understand the tool and the goals any developer should have of producing good quality source code.

On top of JSPM, we also use TypeScript so that we can produce nicely structured source code that is easy to collaborate on.  Indeed, it's thanks to JSPM that we can integrate TypeScript so nicely with our workflow.  You can substitute TypeScript for ES6, CoffeeScript or even ES5, the conventions and principles remain overall the same.

Back to the Template

So, looking at the template we used, it turns out to be a great case study for this process.  It has a mix of dependencies that can be found on NPM as well as one small custom script that's been distributed as a minified file.  It also uses SASS for its templates.

Markup

The first and simplest thing we did was derive new base templates from the example markup.  We use Laravel, so this was a piece of cake thanks to blade or twig for templating.

The general rule here is that so long as you play by the conventions they've established for DOM structure, their SASS/CSS should still work.  The template's original HTML files really just end up being your style guide.

Stylesheets

Things start to get a little tricky here because what we want are for the styles to work, but in such a way that the third party template can become part of the build process.  Not just us consuming it as output.  By doing that, if we need to add or change styles from the original template, it won't create additional overhead.

The "right way" - and yes, I do believe there can sometimes be a best-approach to solving problems - to do this was to take the SCSS files that came with the template and to categorize them in the de-facto structure in my Laravel project.

This is great because now anyone familiar with Laravel can be familiar with the template we purchased!  If you examine the image carefully, you'll see that I have a file called dashboard.scss.  Let's take a look and see what's inside!

As you might have been able to guess, it's quite simple!  Because we've given ourselves the entirety of the template's source stylesheets, we can now work with them as a first-class citizen.  This is significantly better than what many people do when shoehorning templates into a site which is to usually end up with two link tags.  One pointing to the original styles, and another pointing to their overrides.  Yuck!

With the dashboard CSS file all set up, building is just a matter of following a normal SASS build flow.  In my Laravel project, that is ideally done using Laravel Elixir, but projects can differ on this. I'm going to leave understanding SASS build flows as outside the scope of this post.

The only thing you should have as an objective - regardless of your environment - is that you are including only one stylesheet.  If you end up with more, you've missed a chance to optimize your workflow and project structure.
If you have multiple interfaces that share styles in common, don't despair.  All you have to do is produce a new SCSS file that includes/inherits from the original root one (in my case dashboard.scss) and then build and include that instead!

Scripts

As I'm sure my introductions above made clear, I'm of the view that getting your scripts set up correctly is a delicate art. You can definitely jump in all gangbusters and start throwing spaghetti at the walls, but that will not make you a professional.  No, I can't tell you that small nests of imperative code, outbreaks of callbacks and global state won't work.  I'm just going to say that I hope you don't end up with a lot of it or having to maintain it.
I've experienced first hand the full list of excuses for not doing clean front end development from day one. Invariably, it's those same people that end up suffering from a lot of friction in their projects only weeks in, confused on why everything has devolved into a mess.

If you've just bought or inherited a template for your project, I'm going to wager the template author did not use a module system for their scripts.  A quarter of the time you might get lucky and they've got bower or NPM set up to barf a bunch of files that they include with script tags.  But even that isn't great.

All of this is a problem.  Maybe not today, but if your solution is successful, you're going to want to get in front of this now before it's too big to justify fixing.  This truncated screenshot should give you an idea of what I'm talking about:

When the page loads, it's going to issue requests for each of these resources and then the sidebar script that came with the template.  Managing these dependencies isn't something you should leave up to markup, it would be much nicer to have tooling set up around it.

The first step to doing that is to get those external dependencies tracked and managed using some kind of tool.  In my case, this will be JSPM:

Of course, you also have Bower, DUO and NPM as alternatives for this which are able to cooperate to varying degrees with other tools. Regardless of what you use, I'm sure you can see, managing your external libraries as dependencies is super easy.

Next, I'm going to skip the step of assembling these dependencies together and I'm going to bring this back to the template.  Just for perspective.

The template I'm talking about here would be the same one that imports the built output of my dashboard.scss file.  Inside this file - and if you're using JSPM, only do this in development mode - the block you end up authoring looks like this:

In my case, this is all just setup for JSPM so that it can do runtime transpiation and dependency loading.  In production, you can minify your output and tell your templating engine to include one file as opposed to four.

What ends up being really nice is the code inside of dashboard.ts:

As you can see, the last file, sidebar.min.js is also included here, and all I've done is move it into a static library directory as part of my project.

Tada!

That's it!  Granted, these steps are very broad strokes, but they should be applicable for a good number of frameworks and environments.

Looking back at the problem I originally described, rather than having a hodge podge of files that are hostile to my project, I've been able to fully integrate them as if they were authored as part of it.

• Whenever I invoke a SASS build, my stylesheets will compile down to single files, including the template's own variables which I now have access to customize under source control
• Whenever I build my front end scripts, they too will compile down to single files which can be delivered quickly as a versioned bundle from a CDN
• I can create any number of derivative builds using native SASS and TypeScript language constructs instead of complex build configurations and markup-controlled dependency loading
• My development flow has not been hampered and my relationship with the template we bought remains the same as it always has been: Adhere to the DOM conventions