JavaScript Best Practices

Maintainable JavaScript — Separate HTML and JavaScript

Spread the love

Creating maintainable JavaScript code is important if want to keep using the code.

In this article, we’ll look at the basics of creating maintainable JavaScript code by looking at loose coupling between JavaScript and HTML.

Keep HTML Out of JavaScript

We should keep our HTML code out of our JavaScript.

Having HTML in our JavaScript code make the app hard to debug when there’re any text or structural issues in our code.

It’s almost impossible to trace issues with dynamic HTML in our JavaScript code.

Therefore, we shouldn’t write code like:

const div = document.querySelector("div");
div.innerHTML = "<h3>Error</h3> <p>Invalid date.</p>";

Embedding HTML strings in our JavaScript is a bad practice.

It complicates tracking down any text or structural issues,

It’s hard to look through the DOM inspector in the dev console of our browser to fund the issue since it’s updated dynamically.

Therefore, it’s harder to work with than tracking down simple DOM manipulation issues.

The 2nd problem is maintainability.

If we need to change the text or markup, we’ve to change the HTML and the JavaScript code to change the text.

This is more work than changing them all in the HTML code.

The markup in JavaScript isn’t accessible for changes.

This is because we don’t expect HTML in our JavaScript code.

It’s much more error-prone to edit markup than it is to edit JavaScript since the markup is in string.

So by putting HTML in our JavaScript code, then we complicate our problem.

There are ways to insert HTML with JavaScript in a loosely coupled manner.

One way is to use some templating system like Handlebars.

For instance, we can write:

<script src=""></script>

  const template = Handlebars.compile("<p>{{firstname}} {{lastname}}</p>");

    firstname: "james",
    lastname: "smith"


We include the Handlebars library and then call Handlebars.compile to return a template function that lets us interpolate expressions in a template string.

If we want to use HTML with Handlebars, we add a special script tag:

<script src=""></script>

<script id="entry-template" type="text/x-handlebars-template">
  <div class="entry">
    <p>{{firstname}} {{lastname}}</p>

Then we can add the following JavaScript to compile the template into HTML:

const source = $("#entry-template").html();
const template = Handlebars.compile(source);
const context = {
  firstname: "james",
  lastname: "smith"
const output = template(context);

The script tag has the text/x-handlebars-template type to distinguish it from a JavaScript script tag.

So we can compile the template into HTML.

The compilation is done by getting the script with jQuery.

Then we call Handlebars.compile to compile the source.

The context has the variables we want to interpolate in our template.

Then we call template with the context to compile the data.

Finally, we call append with the compiled template.

Alternatively, we can use frameworks like Vue, React, or Angular to structure our apps so that we won’t have to worry about mixing HTML and JavaScript is a disorganized way.

The frameworks make us write code in a way that there’s loose coupling between JavaScript and HTML.


We should keep our HTML code out of our JavaScript code.

This way, we won’t have to worry about tracking code that’s hard to debug.

We can separate them with templating systems like Handlebars or use frameworks like Angular, React, or Vue.

By John Au-Yeung

Web developer specializing in React, Vue, and front end development.

Leave a Reply

Your email address will not be published. Required fields are marked *