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

Popular posts from this blog

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.


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 technology experts. At worst, they're unabashed self promoters. At best they're conduits for very bad pol…

Making TypeScript npm Packages

If you've landed here, I can only assume you're like me and see packages as the highest form of sophistication in software development.  In that same vein, I bet at some point in the past you've wished you could start applying DRY principles to your client-side efforts.  I know for myself, I don't enjoy writing the same application bootstrap code constantly and so recently, I was motivated to codify it.

This body of understanding has taken me quite some while to figure out, hopefully what I share here is helpful enough to get you up to speed.  No post is complete without some kind of example, so throughout I'm going to reference a package I've just finished putting together called protoculture.

Briefly described, protoculture encapsulates all the common bootstrap and conventions I've been using while developing TypeScript apps that use React and Redux.  Honestly, I've already gotten a lot of benefit out of putting this package together, but nothing about…

The Cons, Winnipeg's New Splash Pads

I never had the chance to be ungrateful, the new splash pad at Kildare and Wabasha isn't a splash pad at all.  It was taken away from us and replaced with an "aquatic park", a little bit of wordsmithing designed to gloss over the fact that an open piece of our community has been replaced with yet another closed gate.

As I write this post now, I can hear it already: "Taken away, what?! It's a new water park, you're so..."
Sure, some might reach for that tired recrimination, which is why I started this blog post by dismissing such a premise.  To be fair however, I offer the response: Don't spoil this discussion with nonsense.
You see, I was grateful before the renovations happened.  The communal service on offer was adequate and I never complained about it or saw it as flawed.  Don't believe me? Here, this is a cute google-generated animation of my son enjoying the splash pad in 2014.

Today we took the kids to see if we could spend some time at th…