Skip to main content

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

Comments

Popular posts from this blog

Laravel Project Architecture: The Missing Guide

At my job, we've been doing a lot of learning and development using Taylor Otwell 's Laravel 4 PHP framework.  As we've become more familiar with it, we've had to come up with better ways to structure our projects outside of what the documentation indicates and the default distribution that is provided. If you've been working with Laravel 4 for any amount of time or come with experience from another framework and are just getting started, you've probably noticed that there are a lot of different ways to cut up your projects. Choice is nice, but sometimes it can be paralysing or misleading. Concrete Advice This post is done in such a way that you can just skim the headings, but if you want a detailed explanation in each section, feel free to read in where necessary. While I can't say the entirety of my advice is in practice throughout the community, I can say that we are starting to use it, and to very good effect at my job.  Especially consider

Amazon in Winnipeg?

Late last week, Amazon put word out that they're starting to look for a city to locate a second headquarters .  The fuel this announcement provides has the hype train in Winnipeg going so fast, it's missing stops. I'm curious though.  As you've been digesting this exciting news, who have you spoken or listened to? Was it this guy  and his party's historic theft of public infrastructure (pdf) and incompetence with digital strategy ? Or how about this guy , who maintains that Winnipeg doesn't need a proper rapid transit option ?  You know, the kind that might actually catch the eye of handsome Amazon who now has Winnipeg trying to be the belle of the ball. Transit "system", Peggo glitches are free - thanks  @infidelatheist Runner up articles are  Winnipeg's inability to join the 21st centry on active transport  and the  compounding of the aforementioned digital strategy mistakes . Stop Listening to These Guys They are not technolo

Building .NET Core Nuget Packages

My last blog post was on building and publishing npm packages, specifically for typescript projects. In my opinion, packages are an important fundamental unit in software development. They sit at the confluence of technical competence and collaboration, and represent something the software community should be proud of. Most of the time, you're going to be creating software packages once you're comfortable with some essential pillars: Coding Project structure Software architecture Building Delivery Community Licensing After I got my npm package up and running, my next task was to do the same thing with my C# libraries. Similar to protoculture, I have made a library called praxis .  This is done by leveraging the services and tooling known in the .NET ecosystem as nuget. In this case, praxis abstracts many of the concepts and functionality I require when producing server projects. It builds on top of ASP.NET Core, so in that sense you can almost think of it as