Forem: Ross Angus

[Boost]

Ross Angus — Tue, 07 Apr 2026 10:29:47 +0000

Ben Sinclair

Mar 25

How to talk to people

#ux #language #relations

Comments 1

4 min read

Mobile tables

Ross Angus — Tue, 07 Oct 2025 14:51:10 +0000

Cover image by Tolga deniz Aran

This is some CSS and JavaScript which allows tables of any size to render on mobile as a simple two-column table, eliminating horizontal scroll.

Note that I didn't invent (or rediscover) this technique - it's an adaptation from where I first encountered it, to take into account edge cases and awkward content.

Don't bore us, get to the chorus:

How this works

Your table doesn't need any specific markup for this to work, in most cases. The JavaScript makes the assumption that the first row describes the rest of the table and attempts to connect every following table cell with its corresponding header cell.

It adds a data-label attribute to the cells, the content of which is a plane text version of whatever appears in the corresponding header.

When it's time for the table to switch to mobile mode, the first row is hidden and the table and its elements are all switched to display: block. This creates a veeeeery long table with just table cells, all the way down.

Inside each table cell are three elements:

A before element, the contents of which is the text within the data-label attribute
One or more elements which actually live inside the table cell. This could be a single text node or a heading and a list: I'm not going to tell you how to fill your table cells
An after element which has your Grandfather's clearfix on it, like it's 2005

Using floats for layout? In the 21st century?

Yeah, I tried a few other methods first. Here's how it went:

Flexbox: worked well until I had multiple paragraphs within the same table cell. Then it started forming multiple columns. Go down that road and you've got yourself another table.
Positioning: worked until the header text wrapped. Then it started getting illegible fast
Grid: no, I didn't try grid. I'll leave that for the professionals.

Floating allows two columns of text to be as long as you like and to sit side by side.

Where this breaks down

As you might have seen from the notes inside the table cells, certain colspan and rowspan combinations are not handled well by the JavaScript. It would be perfectly possible to make them work but ... I couldn't be bothered. It wouldn't be easy to get them to work, which is why I've left it as an exercise for the reader (this is what people say, right?).

Also, as the text which represents the header cell has all the HTML stripped out of it, any markup there will not appear on the mobile version of the table.

Perhaps there's a version of this where instead of data-label attributes, the contents of each cell are wrapped in an element, the contents of each corresponding header cell is placed in a preceding element and these two elements are laid out using flexbox. Seems like a faff, if you ask me.

Workarounds

When I said in most cases above, you can fix the issue above with some added markup. In HTML, it's possible to explicitly associate a table cell with another cell, to show they have a relationship. We do this using the headers attribute.

When the JavaScript is attempting to pull in the correct header data, it checks for a headers attribute first, and uses that in preference to its best guess.

What this means for tables with a lot of rowspan and colspan attributes is that you can ensure the correct content appears on mobile by using the headers attribute. But you only need to do it on cells which appear after the cells which won't stay in their lane. The ones before should work fine.

Native CSS carousels and positioning controls

Ross Angus — Mon, 08 Sep 2025 12:02:30 +0000

Cover image by JessicaChristian

As part of a silly academic exercise I'm working on, I was digging into pure CSS carousels. Like all lovers of plane English, I started with the implementation documented on CSS Tricks.

(Through gritted teeth, at the time of writing this only works on Chrome)

This uses some CSS properties I'd not encountered before - namely anchor-name, position-anchor and position-area.

Let me be candid for a second: this is a small subset of the CSS properties from the article which I'm unfamiliar with. But these three are pertinent to my use-case.

Naturally, I started thinking like a QA engineer and added multiple carousels to my page.

Which is where it stopped working:

It turns out the anchor-name works in a similar way to an ID in that there can only be one per page. Except it's specified in the CSS, not the HTML. And just like with non-validating pages which include multiple IDs of the same value, the browser treats the last one on the page as the real one.

Edit: a solution to this issue

Since writing this post, I've read the documentation at web.dev which describes how to use anchor-scope to address exactly this issue.

Looking at the DOM of the carousel, the answer seemed simple:

<div aria-roledescription="carousel">
  ::scroll-button(inline-start)
  ::scroll-button(inline-end)
  ::scroll-marker-group
  <div role="group" aria-roledescription="slide">
    ...
  </div>
</div>

Give [aria-roledescription="carousel'] a position of relative and position the two ::scroll-buttons using absolute. But that absolutely did not work:

I went around the houses for a bit with this and Cursor (I know, I know...) pointed me at a bunch of new CSS which sort of replicates positioning, but ... not?

This seemed a really dumb problem. The buttons were right there in the markup. Having them render in the correct spot seemed trivial. Then I remembered how my old colleague James described me once: You do interesting things with old technology. So I got rid of all that modern CSS and floated the right button:

It's possible that I've encountered a bug in Chrome's rendering engine here - the DOM and the layout engine disagree with each other. Cursor's only useful contribution to this question was that this happens with bleeding-edge features such as this.

Chapter 8: HTML part three

Ross Angus — Thu, 13 Mar 2025 11:21:14 +0000

Cover image by cottonbro

Recap

Last time, we continued working with PostHTML and did the following:

Learned how to use the picture tag in HTML5
Created a new fragment using the picture tag and passed it a couple of arguments
Wrote some code to rebuild pages in the dist directory when we update them in the src directory
Put the code which calls PostHTML into its own module

We ended last time with some tasks still to do:

Handling changes to fragments
Getting the dist directory set up correctly for Our Hypothetical Second Developer
Adding content inside of modules

At the end of the last chapter, we wrote a watch-html task which used the onchange package to call a script. That script (html-update.js) attempted to call PostHTML and pass it the input and output paths for our HTML file.

This worked well, if the file being updated represented a HTML page. But what if we edit a HTML fragment when the task is watching?

Watching fragments

We don't know how often a particular fragment appears in different HTML pages, so the brute force approach is to rebuild all HTML pages when any single fragment is updated. This isn't ideal for a couple of reasons:

We'll be rebuilding some pages which don't need to be rebuilt
This operation requires a lot of writing to the hard drive of individual files and will be both slow and won't scale well

This is unfortunate and I can't see an easy fix. If we could use browserSync to tell us which page was currently open in the browser, we could just update that page, but that would still leave all the other pages out of date.

Static site builders

While this course will teach you how to build a functional static site using Node.js and other technologies, if you need to build a large, complicated site or application, other technologies might be a better fit. However, the benefit of using this course is that you'll understand every part of the code you put together and you should be able to bolt other technology onto it and upgrade parts of it in the future.

This means we need to write a task which rebuilds all HTML pages. Hmm. This is reminding me a lot of what we did with Sharp.

Generating all HTML

Create a new file called generate-all-html.js inside the tools directory.

It should look like this:

import getFiles from "./get-files.js";
import callPostHTML from "./call-posthtml.js";

const allHTMLPaths = getFiles('./src/views');

allHTMLPaths.map((path) => {
  console.log(path);
  // callPostHTML(something, somethingElse);
});

This is pretty similar to compress-all-images.js, but instead of importing write-images.js, we're importing our new function callPostHTML. Let's see what that console logs when we point it at something.

In a terminal, cancel any currently running commands and type:

node tools/generate-all-html.js

You'll probably see something like this in the terminal:

./src/views/index.html
./src/views/about/index.html

This path is needs a couple of tweaks, to get it in the format which callPostHTML() expects. Create two new variables inside the map() function and change the console.log() so it shows them to us:

allHTMLPaths.map((path) => {
  const inputPath = path.replace('./', '');
  const outputPath = inputPath.replace('views/', '').replace('src/', 'dist/');
  console.log(inputPath, outputPath);
  // callPostHTML(something, somethingElse);
});

Chaining the replace function

Note that with the outputPath variable we've chained together two replace() functions, so we get to first remove views then replace src/ with dist/.

Run the file using node tools/generate-all-html.js and you should see something like this:

src/views/about/index.html dist/about/index.html
src/views/index.html dist/index.html

Perfect! Let's plug those variables into callPostHTML() and try it out. Update the inside of your map() function to read:

allHTMLPaths.map((path) => {
  const inputPath = path.replace('./', '');
  const outputPath = inputPath.replace('views/', '').replace('src/', 'dist/');
  callPostHTML(inputPath, outputPath);
});

Now delete the contents of your dist folder and run node tools/generate-all-html.js (remember to try the up arrow trick to save yourself some time). It won't generate out the images, javascript or CSS, but you should (eventually) see all your HTML files appear inside the dist directory.

Choosing how much HTML to generate

We have two different scripts which do similar tasks:

html-update.js runs when the user makes a change to any HTML file inside either views or fragments
generate-all-html.js can be manually called in order to generate all the HTML files inside views

We already worked out that if we edit a file inside the fragments directory, we need to generate all HTML view files from scratch. How about we treat generate-all-html.js as a module, rather than a script?

This means we can import it into html-update.js and trigger a build if we notice a change to a fragment.

Changing generate-all-html.js into a module means assigning it to a variable, then exporting that variable as the default. Like this:

import getFiles from "./get-files.js";
import callPostHTML from "./call-posthtml.js";

const generateAllHTML = () => {
  const allHTMLPaths = getFiles('./src/views');

  allHTMLPaths.map((path) => {
    const inputPath = path.replace('./', '');
    const outputPath = inputPath.replace('views/', '').replace('src/', 'dist/');
    callPostHTML(inputPath, outputPath);
  });
};

export default generateAllHTML;

Now if we try and run it directly, it won't do anything. But we can call it from a different file instead.

Back to fragments again

Let's add a new variable to html-update.js, just after where we instantiate editedDistPath:

...
if (triggerEvents.includes(fileEvent)) {

  console.log("HTML change detected");

  const { distPath, fileName, extName } = getDistPath(srcPath);
  const editedSrcPath = srcPath.replaceAll('\\', '/');
  const editedDistPath = distPath.replace('/views', '');
  // Do we need to rebuild all HTML files?
  const rebuildAll = editedSrcPath.indexOf('fragments') > -1;
}
...

The new line looks a bit weird, doesn't it? This stores the result of a JavaScript comparison into a variable. What this means is that the comparison will either be true or false. Rather than storing the comparison itself, the variable will instead store the boolean value of the comparison. The comparison itself looks for the string fragments inside the editedSrcPath variable. If this string is not present, the indexOf() function will return -1. If it's present then the function will returns the index within the string where the fragment appears. So by checking if it is greater than minus one, we can determine that the string appears somewhere inside editedSrcPath.

Using `rebuildAll` to decide what to do

Put an if/else statement around the call to callPostHTML(), like this:

if (rebuildAll) {
  // rebuild all HTML
} else {
  // Pass `callPostHTML()` our paths
   callPostHTML(editedSrcPath, `${editedDistPath}/${fileName}${extName}`);
}

Let's import our new generateAllHTML() function into this file to take care of that first part.

At the top of html-update.js, import the function like this:

import generateAllHTML from "./generate-all-html.js";

Now call it from inside the if statement like this:

if (rebuildAll) {
  generateAllHTML();
  console.log(`Fragment ${fileEvent === 'add' ? "added" : "changed"} successfully`);
} else {
  callPostHTML(editedSrcPath, `${editedDistPath}/${fileName}${extName}`);
  console.log(`HTML page ${fileEvent === 'add' ? "added" : "changed"} successfully`);
}

Console logs

We're reusing fileEvent (which we use before to determine if we needed to do any work) so that the terminal will either report HTML page added successfully or HTML page changed successfully. At this point, we're just showing off.

It's considered bad form to leave console.log() commands in live code but here, we're using them to update future developers on what's going on. These logs will never appear on the live site, they will only appear in the terminal when we're using Node. I'm sure you know how frustrating it is to watch a blinking cursor and wonder if the code has crashed or it's doing something but just keeping you in the dark.

As an exception to this rule, clever tech companies use console.log() to reach out to developers who are snooping around there site, curious about how it works.

Testing it out

Let's test this out! Start the watch task with:

npm run watch-html

Open src/fragments/picture.html and add an extra line break at the end of the file, then hit save.

You should see Fragment changed successfully in the terminal and your dist directory should add in an about directory with a html file inside it.

Building all HTML files on first run

There's still another use-case we haven't handled yet: what happens if our hypothetical second developer installs the site for the first time? We need to generate all the HTML files for them at the same time.

We can't just run generate-all-html.js because that does nothing but export the function generateAllHTML() now. Let's account for this inside html-update.js instead.

How about if we call html-update.js from the command line with no arguments, it should generate all the HTML files? Just before the triggerEvents.includes(fileEvent) if/else statement, add this line:

// If this script is called with no arguments, rebuild all HTML files
if (typeof srcPath === "undefined" && typeof fileEvent === "undefined") {
  generateAllHTML();
}

Or if we want to use a slightly more modern way to express this:

// If this script is called with no arguments, rebuild all HTML files
typeof srcPath === "undefined" && typeof fileEvent === "undefined" && generateAllHTML();

(Remember that the JavaScript parser goes from left to right and keeps going until it finds a statement which equates as false. This means if the first two statements are both true, then the function generateAllHTML() will be called.)

Updating `package.json`

Edit your html-build command in package.json:

...
"scripts": {
  ...
  "html-build": "node tools/html-update.js",
  ...
},
...

This will call html-update.js but without arguments. Let's add this new command into our prepare command:

...
"scripts": {
  ...
  "prepare": "concurrently \"npm run sass-prod\" \"node tools/compress-all-images.js\" \"npx webpack --config webpack.prod.mjs\" \"npm run html-build\"",
  ...
},
...

Why not call the script twice?

You might notice that we edited the html-build command so that it called node tools/html-update.js. Then we called that command from a different command (as part of prepare). Here's what they look like next to each other:

npm run html-build
node tools/html-update.js

Why not call node tools/html-update.js twice?

By calling html-update.js only once in the file, it's similar to assigning it to a variable. This means should we ever rename the file or point it at a new script, there's just a single reference to it and it helps to reduce confusing errors.

To test the rebuild command out, delete the contents of your dist directory, cancel the watch task in your terminal and run either npm run prepare or npm install from the terminal (both run the same command). This should regenerate all of the contents of the dist directory from scratch, including the HTML files, images, CSS and JavaScript.

Passing complicated markup to a HTML module

I want to return briefly to the first fragment we wrote - head.html to show you a trick. We currently call this module like this:

...
<head>
  <title>Hello Worm</title>
  <module href="src/fragments/head.html"></module>
</head>
...

This lets us specify a title tag which is custom to the page and also add in any additional CSS and JavaScript we want. But there's another way to do the same thing. Remove the old head tag from the HTML page entirely and change the rest of the markup so it looks like this:

...
<module href="src/fragments/head.html">
  <title>Hello Worm</title>
</module>
...

posthtml-modules lets us pass content rich with HTML tags between the opening and closing module tags. But this won't work until we tell PostHTML we want to pass data this way. So update posthtml.json to this:

{
  "plugins": {
      "posthtml-modules": {
          "root": "./src/views",
          "initial": true,
          "locals": true
      },
      "htmlnano": {}
  }
}

(the new bit is "locals": true)

Now change the head.html fragment so it looks like this:

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="/css/main.css">
  <content></content>
</head>

Note that anything inside the module tag on individual HTML pages will be output where that <content></content> tag sits.

Now regenerate the HTML by running this from the terminal:

npm run html-build

The markup should be the same (although the order of the tags within the head is slightly different). This technique lets us simplify the tags on each page in the src/views directory while still giving us freedom to add tags within the head section of the page.

Nesting modules

Let's create a new fragment which contains a legal disclaimer. Create a file called disclaimer.html inside fragments. It should read as follows:

<p><small>The following site is intended for educational purposes only and should not be taken as legal advice. Your home may be at risk if you do not keep up repayments. Other websites are available. This website is presented "as is" and should not be printed on a t-shirt. Yea, though I walk through the valley of the shadow of death, I will fear no evil: for thou art with me; thy rod and thy staff they comfort me. The views presented on this site do not necessarily reflect those of Tim Berners-Lee, inventor of Alexander Graham Bell's Electric Internet.</small></p>

Now create a second fragment called footer.html. It should look like this:

<footer>
  <content></content>
</footer>

You can import these into the home page (src/views/index.html) just before the script tag at the bottom of the body like this:

<module href="src/fragments/footer.html">
  <module href="src/fragments/disclaimer.html"></module>
</module>

This might seem a little pointless - why not put this into one fragment? Well, at some point you might have more than one style of footer or you might want to re-use your legal disclaimer elsewhere on the site (such as on a sign up form).

Wait! That's not all we can do!

In src/views/index.html change your call to the module to this:

<module href="src/fragments/footer.html">
  <h2>Home page legal disclaimer</h2>
</module>

... then in src/fragments/footer.html, update it to this:

<footer>
  <content></content>
  <module href="./disclaimer.html"></module>
</footer>

Now we can pass custom markup to the footer when we call it, but the legal disclaimer can be the same on every page. Perhaps some pages require other kinds of legal disclaimers, I don't know. I've no idea who your site is for.

Note that the path to disclaimer.html is different in the above example because it's looking for it in the same directory as where the footer.html lives.

Look, not all of my examples can be good, OK?

Summary

We started the chapter by working out how we should handle what happens when a developer edits a fragment
What we need to do is very similar to what we did with images, so we reused some code from that
We changed generate-all-html.js into a module and started treating it like a function, rather than a script to be run
This means html-update.js can either update one file or all the files, depending on what arguments are used
We changed the way fragments worked so we could call them, but add large chunks of markup inside
Then we tried a couple of other ways of nesting fragments where content appears on more than one page

View Chapter 8 code snapshot on GitHub

Quiz

The end

Thanks for making it all the way to the end of this course. I don't care what anyone else says, I think you're a genius. I want to thank Ewan Burns for inspiring this course and helping me develop it.

Stretch goals

Auto-resizing images

For certain kinds of module - for example hero panels - we need images which are a specific width and height. What if you had different rules for different directories inside the src/img directory? For example, if a developer dropped a large image inside a directory called src/img/hero, image-compress.js could notice this and call a module which resized the image automatically, before generating out the different formats.

What if we took this further? Why force mobile users to download the desktop images? Expand out the picture tag so that it uses CSS media queries to show different images at different browser widths. That way, each hero panel might generate nine different images, which would only display at certain breakpoints.

Linting

What if we checked our code before we checked it in? Using so-called linting packages will warn us if we add obvious bugs or bad practice?

TypeScript

What if we wanted to write a version of JavaScript which is more robust and can show us errors as we type? TypeScript was originally developed to enforce data types more strictly in JavaScript but has since become somewhat of an industry standard for large web applications.

Chapter 7: HTML part two

Ross Angus — Tue, 11 Mar 2025 10:49:06 +0000

Cover image by Blue Bird

Recap

Last time, we installed PostHTML plus a few of its close, personal friends. Then we started cutting up our web page into modules. We also learned:

Currently, MVC is the dominant paradigm for application development on the web
JAMSTACK is MVC but with an added static website
How to handle Node security concerns
How to configure PostHTML
Splitting HTML into modules can save us effort

Let's improve how images are rendered next.

Images in HTML5

When we build web pages as a developer, we're used to the idea of making the same content fit wildly different devices. From phones to wide-screens. But what about images? Images have an inherent width and height and while modern browsers are good at downscaling and even stretching images to fit, this feels less than ideal. What other options do we have?

The `srcset` attribute

HTML5 brough some additional attributes for the img tag which maintain backward compatibility but also allow us to smuggle in additional paths to larger or smaller images in the same tag. Here's an example of the markup:

<img
  src="example-image-default.jpg"
  sizes="(max-width: 600px) 480px, 800px"
  srcset="example-image-480w.jpg 480w, example-image-default.jpg 800w"
  alt="This is an example image.">

Let's go through those attributes:

src - this is just your common-or-garden path to the default image
sizes - this borrows the syntax from CSS media queries to define thresholds for switching between images. Specifically, the width of the viewport of the browser. In this example, there are two:
- The size between zero and 600px (max-width: 600px)
- The size above 600px
sizes (again) So what does the 480px, 800px mean? This is how much space is left for the image, once all the padding and so on around the image is taken into account.
srcset - this echoes a lot of the above but gives us paths to images. Each image and width is separated from the next with a comma. So we have two here, example-image-480w.jpg which has a width of 480 pixels and example-image-default.jpg which has a width of 800 pixels. Note that browsers know nothing about an image's width before they load it in, so this is useful for the browser's layout engine to know so it can allocate space while it's rendering the page.
alt - the alternative text which represents the image before it loads in

I ... do not like this syntax. It's complicated and ugly and very difficult for humans to type out. However, we have an alternative!

The `picture` tag

The picture tag in HTML5 split this out into mutliple source tags, inside a wrapper tag of picture. It looks like this:

<picture>
  <source media="(max-width: 799px)" srcset="example-image-small.jpg">
  <source media="(min-width: 800px)" srcset="example-image-large.jpg">
  <img src="example-image-small.jpg" alt="Just imagine a really cool image.">
</picture>

I find this much easier to read. But that's not all it can do! It can also give us a top-to-bottom way to check if a browser supports a particular image format. For example:

<picture>
  <!-- JPEG XL - poor support currently,
   so sharp support is experimental -->
  <source srcset="example-image.jxl" type="image/jxl">
  <source srcset="example-image.avif" type="image/avif">
  <source srcset="example-image.webp" type="image/webp">
  <img src="example-image.jpg" alt="Just imagine a really cool image.">
</picture>

When the web browser parses this picture tag, it starts from the top and loads the first image which it has support for. Then, like an if/else statement, it skips the rest of the code and continues.

Legacy browsers will render the img tag. But modern browsers will still honour its alt text in the final markup.

This finally gives us a use for all the additional Sharp image pipelines we created in chapter 4 and never did anything with the output files.

Revisiting our markup

Currently, inside index.html, we reference a single image:

<p><img src="/img/example-01.webp" alt="An animal, yesterday"></p>

Let's use a picture tag, but let's store it in a new fragment. This is cool, I promise!

Create a new file in src/fragments called picture.html. It should look like this:

<picture>
  <source srcset="{{ path }}.avif" type="image/avif">
  <source srcset="{{ path }}.webp" type="image/webp">
  <img src="{{ path }}.jpg" alt="{{ alt_text }}">
</picture>

What's with all the moustaches? The double curly braces are a little like escape characters. But instead of telling the parser to ignore the contents, it indicates that the language has changed.

Now go back to your index.html page and replace the paragraph with the image tag inside it with the following:

<module
  href="src/fragments/picture.html"
  locals='{
    "path": "/img/example-01",
    "alt_text": "An animal, yesterday"
  }'
></module>

This works exactly like the method we used to import the fragment into the head tag, but this time, we're calling the picture.html module and passing data along with the request.

Specifically, we're passing some JSON via the locals attribute. Note that because JSON has to have both the names and the values surrounded by double-quotation marks (and HTML isn't fussy if we use single or double quotes), the locals attribute has a single quote mark surrounding the JSON data.

Once these variables reach the picture.html fragment, we extract them and add them to the markup.

We can't use hyphens to separate words for these variable names ("kebab case"), so we've used underscores (this is known as "snake case").

Limitations of this approach

While this allows us to put our markup into components and pass data between them, it doesn't allow us to use logic to change the markup depending upon what input data is fed.

For a more robust approach, we'd probably need to install a templating language of some kind, such as Twig, EJS, Handlebars, Pug or Mustache (this is not a complete list!). Reading the documentation for posthtml-modules, you'll notice it doesn't mention package.json or any of the approaches we've used in this guide. Instead, the examples are in JavaScript and we've advised to add this to our Node application.

Node apps

The approach we've used up until now is to avoid task runners as much as possible and string together commands until we have a site which meets our needs. And this works! But another approach is to write code in JavaScript to be run by Node which produces our site. This works in a similar way to how we created image-compress.js and ran that in package.json using the command node tools/image-compress.js rather than npm run ..., like we did for the other commands.

We could also use a dedicated static site generator, of which there is no shortage. But this course was intended to give you an introduction to some of the tools which are used to make these packages and how you might string them together.

Adding a second page

Sadly, PostHTML and its pals don't work in the same way as the sass package does: we call an instance of PostHTML and it processes one file at a time. This means we need to add a couple of new requirements:

The watch task needs to know when any source page has changed, and to update the corresponding distribution page
We need a task which rebuilds all of the HTML pages, for Our Hypothetical Second Developer, on first-run

Hey! This feels familiar. Isn't this what we had to do with sharp too? Perhaps we can reuse code!

Calling PostHTML

There's two different ways to call PostHTML (strictly speaking, we're calling posthtml-cli, but whatever):

Calling it and pointing it at a configuration file (posthtml.json)
Calling it and pointing it at a configuration file, but specifying the input and output file at the same time

Currently, the input and output files are hard-coded into posthtml.json, here:

{
  "input": "src/views/**/*.html",
  "output": "dist",
  "plugins": {
      "posthtml-modules": {
          "root": "./src/views",
          "initial": true
      },
      "htmlnano": {}
  }
}

Let's get rid of the input and output nodes from this file, so all it does is establishes the defaults for the plugins. It should look like this:

{
  "plugins": {
      "posthtml-modules": {
          "root": "./src/views",
          "initial": true
      },
      "htmlnano": {}
  }
}

Now let's write a script which calls PostHTML with the right paths.

The page has updated

The first requirement we discovered was to update a file in the dist directory once the corresponding src/views file changes.

Inside your tools directory, create a new file called html-update.js. It should look like this:

import { argv } from "node:process";

// Destructuring the Array from Node which includes data we need
const [node, thisFile, srcPath, fileEvent] = argv;

// White-list of events which should cause PostHTML to rebuild pages
const triggerEvents = ['add', 'change'];

// If the wrong kind of event triggers this script, do nothing
if (triggerEvents.includes(fileEvent)) {

  console.log("HTML change detected", srcPath, fileEvent);

}

This is basically image-compress.js, but with some of the guts removed.

Edit your package.json watch-html task so it now reads:

"watch-html": "onchange \"src/views\" \"src/fragments\" -- node tools/html-update.js {{file}} {{event}}"

This should ring a bell as well - this is very similar to the watch-images command, even down to the {{file}} and {{event}} arguments. Now run this task from the terminal:

npm run watch-html

It won't open a browser window (because serve isn't involved) but we can fiddle around with files and see what happens.

Renaming variables and arguments

You might notice that we're passing an argument called {{file}} via package.json and it's being called srcPath inside html-update.js. This is normal - as we're destructing argv into different variables, they are given names which are valid within the scope of this file. The JavaScript doesn't care what they were called before they arrived, it'll use whatever name you want.

Because we're dealing with input (source) and output (distribution) filenames here, I've tweaked the variable names to reflect this.

Adding a new folder

Add a new folder inside src/views called about. Nothing will appear in the terminal because it's looking out for new html files. Take a copy of your index.html and put it inside the about directory.

The terminal should report this:

HTML change detected src\views\about\index.html add

Default files and directories

Perhaps you're wondering why we created a new folder, rather than just a file called about.html. Here's why: directories on web servers can contain multiple different files inside but the server can be configured to look for a default file. index.html is often one of these default file names. This means that you can specify the directory, but you don't have to specify the file name inside it.

In terms of URLs, this is the difference between:

http://www.mycoolsite.com/about.html

... and:

http://www.mycoolsite.com/about/

The second one looks better, is easier to say if someone is talking about your site at a party and (to some degree) disguises the technology you used to create the site.

It also means that if you change the technology in the future, the URLs can stay the same, which will save you a lot of headaches because you won't need to set up redirects.

The srcPath part of the console.log() looks wrong, as usual. Hey - we can reuse get-dist-path.js and use that to sort it! Import it at the top of html-update.js:

import getDistPath from "./get-dist-path.js";

Now let's use it like we did before. Replace your console.log() with this:

const { distPath, fileName } = getDistPath(srcPath);
console.log("HTML change detected", srcPath, distPath, fileName);

Remember how we destructed the object before? Now we'll see what we get back from getDistPath(). Try renaming src/views/about/index.html to src/views/about/index2.html. You should see this:

HTML change detected src\views\about\index2.html ./dist/views/about index2

We have most of the information here, but not the file extension. This wasn't important when we were dealing with images, but let's change /tools/get-dist-path.js so it sends it though. Luckily, it already exists as a variable in getDistPath(), so we just need to update the return statement from:

return {
  distPath,
  fileName
}

...to:

return {
  distPath,
  fileName,
  extName
}

Ignoring passed data

Even though we've changed what getDistPath() returns, we don't need to alter image-compress.js. It's cherry-picking data from the object which getDistPath() returns and doesn't care that we've stuffed even more data inside.

Back in html-update.js, update the code inside your if statement to:

const { distPath, fileName, extName } = getDistPath(srcPath);
console.log("HTML change detected", srcPath, distPath, fileName, extName);

Now rename src/about/index2.html back to src/about/index.html and look in your terminal. You should see:

HTML change detected src\views\about\index.html ./dist/views/about index .html

Couple of fixes to those paths:

1) The source path needs \ replaced with /
2) The distribution path needs views/ removed from it (this directory was useful within src so we could keep all the HTML files in one place, but we need to mix things up on the live site)

Let's create new variables with those alterations. After your destructing of getDistPath(), add a couple of new variables:

const { distPath, fileName, extName } = getDistPath(srcPath);
const editedSrcPath = srcPath.replaceAll('\\', '/');
const editedDistPath = distPath.replace('/views', '');

Why are we creating new variables?

You might reasonably look at the above code and wonder why we don't just change the original variables, rather than creating a new variable. You know, like this:

let { distPath, fileName, extName } = getDistPath(srcPath);
srcPath = srcPath.replaceAll('\\', '/');
distPath = distPath.replace('/views', '');

(we need to use let rather than const because the value is changing)

This code is frowned upon in some corners of The Internet because we're never quite sure what the value of srcPath might be at any particular moment. srcPath is initialised right at the top of html-update.js and here, more than half way down, becomes something different.

Call PostHTML

We need a new script which does for HTML what write-images.js does for images (reminder: write-image.js calls Sharp multiple times and outputs different images). Create a new file called call-posthtml.js inside the tools directory. It should look like this:

import { exec } from 'child_process';

export default function callPostHTML(inputFilePath, outputFilePath) {
  exec(`npx posthtml ${inputFilePath} -o ${outputFilePath} -c posthtml.json`, (err) => {
    if (err) {
      console.error(`exec error: ${err}`);
      return;
    }
  });
};

The exec function allows us to run commands in the terminal from within JavaScript. It's like reaching outside of the script and interacting directly with the terminal. Needless to say, JavaScript running outside of Node can't do this.

This is the line which runs in the terminal:

npx posthtml ${inputFilePath} -o ${outputFilePath} -c posthtml.json

Quick reminder of what this means:

npx - gives us access to functions within node_modules
posthtml - calls PostHTML from within node_modules
${inputFilePath} - the JavaScript within call-posthtml.js will replace this with a string we pass it, which represents the path to the input file
-o this flag means that the following path represents the output file
${outputFilePath} - the JavaScript within call-posthtml.js will replace this with a string we pass it, which represents the path to the output file
-c this flag means the next value represents the configuration file we'd like to use with PostHTML
posthtml.json - this is the configuration file we've added already, which sets up the plugins used by PostHTML

Lowering a flag

The documentation for posthtml-cli tells us that we can pass a path to posthtml and it will be assumed to be the input. An output needs a -o flag before it. And a -c flag points to a configuration file.

Perhaps you're wondering why I'm spelling this out. Actually, I don't care if you're wondering or not. Because I spent a couple of hours baffled as to why my input wasn't being found when I used a -i flag, as specified in the documentation. And it turns out I just needed to omit the -i flag.

Thanks for listening. I needed to get that off my chest. Real talk: sometimes documentation isn't accurate.

The exec function has a callback function which is run if there's an error. But let's not dwell on past mistakes. We're just going to log the error to the terminal and move on with our lives:

(err) => {
  if (err) {
    console.error(`exec error: ${err}`);
    return;
  }
}

Finally, we export callPostHTML so we can use it elsewhere.

Calling `callPostHTML` from inside `html-update.js`

Update html-update.js so that it looks like this:

import { argv } from "node:process";
import getDistPath from "./get-dist-path.js";
import callPostHTML from "./call-posthtml.js";

// Destructuring the Array from Node which includes data we need
const [node, thisFile, srcPath, fileEvent] = argv;

// White-list of events which should cause PostHTML to rebuild pages
const triggerEvents = ['add', 'change'];

// If the wrong kind of event triggers this script, do nothing
if (triggerEvents.includes(fileEvent)) {

  const { distPath, fileName, extName } = getDistPath(srcPath);
  const editedSrcPath = srcPath.replaceAll('\\', '/');
  const editedDistPath = distPath.replace('/views', '');

  // Pass `callPostHTML()` all our paths
  callPostHTML(editedSrcPath, `${editedDistPath}/${fileName}${extName}`);
}

The new bit is we import callPostHTML then call it with the correct paths, rather than just logging them to the console.

Cancel, then re-run the npm run watch-html task in the terminal. Now delete the contents of dist and rename src/views/index.html to src/views/index2.html. You should see index2.html appear inside your dist directory.

Rename it back to index.html. You should now see both index.html and index2.html. This is working as expected!

There's still a little bit more to do here:

Handling changes to fragments
Getting the dist directory set up correctly for Our Hypothetical Second Developer
Adding content inside of modules

Still, we've covered quite a lot this chapter:

How to make images in HTML more dynamic
How to pass arguments to PostHTML modules
Replicating our methods with images to apply them to HTML files
Calling PostHTML from the terminal with inputs and outputs

View Chapter 7 code snapshot on GitHub

Quiz

Chapter 6 HTML part one

Ross Angus — Tue, 11 Mar 2025 09:09:08 +0000

Cover image by Antoni Shkraba

Recap

Last time, we installed Webpack so we could process our JavaScript. With more JavaScript. We learned:

Webpack does for JavaScript what SASS does for CSS (and SASS)
How to configure Webpack for development
Two different types of module imports in JavaScript
Why we might use NPX as well as NPM
How to configure Webpack for production
How to keep these two configuration files DRY
What IIFEs are and why we use them
Writing client-side JavaScript modules and the correct way to import them

This time, we're finally going to work on generating HTML files.

Working with HTML

We're on the home straight now. We've done images, JavaScript and CSS. Just HTML to go. Soon, you'll be able to write your own code and discard me like an old sock.

HTML is less of a focus for a lot of Single Page Applications (called "SPA" by its fam). This is because most of the work of rendering snippets of HTML is taken up by JavaScript - the HTML is really just a wrapper into which JavaScript plonks markup.

But you might not want to do that. Wouldn't it be nice to split HTML into modules, so that repeated parts (such as the header and the footer) could be found in one place and then pulled into the page?

To achieve this goal, we'll need to import four different modules. Spoilers follow:

PostHTML gives JavaScript the power to mess around with HTML
posthtml-cli allows us to control PostHTML using Node, so we can string all this together
posthtml-modules lets us cut up our page into tiny wee bits (also known as modules)
htmlnano takes a HTML page and removes all the repeated whitespace, just like we've already done with our JavaScript and CSS

These packages aren't as popular as the ones we've been using up until now. That's for a couple of reasons:

MVC

Single-page applications don't need to generate multiple HTML pages. They build them on-the-fly.

MVC stands for "Model View Controller". This is one way to split up an application's code:

"Model" is basically the same thing as the data. It's what's feeding into the application and needs to be displayed
"View" is closest to a template. It's the structure which sits around the data and gives it shape and allows the user to visually group together similar parts of the page
"Controller" is all the business logic which decides what happens when the user interacts with the user interface in some way, such as clicking a "like" button

This way of splitting up the code is another example of separation of concerns.

The MVC approach is dominating the application market at the time of writing. The three main front-end frameworks which do this are React, Vue and Angular but there are many, many more.

Front-end MVC frameworks run client-side. This means all the JavaScript is parsed by the web browser. Our approach with PostHTML will be rendered server side (also called SSR)¹. Because MVC frameworks handle everything which PostHTML and its pals do, PostHTML is not as popular as React.

JAMSTACK

The second reason that PostHTML isn't a very popular package is JAMSTACK. JAMSTACK sits on top of an MVC application and allows it to build out individual pages to create a multi-paged site. These pages exist as actual HTML pages for users and search engines to visit but once a modern browser lands on any single page, it kind of fakes a reload when the user requests to move to a different page.

The data for just that next page is pulled into the MVC application and the current page is rebuilt with the new content. Just in case the user looks at the address bar, that is rewritten with the new URL (even though that flat HTML page wasn't loaded).

This approach has a few advantages:

The smallest possible parcel of data is sent across the internet
The web browser usually doesn't have to re-render the whole page, just a small part of it
The user doesn't have to suffer the existential doubt with comes when they look at an empty screen for a fraction of a second
Because the pages all exist on the web server, the site can easily be spidered by search engines and users can enter the site on "deep" pages
Some code files split the JavaScript into what is running on the server and what is running in the browser. This means we can manipulate sensitive data (such as API keys) with JavaScript without the risk of exposing this to a public URL.

JAMSTACK frameworks do both server side rendering and client-side rendering. Twice the work!

But all of this is a course in it's own right and won't be covered here. Sorry! Let's get back to the more traditional, static approach for now.

Installing PostHTML, posthtml-cli, posthtml-modules and htmlnano

Let's install all four of the packages we want at once. In a terminal, type:

npm i -D posthtml posthtml-cli posthtml-modules htmlnano

Congratulations! You have unlocked a new achievement! "Downloaded your first security vulnerability". Note that your terminal says:

5 moderate severity vulnerabilities

What can you do about this? Glad you asked - usually, bugger-all.

Side quest: Node security woes
So we can run npm audit from a terminal to see a list of these issues. It tells us:

got  <11.8.5
Severity: moderate
Got allows a redirect to a UNIX socket - https://github.com/advisories/GHSA-pfrx-2q88-qq97
fix available via `npm audit fix --force`
Will install posthtml-cli@0.7.7, which is a breaking change
node_modules/got
  package-json  <=6.5.0
  Depends on vulnerable versions of got
  node_modules/package-json
    latest-version  0.2.0 - 5.1.0
    Depends on vulnerable versions of package-json
    node_modules/latest-version
      update-notifier  0.2.0 - 5.1.0
      Depends on vulnerable versions of latest-version
      node_modules/update-notifier
        posthtml-cli  >=0.8.0
        Depends on vulnerable versions of update-notifier
        node_modules/posthtml-cli

Wait, so all versions of posthtml-cli greater than 0.7.7 depend upon a vulnerable version of got? And the fix is to install an older version of posthtml-cli? How does this make sense? Also to downgrade to the "safe" version of posthtml-cli is a breaking change. How broken exactly? No idea what to do with that information.

Should I even care?

The vulnerability is to posthtml_cli which helps us interact with PostHTML using the terminal. posthtml_cli sits within the devDependencies node of package.json. Which means it never makes it to the live site. It wouldn't make any sense on the live site. So this situation is only risky if a hacker had direct access to your computer, ran the site locally, then used the compromised version of got to ... do something?

Pro-tip: if a hacker has control over your computer, the gig is already up. They will be too busy stealing your data to bother running a dev environment.

Instead of forcing a breaking change, let's try the gentle method and see how far it gets us. In a terminal, type:

npm audit fix

Did that fix the issue? No. Did it break anything else? Also no. Did it make us feel better? Little bit. Let's move on.

Configuring PostHTML

Remember when we installed Webpack and it came with it's own configuration file which needed to sit in the root of our project? PostHTML's got one of those too. It's called posthtml.json and looks like this:

{
  "input": "src/views/**/*.html",
  "output": "dist",
  "plugins": {
      "posthtml-modules": {
          "root": "./src/views",
          "initial": true
      },
      "htmlnano": {}
  }
}

So create that, if you could. It sits along site package.json and all the rest in the root of the Node application.

You might have noticed that this is pointing at a directory which doesn't exist yet - a sub-folder of src called views. Why is this?

We need somewhere to put all our HTML where it won't get mixed up with all the other file types. For example, if we pointed PostHTML at the src directory and then set up a watch task to look for changes, this task would trigger every time we did something inside the scss or js folders too.

The reason it's called views echoes what I said earlier about MVC - the views part of MVC is the presentational HTML.

Wildcards
You might spot a bunch of asterisks hanging out on this line of posthtml.json²:

"input": "src/views/**/*.html",

In this context, the asterisks are behaving as a "wildcard" (in normal JavaScript, a single asterisk would act as a multiplication symbol). Wildcard characters can stand for anything, like in that card game I've never played because it doesn't interest me. So the path here translates into English as "any files which end with a html file extension inside the src/views directory or any of the sub-directories (or no sub-directory)". So:

  Any sub-directory ↓↓ ↓ any file name
"input": "src/views/**/*.html",
or no sub-directory ↑↑

You might reasonably assume that this pattern works in the same way as the sass package does - that it watches a directory and replicates anything it finds there into a different directory. Sadly, this isn't the case. But we'll fix that issue in a bit.

Finally, the plugins node calls two other packages we just installed, posthtml-modules and htmlnano. posthtml-modules has a number of different options we can specify. We've simply pointed it at our views directory and asked that when it first starts up, it should automatically run.

The second plugin is htmlnano the configuration of which is ... not well documented. So we've passing it an empty configuration object, which is the same as telling it to run with the default configuration. If we don't pass it something, it won't run at all.

Setting up the new commands

Back in package.json, let's set up our develop and build tasks for HTML files. They'll sit inside the scripts node and look like this:

"html-build": "posthtml -c posthtml.json",
"watch-html": "onchange \"src/views\" \"src/fragments\" -- npm run html-build",

I've added them inside the scripts node at the bottom.

Hang on - there's another new directory referenced here called fragments. What's that all about?

More new directories

PostHTML will process any and all html files inside our views directory and we also want to use little fragments of HTML to include into these pages. By splitting these out into a new, sibling directory, we can ensure that these wee bits never end up as html files in their own right on the live site. So the directory structure of the src folder should look like this:

...
🗀 src
  🗀 fragments
  🗀 img
  🗀 js
  🗀 scss
  🗀 views
...

Both the fragments and the views directories need to be scrutinised by the watch task, so if we change a file inside either, the page will rebuild.

What the new `package.json` commands mean

The html-build task invokes posthtml with a c flag:

"html-build": "posthtml -c posthtml.json",

I can't find this in the documentation but my guess is that it stands for "configuration". The next argument passed is the path to the configuration JSON, so this checks out.

onchange watching two different directories

The other new command we've just added to package.json does something a little new:

"watch-html": "onchange \"src/views\" \"src/fragments\" -- npm run html-build",

The package onchange can watch two different directories at the same time, and then run the specified command if either changes. This means we can use the watch-html command to look into both src/views and src/fragments and run the html-build command if any files in either directory changes.

Adding the new commands to the `start` and `prepare` commands

Your start and prepare commands should include our new commands, so they now look like this:

"start": "concurrently \"npm run serve\" \"npm run sass-dev\" \"npm run watch-images\" \"npm run watch-js\" \"npm run watch-html\"",
"prepare": "concurrently \"npm run sass-prod\" \"node tools/image-compress.js\" \"npx webpack --config webpack.prod.mjs\" \"npm run html-build\""

Moving and splitting the HTML

Drag your index.html from dist to src/views. Let's break it up!

Create a new file inside your fragments directory called head.html. It should look like this:

<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="/css/main.css">

Now edit the head tag of your index.html so it looks like this:

<head>
  <title>Hello Worm</title>
  <module href="src/fragments/head.html"></module>
</head>

We've moved all the tags which are common to all pages on the site and put them inside one fragment. That path doesn't make a lot of sense, does it? The way we usually navigate between directories is to use ../ to move into the parent directory and to just add the sub-directory name in the same way as src is used here. This implies that all of the src directory lives under the views directory, which we know isn't the case.

This is happening because posthtml-modules is the package which is interpreting this path and as far as it's concerned, it's running in the root of the Node application. And the root of the Node application is where the src and dist directories live. But this certainly is confusing.

Let's check if this all works.

In a terminal, type:

npm start

Hmm. Nothing there. Let's debug this. Is there anything in the dist directory yet? No? Of course - PostHTML only builds a new HTML file once there's been a change, which there hasn't been since we started the web server.

Add a space, then delete it, in src/views/index.html. Wait for the terminal to finish, then refresh your web browser.

Hopefully the web page should appear. Now change the Hello Worm text in index.html however you like, to make sure it updates automatically once you save.

Inside head.html, break the path to the CSS by changing the line:

<link rel="stylesheet" href="/css/main.css">

For example:

<link rel="stylesheet" href="/css/main2.css">

After you save the file, the text should change to Times New Roman, the most boring of typefaces. Change it back and the correct typeface should reappear!

Now open up the index.html file inside the dist directory. It should look like this, more or less:

<!doctype html><html class="no-js" lang="en-GB"><head><title>Hello Worm</title><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><link rel="stylesheet" href="/css/main.css"></head><body> <p>Hello Worm</p> <p><img src="/img/example-01.webp" alt="An animal, yesterday"></p> <script src="/js/main.js"></script> </body></html>

Ah, barely room to swing a cat in there. Just the way we like it.

Summary

What we've got so far does the following:

Allows us to create a page with server-side includes (that's another way of describing what posthtml-modules does)
Converts our SCSS to CSS then minifys it
Concatenates (joins together) and minifies our JavaScript files
Converts our images to next-gen versions

This is a great place to start! But I'd like to handle those images in a slightly better way which uses both posthtml-modules and all those next-generation image files we generated with sharp. Let's do that in the next part.

Let's review what we learned:

Currently, MVC is the dominant paradigm for application development on the web
JAMSTACK is MVC but with an added static website
How to handle Node security concerns
How to configure PostHTML
Splitting HTML into modules can save us effort

View Chapter 6 code snapshot on GitHub

Quiz

Technically, we'll be creating the static HTML pages before the code even reaches the server. We're doing it on our local machine. Perhaps there's a word for this, but I couldn't find one in a cursory search. ↩
Perhaps you're wondering what swear word you're supposed to type there instead. ↩

Chapter 5: JavaScript

Ross Angus — Mon, 10 Mar 2025 15:06:28 +0000

Cover image by Audy of Course

Recap

Last time, we finished optimising our images:

Used the fs module from Node to elegantly handle nested directories inside src/img
Learned about short-circuit evaluation in JavaScript
Stole a utility function from Param Harrison to get a list of files and folders in Node
We looked at how we might split up a long, complicated script into modules
We learned the shorthand which can be used in JavaScript if the name and property are the same

Now we're going to write some more JavaScript to process our JavaScript.

JavaScript

We want to do a couple of things with our JavaScript:

We want to write bleeding-edge JavaScript, including this season's must-have methods
We want it to run fast on a decent proportion of the web

We're going to be writing our JavaScript using ES6 modules which allows us to split them into many different units. And while support for ES6 is excellent, downloading all of those files individually isn't great for a couple of reasons:

If your host doesn't support HTTP2 then each file requires a new connection, all of which adds overhead
The end user needs to download all of your comments and whitespace too, which they probably aren't interested in

Guess what? There's A Package For That™!

Introducing Webpack

Webpack was invented for one reason and one reason only: to take a bunch of JavaScript modules and squash them into one package. Which is exactly what we're going to use it for.

Historical aside

Remember when I talked about how Ryan Dahl made Node.js and intended it to have one purpose and that other people would build on top of it? What this originally led to was what are called "task runners" - early examples included Grunt (which wrote files to disk) and Gulp (which ran files from memory). Gulp's still pretty popular! (but nowhere as popular as Webpack)

Task runners are complicated to configure and as we've learned, we can mostly get by without them these days.

However, when Webpack came along, people started using it as a task runner. And it works. So everything we've done so far could probably be achieved using Webpack. But I don't think we need to do that and I'm not alone.

But don't take my word for it. By all means, check out the sass-loader for Webpack. It won't be covered in this guide. If anyone has done this successfully and come back here to tell me why I'm wrong, here's your medal:

🎖

Installing Webpack

Let's use the street-slang NPM version. In a terminal, type:

npm i -D webpack webpack-cli

Note how we're installing both Webpack and webpack-cli on the same line. Nice little trick there.

What's this webpack-cli business? Don't worry about it. It's just Webpack's wee pal. Won't go anywhere without it.

This should plonk a reference to Webpack and webpack-cli in our package.json. You know the score by now.

Configuring Webpack

Remember how we had to create .gitignore? Sometimes packages are so special that they don't want to add their configuration into package.json and demand their own special configuration files. Webpack's like that¹.

Bespoke configuration file

Webpack's configuration file is called webpack.config.mjs and it should sit in the root of your Node application - as a sibling to package.json and the rest of the gang.

Here's what it should look like:

import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

export default {
  mode: 'development',
  entry: './src/js/index.js',
  output: {
    filename: 'main.js',
    path: path.resolve(__dirname, 'dist/js'),
  }
}

What's an MJS file?

This configuration file example is pretty far from the Webpack documentation. Even the file extension is different. Why is this?

Remember when we enabled JavaScript modules in Node? This led to Webpack expecting ES Module syntax. This is not what the documentation for Webpack is expecting.

The file extension mjs is short for "Modular JavaScript" and reminds Node how they should be treated.

The first line of webpack.config.mjs imports the path function from Node and renames it "path". Imaginative. The path function lets us view and manipulate the paths of the files we want to change. Earlier, we used the fs module in Node to change files on the hard drive, when we wanted a list of images. But this is just a configuration file so it's not directly changing files.

We import another in-build Node function fileURLToPath.

Different kinds of imports in ES6

When a JavaScript module exports just a single function or one function is marked as the default, we can call it like this:

import myFunction from "./tools/my-function.js";

But sometimes you want to have a few different functions in the same file. Let's say a file looks like this:

export returnRandomNumber = () => {
  ...
};

export returnRandomWord = () => {
  ...
}

//  Hello ↓
export default returnRandomEmoji = () => {
  ...
}

We could import these functions into a different module like this:

import returnRandomEmoji, { returnRandomNumber, returnRandomWord } from './tools/randoms.js';

Because returnRandomEmoji is the default export from randoms.js, it gets to escape from the curly braces. The same cannot be said for returnRandomNumber and returnRandomWord, who are still exported, but just not as the default.

When we're writing JavaScript in this way, each file is assumed to be a module. This means the JavaScript engine makes certain assumptions about what it exports - whether it does so or not. The Webpack configuration file does nothing except exports some JSON which represents the configuration information. That's what the module.exports object means. Why isn't it just a JSON file? Probably because it needs to call on various Node functions to return path information.

The entry node points to a new file in a new directory within our application. We'll create something in there in a moment.

The output node points to another file - this will be generated by Webpack and it's what we should point our HTML file at. We've set it to create the file main.js inside the dist/js directory.

The second node inside the output node - path - uses the path component from Node. The resolve function just squashes together two strings. The second of which is our good old dist directory.

If we were using Webpack in the conventional way (that is, using ES5 syntax), we could access an environmental variable called __dirname. This returns the full path to the root of our application. However, in ES6, we need to derive this variable using the lines:

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

If it sounds like I don't fully understand this, that's because I don't fully understand this. Basically, by trying to force Webpack to use ES6 we've left the documentation behind and are in (mostly) uncharted territory. Perhaps there's a reason why most people don't do it this way.

With all this in mind, think of this file as just some fancy JSON.

Wait, if it's fancy JSON, how come each node ends with a comma?

Remember when I told you how strict JSON was about ending every node with a comma, apart from the last one? This doesn't follow that rule because it's a JavaScript object which we're treating like JSON, rather than real JSON.

If it's any consolation, I'm sorry for the confusion.

Setting up our directories

We need to set up directories for our JavaScript. Inside your src and dist directories, add a new js directory to each. Have it as a sibling of img, so they look like this:

🗀 dist
  🗀 css
  🗀 img
  🗀 js
🗀 src
  🗀 img
  🗀 js
  🗀 scss
...

Add your entry point

Create a new JavaScript file inside src/js called index.js. Let's keep it simple for now:

console.log("Hello worm");

This is the file which the Webpack configuration file is pointed at as an input.

Loading the configuration into Webpack

Just creating the file isn't enough. We need to point Webpack at it, much like you might bring a horse to water.

Let's run Webpack from the terminal. Type (or copy-&-paste) the following into your terminal.

npx webpack --config webpack.config.mjs

Hang on, what's npx when it's at its gran's?

First, a quick reminder of what our old pal NPM does:

Installs packages dragged from the internet
Runs specific commands we've added to package.json such as start or prepare

What if we wanted to pull out a specific bit of functionality we know is hidden inside node_modules but didn't need to write a command for it? This is one of the two things npx does².

The line we've just typed into the terminal asks npx to find our webpack application, then passes it the --config flag and also the location of our webpack-config.mjs file.

After you've run this command, you should see a new file appear in dist/js/ called main.js. Have a look!

Our single line of JavaScript has somehow turned into 49 lines where the developer was paid by the underscore. Don't worry - we won't be writing code like this. If you read some of the comments, you'll notice Comrade Webpack telling us that we're seeing this mess because we triggered a development build of the JavaScript, rather than a production build.

Adding in a production build

We've got two choices here:

Create a duplicate of webpack.config.mjs and tweak it a bit for production
Install another plugin

I know option 2 doesn't sound appealing but we all took a sacred oath to uphold the principles of DRY and we cannot break that pact.

(More serious justification: because the production and development configurations share a lot of data, we want to share that common data between them, so that if we update it in one place, it impacts both environments. If we didn't do this, we might run the risk of an issue appearing on the live site which doesn't exist on the development site, which would take ages to debug.)

Development sites?

The vast majority of websites you interact with have shadowy clones of themselves which you're not allowed to see. These are used to preview and test changes to that site to various stakeholders before the general public clicks all over them. They have a bunch of different names which reflect their purposes. Here's some of my favourites:

Development (or dev)
Quality-assurance (or qa)
Staging (or stag)
Pre-production (or pre-prod)

Finally, finished code is published to:

Production (or prod)
Live (same as prod)

Installing webpack-merge

webpack-merge takes two different webpack configuration files and squashes them together. This lets our development and production configuration inherit from a third configuration we're going to call webpack.common.mjs. First, let's install the package. In a terminal, type:

npm i -D webpack-merge

Splitting up our configuration

Rename webpack.configuration.mjs to webpack.common.mjs. Then take a copy of it and call it webpack.dev.mjs. All these files should sit in the root of the Node application (they should be siblings to package.json).

webpack.common.mjs just needs a single line removed. The line which sets the mode to development:

export default {
  mode: 'development', // ← Remove this line
  ...
}

The new webpack.dev.mjs file should look like this:

import { merge } from 'webpack-merge';
import common from './webpack.common.mjs';

export default merge(common, {
  mode: 'development',
  devtool: 'inline-source-map',
});

At the start of our new configuration file, we import the merge function from webpack-merge. Then we pull in our other file, which we're calling common.

Then we take the imported common config and squash it together with some new JSON, using the merge() function. This returns some JSON which is exported as if nothing happened.

The new JSON object sets the mode to development and uses the inline-source-map devtool. That's all we need to know for now!

Remind me: why do we need a development and production mode configuration?

Just like with SASS, while we're writing JavaScript we need to know which specific file any errors might be coming from. If we let Webpack compile all our code into a single file just like on live, we couldn't trace it back to a specific source file. The browser would always report the error on "line 1" of the JavaScript file (because Webpack will squash all our code into a single line).

Once the mode is set to development the browser will magically know the specific source file the error has originated from. So much easier.

The production configuration strips all of that out, giving us just the leanest possible JavaScript.

Testing it out

To test out our new configuration, run:

npx webpack --config webpack.dev.mjs

Check your dist/js/main.js file and it should look the same as it did before. All this work and nothing to show for it.

Adding a production configuration

Let's create a new configuration for production. Take a copy of webpack.dev.mjs and call it webpack.prod.mjs. It should look like this:

import { merge } from 'webpack-merge';
import common from './webpack.common.mjs';

export default merge(common, {
  mode: 'production',
});

Test that configuration out at the terminal by typing:

npx webpack --config webpack.prod.mjs

Now have another look at dist/js/main.js. It should look like this:

(()=>{"use strict";console.log("Hello worm")})();

Well, at least it's small now. What's with the syntax? Was the developer paid by the parentheses?

Immediately Invoked Function Expressions

You know how everyone's frightened of (in ascending order of threat) spiders, nuclear war and polluting the global scope? Immediately Invoked Function Expressions (or IIFEs, to their friends) were our best method of encapsulating variables in JavaScript before ES5 and the like.

Because variables which are declared inside of functions are only in scope within that function, IIFEs are a method of declaring an anonymous function which immediately runs (or is invoked). Webpack uses a modern arrow function variation but you can use older methods too. Essentially, the first set of parenthesis encapsulates the code and the second set runs it.

"use strict"

This invokes a slightly more strict version of JavaScript, at least compared to how things used to be in The Bad Old Days. Because Webpack is generating backward looking JavaScript, this tells the JavaScript parsing engines in browsers to step up their game.

Adding in our new commands to `package.json`

Remember our old pal package.json? Let's see how they are doing. We currently have a load of commands:

sass-dev - converts SASS files to CSS during development
sass-prod - converts SASS files to CSS for production (not currently used)
serve - starts up a web server and points it at the dist directory
start - runs three different of the commands above at the same time - serve, sass-dev and watch-images
prepare - populates the dist directory with production-ready files
watch-images - watches the img directory for changes, then invokes our image-compress script

Take a moment to appreciate how much you've learned.

OK, the moment has passed.

Let's add our production webpack command to our prepare task. It should now read:

"scripts": {
  "prepare": "concurrently \"npm run sass-prod\" \"node tools/compress-all-images.js\" \"npx webpack --config webpack.prod.mjs\"",
  ...
}

The prepare command should be used to create production-ready files.

While we're at it, let's add a new watch task to pick up on any JavaScript changes. After the watch-images command, add:

"watch-js": "onchange \"src/js\" -- npx webpack --config webpack.dev.mjs",

The watch-js command will produce files which help us with development. Now let's call watch-js as part of the start command, so it reads:

"start": "concurrently \"npm run serve\" \"npm run sass-dev\" \"npm run watch-images\" \"npm run watch-js\""

Testing out the production JavaScript

Let's test this all out! Delete the contents of the dist/js, dist/css and dist/img directories (leave dist/index.html!), then in the terminal type:

npm install

(remember, this is the same as running npm run prepare)

Now check those same directories again. You should see the production-ready CSS, JavaScript and images.

The scripts node of your package.json should look like this:

"scripts": {
  "sass-dev": "sass --watch --update --style=expanded src/scss:dist/css",
  "sass-prod": "sass --no-source-map --style=compressed src/scss:dist/css",
  "serve": "browser-sync start --server \"dist\" --files \"dist\" --watch \"dist\"",
  "start": "concurrently \"npm run serve\" \"npm run sass-dev\" \"npm run watch-images\" \"npm run watch-js\"",
  "prepare": "concurrently \"npm run sass-prod\" \"node tools/compress-all-images.js\" \"npx webpack --config webpack.prod.mjs\"",
  "watch-images": "onchange \"src/img\" -- node tools/image-compress.js {{file}} {{event}}",
  "watch-js": "onchange \"src/js\" -- npx webpack --config webpack.dev.mjs"
}

Testing out the development JavaScript

In dist/index.html, include a script tag to link to your JavaScript file:

<script src="/js/main.js"></script>

This should appear inside your body tag but after all the rest of the HTML. This is so the page renders first and then the JavaScript has access to everything in the DOM.

Start up your local server with:

npm start

You should (eventually) see your page. Right-click and inspect an element to open the developer tools. Switch to the Console tab at the top of the developer tools and you should see the text Hello worm appear.

Does it change, when we update the JavaScript? Edit src/js/index.js so that it reads:

console.log("Hello world");

Check the console in your browser. It should now say "Hello world" instead of "Hello worm".

JavaScript Modules

A quick reminder of how our scss directory looks:

🗀 src
  ...
  🗀 scss
    _fonts.scss
    main.scss

How this works is that SASS ignores any files which start with an underscore. So we use main.scss to import all of the scss files in any directory structure we want. That way, we can keep our sass modular and still export just one file to the production environment.

We want to take a similar approach with JavaScript. Remember when we split image-compress.js into different functions, then imported and exported them? We want to do this with our production JavaScript too (reminder: all the JavaScript we've currently written except console.log("Hello world"); won't end up on the live site).

Rather than using underscores, we don't need to do anything to exclude individual JavaScript files from our bundle. Webpack is opt-in rather than opt-out. In fact the only JavaScript file Webpack will look at is src/js/index.js, because that's what we defined in webpack.common.mjs.

All we need to produce modular JavaScript is to write a module and import it into index.js. So let's do that now.

Directory structure

Inside your src/js directory, create a new folder called modules. Inside that, create another directory called add-emoji. Inside that, add a new file called add-emoji.js. Your directory structure should look like this:

🗀 src
  ...
  🗀 js
    🗀 modules
      🗀 add-emoji
        add-emoji.js

(VS Code might try and help you out by flattening this out visually)

Personally, I'd advice kebab case for directories and file names, and camel case for function names.

Add Emoji

This is our first client-side (i.e. this runs on the "client" or web browser) module:

export default addEmoji = (emoji = '😊', selector = 'body') => {
  const element = document.querySelector(selector);
  element && element.insertAdjacentHTML('afterbegin', `<big>${emoji}</big>`);
};

It's a function called addEmoji which takes two parameters:

An emoji as a string (or just, you know, a string of text)
A CSS selector of a tag where you want to insert the emoji just after the opening tag (this is also a string)

If the function is called without any arguments, it falls back to the defaults of rendering a 😊 emoji just after the start of the body tag. The emoji itself is rendered inside a big tag because no-one has used this tag for over five years now and I'm worried its internet licence might expire.

Note that I'm using short-circuit evaluation on the second line inside the function - this will check if the element exists or not. So even if the function is called with an invalid CSS selector, no error will be triggered.

But of course, a module will do nothing until it's called.

Calling the module

Open up src/js/index.js. It should look like this:

console.log("Hello world");

Get rid of that line and instead, import our new module, then call our new function three times:

import addEmoji from "./modules/add-emoji/add-emoji.js";

// Will add `😊` after the opening `body` tag
addEmoji();
// Will add `🪱` inside the first `p` tag on the page
addEmoji('🪱', 'p');
// Will not find a `section` tag on the page and silently fail
addEmoji('😈', 'section');

To add the file extension or not

It's possible that VS Code tried to finish that import statement above for you, like an eager fan in the front row of a concert (you are the singer in this analogy). And in doing so, it dropped the .js. This is an error. Because we're importing a local file, we need to specify this file extension, no matter what VS Code thinks.

You might encounter module imports elsewhere which don't need to specify a file extension. These rely on specific configurations to handle fallback cases such as this to work. I want to keep the Webpack configuration as small as possible, so I've not added them³.

Testing this out

Your page should have refreshed after each save. You should see a new smiley face above Hello Worm, a new worm emoji inside that paragraph and no devil face on the page (unless you added a section tag, of course).

Most importantly, you shouldn't see anything in the console of the web browser (apart from complaining that you're missing a favicon) - no errors, no Hello world.

Congratulations! You're writing client-side code in a modern way!

Let's review what we learned:

Webpack does for JavaScript what SASS does for CSS (and SASS)
How to configure Webpack for development
Two different types of module imports in JavaScript
Why we might use NPX as well as NPM
How to configure Webpack for production
How to keep these two configuration files DRY
What IIFEs are and why we use them
Writing client-side JavaScript modules and the correct way to import them

View Chapter 5 code snapshot on GitHub

Quiz

Strictly speaking, Webpack wants to work with zero configuration but it's rare that the out-of-the-box experience is exactly what we want. ↩
The other is to run a bit of functionality, but instead of it being pulled from your hard drive the internet acts as your hard drive. Woah. ↩
Well, I did add the configuration but it didn't work first time and I got bored ↩

Chapter 4: images part two

Ross Angus — Sat, 08 Mar 2025 17:33:12 +0000

Cover image by Yura Forrat

Recap

Last time, we started to look at optimising images:

We used the onchange package to pass events from the file system to our JavaScript
We ran arbitrary JavaScript files directly in Node - no web browser required
We saw that Node gave us access to different methods of accessing path and filename information
We learned that Sharp is this season's must-have image optimisation package

There's still a lot to do before we meet our goals set out at the start of the previous lesson. Here's the features we wanted to build:

~~Drop an image into the src/img directory and it automatically gets converted into a next-gen format in the dist/img directory~~
Run a task which converts all images in the src/img directory into their optimised versions in dist/img - for example when you've added some images but the server wasn't running at the time
~~Overwrite an existing image in src/img with a new one with the same name, and have the corresponding images in dist/img update automatically~~
Use as many different sub-directories in src/img and have those be replicated on dist/img - for example src/img/gallery/open-day which lives inside dist as dist/img/gallery/open-day

Let's continue the build!

Nested directories

Our script works perfect, but only if the image in question is inside src/img. What about if we wanted to create sub-directories inside src/img, such as src/img/gallery?

Let's see what happens. In a terminal, run:

npm run watch-images

Now Create a new folder inside src/img and call it gallery. Copy one of the images and paste it into there.

I got an error in the terminal which read:

Error: ./dist/img/gallery/example-01.webp: unable to open for write
windows error: The system cannot find the file specified.

sharp tried to write the optimised image into a new folder called gallery which lives inside dist/img - exactly as we'd hoped. But it couldn't find the directory. Let's give the script the power to create directories.

For this, we'll need to lean on another part of Node, the fs module. fs stands for "file system" and not a rude exclamation you might use when your code doesn't work.

import fs from 'node:fs';

Just like before, we're going to use two functions built into fs. The first, existsSync(), takes a parameter which is a path. It returns true or false depending if the path exists or not.

The second function is called mkdirSync and allows us to make one or more directories in the path we supply it.

We can use these two functions inside your if statement, between where the variables are initialised and the calls to sharp, like this:

if (!fs.existsSync(distPath)) {
  fs.mkdirSync(distPath, {recursive: true});
}

Guess what: there's a shortened form of if too, as long as the JavaScript fits onto one line. It uses the double ampersand and the cool name for it is short-circuit evaluation.

It looks like this:

true && alert("Truth detected!");

This would cause a JavaScript alert with the string Truth detected!.

However this would do nothing:

false && alert("Can you hear this?");

How this works is the JavaScript parsing engine works from left to right. It will continue until it finds something false and then skip the rest of the statement and work further down the file. So we could shorten our if statement to:

!fs.existsSync(distPath) && fs.mkdirSync(distPath, {recursive: true});

Don't go hog-wild with this technique. Remember that JavaScript needs to be readable as well as using the most up-to-date slang.

OK, but what does this statement do? First, we check if the distPath we want to use exists or not. If it doesn't exist, we call mkdirSync on it, while passing a recursive boolean in the option object. This will recursively call mkdirSync over and over again, until all the directories are created.

Testing out nested directories

Let's try this out. Cancel the watch-images task and create some nested folders inside src/img, for example src/gallery/1/2/3. Restart the watch-images task and drop an image inside the 3 directory.

Now check what's inside the dist/img directory. You should see a mirror of the src directory structure, except now your example file is a webp rather than a png. Great! We can cross off this requirement:

~~Use as many different sub-directories in src/img and have those be replicated on dist/img - for example src/img/gallery/open-day which lives inside dist as dist/img/gallery/open-day~~

Adding `watch-images` to our `start` task

Cancel the watch-images task using ctrl + c. Let's edit our old pal package.json and introduce watch-images to the start krew:

{
  ...
  "scripts": {
    ...
    "start": "concurrently \"npm run serve\" \"npm run sass-dev\" \"npm run watch-images\"",
    ...
  }
}

Lovely.

Check if the image changes

From a terminal, run:

npm start

Your example web page should open and accuse you of being a worm. Let's add an image.

Open the file dist/index.html. Add a paragraph before the closing body tag so that the whole file looks like this:

<!doctype html>
<html class="no-js" lang="en-GB">

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Hello Worm</title>
  <link rel="stylesheet" href="/css/main.css">
</head>

<body>
  <p>Hello Worm</p>
  <p><img src="/img/example-01.webp" alt="An animal, yesterday">></p>
</body>

</html>

You will hopefully have a few different images inside dist/img by this point, none of which might be called example-01.webp so update the img tag so it points to an image which actually exists. Save the file.

Let's update the image! Visit the example image page and download a different image from the one which is currently displayed on your page. Use this image to overwrite example-01.png (or whatever) in your src/img directory. You should see your image-compress.js script kick into action. And once it's finished, you should see the browser refresh and the displayed image should update.

This happens "automagically" because we've already configured browser-sync to watch the dist directory and to refresh when something happens in there.

Missing task

Just like with the CSS, our hypothetical second developer will inherit this codebase and an empty dist/img directory.

We need to write a task which will go through all the images in src/img and optimise them. As the site grows in complexity, this isn't something we'd want to do every time we start the local server, because that would take ages. But it should run at least once, when a new developer downloads the project.

Let's start by grabbing a list of all the src images.

Get all files

We need to write a function which pulls a list of file names from an arbitrary directory. Inside the tools folder, create a new file called get-files.js. It should look like this:

// Import the "file system" function, which is built into Node.js
import fs from 'fs';

export default function getFiles(dir, files = []) {
  // Get an array of all files and directories in the passed directory using fs.readdirSync
  const fileList = fs.readdirSync(dir);
  // Create the full path of the file/directory by concatenating the passed directory and file/directory name
  for (const file of fileList) {
    const name = `${dir}/${file}`;
    // Check if the current file/directory is a directory using fs.statSync
    if (fs.statSync(name).isDirectory()) {
      // If it is a directory, recursively call the getFiles function with the directory path and the files array
      getFiles(name, files);
    } else {
      // If it is a file, push the full path to the files array
      files.push(name);
    }
  }
  return files;
};

I stole this from Learn with Param. Does this make me a great artist? That's not for me to say.

Use `getFiles()` to pull in a list of the images

Create a third file in our new tools directory called compress-all-images.js. It should look like this:

import getFiles from "./get-files.js";

console.log(getFiles('./src/img'));

This does exactly two things:

Imports the function get-files.js from the same directory
Console-logs the output of that function, if it's pointed at ./src/img

Save any missing images from the example page into src/img, just so we have a good supply.

In the terminal type:

node tools/compress-all-images.js

You should see an output something like this inside your terminal:

[
  './src/img/example-01.png',
  './src/img/example-02.png',
  './src/img/example-03.png',
  './src/img/example-04.png',
  './src/img/example-05.png',
  './src/img/gallery/1/2/3/example-01.png']

Those square brackets mean it's an Array. A nice way to work with Arrays is to call the map method on them. This means that map goes through each item in an Array and runs the same function on it (a function we're just about to define). Let's store that data in an variable, then iterate over it with map():

import getFiles from "./get-files.js";

const allImagePaths = getFiles('./src/img');

allImagePaths.map((path) => {
  console.log(path);
});

Our new function is passed as a parameter to map and we're writing it inline, as an arrow function. The function receives an automatic parameter which I've chosen to call path. In the example above, the first value of path will be ./src/img/example-01.png.

Call the JavaScript file from the terminal a second time, using the up arrow, if you're in a hurry.

As expected, this console.log()s the same data, but as individual lines. Now we just need to replicate a bunch of code from image-compress.js in this file, right?

Let's see if we can split this reused code off into different modules, so we don't write the same code twice.

Making `image-compress.js` more modular

A lot of image-compress.js is concerned with getting the right dist path and extracting the filename from a path. Let's pull all of that code into a new file inside tools called get-dist-path.js:

It should look like this:

import path from "node:path";

export default function getDistPath(filePath) {

  const trimPath = thisPath => thisPath.replace('src', '');

  // The path from the root of the Node application to the filename of the image
  const dirName = path.dirname(filePath).replaceAll('\\', '/');
  // The image name, plus file extension
  const baseName = path.basename(filePath);
  // The image file extension
  const extName = path.extname(filePath);
  // The path to the source image, minus the `src` bit
  const subPath = trimPath(dirName);
  // The name of the image, without the file extension
  const fileName = baseName.replace(extName, '');
  const distPath = `./dist${subPath}`;
  return {
    distPath,
    fileName
  }
};

Shorthand property and method names in JavaScript

You might have notices some weird return syntax there:

return {
  distPath,
  fileName
}

This is a shorthand form of an object in JavaScript. It's the same as this:

return {
  "distPath": distPath,
  "fileName": fileName
}

Where the name and the value are the same (even if one is a variable), you can skip the value part in JavaScript (not in JSON!)

The getDistPath function is passed a src path and uses this to work out what the equivalent dist path should be.

But there's still code in image-compress.js which just calls Sharp, which would be common to compress-all-images.js. So let's split that out into a new file too. Inside the tools directory, create a new file called write-images.js. It should look like this:

import fs from 'node:fs';
import sharp from "sharp";
import getDistPath from "./get-dist-path.js";

export default function writeImages(filePath) {
  const { distPath, fileName } = getDistPath(filePath);

  !fs.existsSync(distPath) && fs.mkdirSync(distPath, {recursive: true});

  sharp(filePath)
    .webp()
    .toFile(`${distPath}/${fileName}.webp`);

};

This means we can import the function writeImages into image-compress.js and then get rid of a lot of code:

import { argv } from "node:process";
import writeImages from "./write-images.js";

// Destructuring the Array from Node which includes data we need
const [node, thisFile, filePath, fileEvent] = argv;
// White-list of events which should cause Sharp to generate images
const triggerEvents = ['add', 'change'];

// If the wrong kind of event triggers this script, do nothing
if (triggerEvents.includes(fileEvent)) {
  writeImages(filePath);
}

Because the only thing which differs between compress-all-images.js and image-compress.js is how they are called and if the web browser is running or not.

Breaking down code

It might feel a bit as if we've been shuffling code about between a whole lot of files in a pretty arbitrary way here. Indeed other programmers might choose to slice this code up differently. Splitting a long piece of code into different modules is an example of separation of concerns and is quite a challenging topic to teach!

The approach we've stumbled into here had us writing one big script which did everything, then realising we'd need to write a second script which did 90% the same thing.

We could, of course, just duplicate the first script and make some changes to it. But breaking it into modules will help us in all kinds of ways in the future.

One way to work out how to split up a long script up is to add comments before each line explaining what it does. Then see if groups of those comments use the same words, suggesting different "concerns".

Another way is to look at inputs and outputs. In our example, we had a lot of code which just edited strings to normalise them and translate them from the src to the dist directories. Not only does this code belong together, it's easy to see how useful it might be in the future for other purposes.

The approach we've taken here where we write the code first, then refactor it later is normal. Don't expect everything to be perfect right away. We can always improve things later.

Finally, let's import writeImages.js into compress-all-images.js. We need to slightly trim the paths, to remove the ./ at the start:

import getFiles from "./get-files.js";
import writeImages from "./write-images.js";

const allImagePaths = getFiles('./src/img');

allImagePaths.map((path) => {
  const trimPath = path.replace('./', '');
  writeImages(trimPath);
});

Generating out other image formats

Now that write-images.js is common to both image-compress.js and compress-all-images.js, let's make it generate three times as many images! We won't use these other formats yet (that's coming soon) but there's no harm in outputting them ahead of time.

Open write-images.js and add more Sharp calls like this:

import fs from 'node:fs';
import sharp from "sharp";
import getDistPath from "./get-dist-path.js";

export default function writeImages(filePath) {
  const { distPath, fileName } = getDistPath(filePath);

  !fs.existsSync(distPath) && fs.mkdirSync(distPath, {recursive: true});

  sharp(filePath)
    .avif()
    .toFile(`${distPath}/${fileName}.avif`);

  sharp(filePath)
    .webp()
    .toFile(`${distPath}/${fileName}.webp`);

  sharp(filePath)
    .jpeg()
    .toFile(`${distPath}/${fileName}.jpg`)

};

Now we're generating an avif, a webp and a boring old jpg file for each image dropped into src/img.

Adding a new task to compress all images

Finally, let's add another task to our prepare command, so that all the images are generated when our second developer (we really ought to give this imaginary person a name) runs npm install.

Open up package.json and edit your prepare task, so it runs compress-all-images.js:

...
"scripts": {
    "prepare": "concurrently \"npm run sass-prod\" \"node tools/compress-all-images.js\"",
    ...
}
...

Testing out optimising all images

Delete dist/img then run npm install from the terminal. Once it's finished, you should see your img directory reappear as if by magic and be populated by each image in your src/img directory, in a mouth-watering choice of three flavours.

~~Run a task which converts all images in the src/img directory into their optimised versions in dist/img - for example when you've added some images but the server wasn't running at the time~~

Let's review what we learned:

Used the fs module from Node to elegantly handle nested directories inside src/img
Learned about short-circuit evaluation in JavaScript
Stole a utility function from Param Harrison to get a list of files and folders in Node
How we might split up a long, complicated script into modules
The shorthand which can be used in JavaScript if the name and property are the same

View Chapter 4 code snapshot on GitHub

Quiz

Chapter 3: images part one

Ross Angus — Fri, 07 Mar 2025 14:27:01 +0000

Cover image by M Mahbub A Alahi

Recap

Last time, we configured a local server and previewed our work:

We installed browser-sync so we can see the contents of dist in a web browser
Learned about escape characters
Ran more than one command at the same time
Learned about the special start command name
Installed, then removed a package because we changed our mind
Learned that if something goes wrong with node_modules we can always nuke it and start again

This lesson is all about optimising images. There's a lot to get through here, but I'm going to take it slow.

Fun break

Perhaps right now, you're feeling a bit of imposter syndrome. We are standing on the shoulders of the giants who made all this technology, and yet we are not fit to shine their shoes.

Don't worry: I have a cure for that.

Let's visit a site made by some of the best engineers the world has ever seen. How about Apple? I need you to open the home page in Chrome (sorry, Firefox - I'm cheating on you this one time). Don't dismiss the cookies or click on anything else and open the developer tools. You can do this by either hitting the F12 key or right-clicking on an empty patch of page and selecting Inspect from the pop-up menu.

There's a lot going on in the developer tools but I want you to pay attention to the tabs across the top. They list off the different parts and start Elements Console Sources Network ... I'd like you to select Lighthouse. It might be hidden behind one of these wee chaps: ».

Once the Lighthouse panel has displayed, click the Analyze page load button and wait for the results. Is everything green?

You can scroll down the report and under the Diagnostics heading, you should see a red warning triangle next to a sub-heading which reads Serve images in next-gen formats. We're going to address this problem in the next lesson, but let me ramble on about Lighthouse for a bit first.

Running a Lighthouse audit is mostly a little disheartening. Getting green scores across the board is basically impossible, if you have a marketing department which is determined to drop a 500MB auto-playing video into a popup window. And even if you don't have this problem, improving the score requires many different departments working together.

In the next lesson, we're going to do what Apple failed to do: serve all our images in "next gen" formats.

(and if you're still feeling like a bad engineer, try running Microsoft through Lighthouse)

Compressing images

When it comes to Node packages which can convert images to cutting-edge modern formats, the new hotness is Sharp. It's so bleeding-edge that we need to write some of our own tools to run it.

Sharp is designed to be called from within a Node application and can do all kinds of stuff like adding blurs, adding text, rotating or converting images to different formats. It's just the last bit we want to use.

However, it doesn't just get installed and then called, like the other plugins we've been using. We're going to have to write a few functions to get it to do what we want.

What we want to achieve

An ideal developer user experience would be the following:

You start to run your local server
You dump a bunch of images into the src/img directory (this doesn't exist yet)
Those images get automagically converted into next generation files in the dist/img directory (this doesn't exist either, yet)

You might also want to do any of the following:

Run a task which converts all images in the src/img directory into their optimised versions in dist/img - for example when you've added some images but the server wasn't running at the time
Overwrite an existing image in src/img with a new one with the same name, and have the corresponding images in dist/img update automatically
Use as many different sub-directories in src/img and have those be replicated on dist/img - for example src/img/gallery/open-day which lives inside dist as dist/img/gallery/open-day

That's a lot of features! It's easy to feel overwhelmed when seeing requirements like this. You might mentally try and solve all of them at once. Resist this temptation, if you can! Remember that computers are very, very stupid and need to be told very simple instructions. Most of our job is to take complicated tasks and break them down into very simple steps.

Creating new directories

Let's create some new directories for these images to sit inside. Add some img directories, so your Node project folder looks like this:

🗀 dist
  🗀 css
  🗀 img
🗀 src
  🗀 img
  🗀 scss
.gitattributes
.gitignore
package.json
package-lock.json

Great! Now we just need to write all the code which converts the image from one format to another. So how do we get started?

Installing another package

If you guessed "installing another package from NPM", you have earned a new achievement: "Web Developer Cynicism Level 1". Spend those experience points wisely! The package we need to install is called onchange.

Installing onchange

Inside a terminal, type:

npm i -D onchange

In order to use onchange, we need to edit package.json. Currently, the scripts node looks like this:

"scripts": {
  "sass-dev": "sass --watch --update --style=expanded src/scss:dist/css",
  "sass-prod": "sass --no-source-map --style=compressed src/scss:dist/css",
  "serve": "browser-sync start --server \"dist\" --files \"dist\" --watch \"dist\"",
  "start": "concurrently \"npm run serve\" \"npm run sass-dev\"",
  "prepare": "concurrently \"npm run sass-prod\""
}

We need to change it to look like this:

"scripts": {
  "sass-dev": "sass --watch --update --style=expanded src/scss:dist/css",
  "sass-prod": "sass --no-source-map --style=compressed src/scss:dist/css",
  "serve": "browser-sync start --server \"dist\" --files \"dist\" --watch \"dist\"",
  "start": "concurrently \"npm run serve\" \"npm run sass-dev\"",
  "prepare": "concurrently \"npm run sass-prod\"",
  "log-images": "onchange \"src/img\" -- echo '{{event}} to {{file}}'"
}

Let's break down that new command (the second half of which I took directly from the onchange documentation):

log-images - this is the name we're calling our new command. It could be anything, as long as it doesn't include spaces
onchange - when we run our task, the first thing it does is invoke the onchange method which we've just added to node_modules
\"src/img\" - this is the (escaped) path to the directory which onchange will be watching.
-- - I'm indebted to the talented and funny Ben Sinclair for clarification on what this means. This is shorthand for everything after this point isn't a flag. This means that any commands which happen to include a hyphen for the rest of the line won't be accidentally treated like a flag.
echo - this allows us to add text to the terminal. It's the same as console.log() in JavaScript
'{{event}} to {{file}}' - this is a string which is built up from two tokens {{event}} and {{file}}. This string will be echoed to the terminal (this just means that the text will appear in the terminal). These tokens are passed by onchange. What do they mean? Let's find out!

Now from a terminal, run our new command by typing:

npm run log-images

onchange runs constantly - it won't stop until we put the terminal in focus and hold down ctrl and c to cancel out of it. This means that as we update the directories, you can watch the terminal and see it update in real time.

Here's some example images to download. Save the first one to src/img and watch what happens in the terminal. You should see something like this:

"'add" "to" "src\img\h7zTxla.png'"
"'change" "to" "src\img\h7zTxla.png'"

Now save the second one, but overwrite the first. You should see the following:

"'change" "to" "src\img\h7zTxla.png'"
"'change" "to" "src\img\h7zTxla.png'"

Now try renaming the file to example-01. You should see:

"'add" "to" "src\img\example-01.png'"
"'unlink" "to" "src\img\h7zTxla.png'"

OK, so the two {{event}}s we're interested in are add and change - when these occur, we need to ... do something. And that something has to do with the value of the second argument {{file}}.

JS Module mode

First thing we need to do is tell Node that we want to use JS modules. Modules are the most modern way to use JavaScript, where every function lives in its own wee file and has a single purpose (at least that's the idea).

To enable this, we need to add a new node to package.json:

"type": "module"

This needs to sit in the "root" of package.json, as a sibling of other nodes you might recognise, such as name and version.

Something like this:

{
  ...
  "description": "A course on Node.js for front end developers",
  "type": "module",
  "scripts": {
    ...
  }
  ...
}

Passing arguments to a script

We're going to write a script (don't worry - it's a javascript) which will run and gather together all this information. But it's not going to sit inside src.

Create a new directory called tools and put it in the root of the Node application. This means it's a sibling to dist and src. The word "root" can get pretty confusing. Here's three different roots we might encounter:

The root of the Node application (where package.json lives)
The root of the local web server (that's the dist directory)
What Microsoft™ Windows™ regards as the root of the file system (this is probably the C: drive on your computer and we'll try and avoid this root as much as possible)

The directory structure of your project should look like this:

🗀 dist
  🗀 css
  🗀 img
🗀 src
  🗀 img
  🗀 scss
🗀 tools
.gitattributes
.gitignore
package.json
package-lock.json

The new file should be called image-compress.js. It looks like this:

import { argv } from "node:process";

const [node, thisFile, filePath, fileEvent] = argv;

console.log(filePath, fileEvent);

Hmm. There's a lot going on there. Let's break it down.

First thing we do is import a function called argv() from node:process. This is built into Node and allows us to examine arguments, but not in the philosophical sense. We're going to pass image-compress.js an argument in a moment.

Next, we do what is called destructuring, which is a very cool, modern way to assign a bunch of variable at the same time. Because we know that argv() is going to send us data inside an Array in a particular order, we can get ahead of the game and give them nicknames.

Finally, we console.log() two of our favourite arguments to the console. (console.log() is like echo, but in JavaScript)

Couple's therapy (passing arguments on)

Are you still running log-images? Stop that! Type ctrl and c in the terminal to kill that command.

Now in package.json we're going to update that command so it does something more useful. Change:

"log-images": "onchange \"src/img\" -- echo '{{event}} to {{file}}'"

... to:

"watch-images": "onchange \"src/img\" -- node tools/image-compress.js {{file}} {{event}}"

This works exactly the same as before, but instead of echoing to the terminal, we're passing the {{file}} and {{event}} arguments to our script. Let's see if it works.

In the terminal, type

npm run watch-images

Now return to my example image page and download the second image again. Save it to src/img and just leave the name how it is.

You should see this in the terminal:

src\img\rBZtOtY.png add
src\img\rBZtOtY.png change

This might not seem like much progress, but we're using the power of Node to see a live update of what's happening on your hard drive. But this time we can manipulate it with JavaScript.

Hang on, what's doing the image optimisation exactly?

The package we're going to install to do the optimisation is called sharp. It's quite big and complicated, so it might take a little while to finish. Let's install it! Cancel out the watch-images command which is currently running and in the terminal, type:

npm i -D sharp

This should update the devDependencies node in package.json with a reference to sharp.

Import sharp into image-compress.js and see if it works. At the top of the file, add this line:

import sharp from "sharp";

Now let's call sharp and point it as the filePath variable. Your whole file should look like this:

import { argv } from "node:process";
import sharp from "sharp";

const [node, thisFile, filePath, fileEvent] = argv;

console.log(filePath, fileEvent);

sharp(filePath)
  .webp()
  .toFile(`./dist/img/filename.webp`);

Chaining

Some functions can be "chained" together. This means that the output from one is passed to the next. So the Sharp call above could also be laid out like this:

sharp(filePath).webp().toFile(`./dist/img/filename.webp`);

It's a little harder to read so usually we indent the chained functions by one tab stop, like the original example.

Let's run the task again. In the terminal, type

npm run watch-images

Now try taking any example image and saving it to src/img. Give it a new name which doesn't currently exist inside the directory.

If everything's worked, you should see a new file inside your dist/img folder called filename.webp. Your first "next generation" image! You should be pleased.

Sensible naming conventions

But we can't call all of our images filename, that would be silly. Luckily, Node comes with a whole suite of tools called path to help us manipulate filepaths and filenames. Let's pull it into the top of image-compress.js like we did with sharp:

import path from "node:path";

Now let's see what we're working with. Change image-compress.js so it looks like this:

import { argv } from "node:process";
import path from "node:path";
import sharp from "sharp";

const [node, thisFile, filePath, fileEvent] = argv;

// The path from the root of the Node application to the filename of the image
const dirName = path.dirname(filePath);
// The image name, plus file extension
const baseName = path.basename(filePath);
// The image file extension
const extName = path.extname(filePath);

console.log('Arguments:', filePath, fileEvent);
console.log('Paths: ', dirName, baseName, extName);

sharp(filePath)
  .webp()
  .toFile(`./dist/img/filename.webp`);

Quick reminder of where we are:

onchange is passing us the path to a file which has changed, plus an event, which we're not using yet
We're loading the path into our script file
We're using Node to split this path into different parts
Those parts are being console.log()ed to the terminal, along with the original path

Testing the logs

Cancel the watch-images task, then immediately restart it (just in case Node is cacheing an old version).

Terminal history

Your terminal has a sort of history. If you want to re-use a command you've typed in the past, you can press the up arrow key (↑) on your keyboard to cycle through all the old commands you've entered. Press up and down until you find npm run watch-images again, then hit return.

Rename an existing image inside src/img to a new name (doesn't matter what). You should see an error:

Error: Input file is missing: src\img\rBZtOtY.png

What's going on here?

Right now, this code is running every time onchange detects a change inside src/img. This error is triggered because sharp can't find an image we're telling it to optimise.

Comment-out sharp, so we can see what's going on. Commenting-out can look like this:

// sharp(filePath)
//   .webp()
//   .toFile(`./dist/img/filename.webp`);

Try renaming the file again and look in the terminal. This is what I saw:

Arguments: src\img\changed.png add
Paths:  src\img changed.png .png
Arguments: src\img\temp.png unlink
Paths:  src\img temp.png .png

Remember, we've got two different console.log()s happening, but they seem to be happening twice. Why is this?

The first set of logs happen during an add event. The second happen during an unlink event. It looks like unlink is the same as deleting a file. So when I renamed a file, what really happened was that the old file was copied and added into the directory under a new name, then the old file was deleted.

We need to only run our code when the right kind of event happens inside src/img. Save another image from the example image page but this time, save it over an existing image which isn't the same image. You should see logs which look something like this:

Arguments: src\img\changed.png change
Paths:  src\img changed.png .png

When we did that, we got a change event. So the two events we need to watch out for are change and add. Let's store them in an Array, for safe keeping:

// White-list of events which should cause Sharp to generate images
const triggerEvents = ['add', 'change'];

Put this variable after the import statements. Now we need to corden off our call to sharp behind an if statement. This should only run if the fileEvent is present in our new triggerEvents Array. So the if statement should look like this:

if (triggerEvents.includes(fileEvent)) {
  sharp(filePath)
    .webp()
    .toFile(`./dist/img/filename.webp`);
}

(it's safe to comment in sharp inside the if statement)

Windows™ woes

I have terrible news for you and I, members of The™ Windows™ Community™: those kids who use Linux, MacOS and so forth giggle at us behind our backs. You see, Windows uses a backslash (\) to represent nested directories on the filesystem. The cool kids use a forward slash (/) instead. If our code is going to run elsewhere, we need to get on board.

Change your dirName variable, so it reads:

// The path from the root of the Node application to the filename of the image
const dirName = path.dirname(filePath).replaceAll('\\', '/');

This looks like it replaces \\ with /, but it doesn't. Remember escape characters? This is another example. The first backslash tells us to ignore the fact that the parser would usually ignore a backslash and to not ignore it. It's a double negative. If you're confused right now, take strength from the thought that this is a normal reaction.

What have we achieved? Let's trigger the script again and find out! Rename an existing file to something new. Your console logs should now look something like this:

Arguments: src\img\example-02.png add
Paths:  src/img example-02.png .png
Arguments: src\img\h7zTxla.png unlink
Paths:  src/img h7zTxla.png .png

Note how the dirName variable now reads src/img. Before, it was src\img. What's nice about this change is that if the same script is run on a Linux or MacOS environment, it won't break because there won't be any back slashes to replace.

Let's get rid of the Arguments console.log(). We've learned all we can from it.

Building up a path to our distribution image

We need to change the path of a changed image - for example src/img/example.png into the path of a converted image - for example dist/img/example.webp. To do this, we need to find the image directory path (img) and the file name (example).

To get the image directory path, let's write a new function!

const trimPath = (thisPath) => {
  const newPath = thisPath.replace('src', '');
  return newPath;
};

This takes a path (for example src/img) and then uses the variable we just created - srcDirectoryName - and finds the first instance of that in the path, before replacing it with ... nothing. So it removes it.

In arrow functions, if we can squeeze the code onto one line and the function returns something, we can omit both the {} and the return statement and the function can automatically return the product. And if our arrow function has exactly one argument, we can dispense with the parenthesis around it. So our trimPath function can also be expressed as:

const trimPath = thisPath => thisPath.replace('src', '');

You might prefer the longer version for clarity and I respect that decision.

Add your favourite version of this function (only one, mind!) to image-compress.js. Let's use this function to create a new variable. Put it after the file extension variable, like this:

// The image file extension
const extName = path.extname(filePath);
// The path to the source image, minus the `src` bit
const subPath = trimPath(dirName);

To get the image filename without the file extension, do a similar trick:

// The path to the source image, minus the `src` bit
const subPath = trimPath(dirName);
// The name of the image, without the file extension
const fileName = baseName.replace(extName, '');

This takes the filename (example.png) and replaces the file extension (.png) with nothing, leaving us just the name (example).

Finally, we need to stitch together a couple of strings which we'll use more than once:

const distPath = `./dist${subPath}`;

This will give us dist/img.

OK, we've got enough scraps of string to knot together into a proper path now. Change your call to sharp so it looks like this:

sharp(filePath)
  .webp()
  .toFile(`${distPath}/${fileName}.webp`);

Template literals

Using the backtick character to build up string like this more flexible than the legacy method, which looks like this:

sharp(filePath)
  .webp()
  .toFile(distPath + '/' + fileName + '.webp');

Another advantage of template literals is that they can include whitespace, so you can use whole chunks of JSON data spread out down your code, if you need to. You can switch between strings and simple JavaScript expressions by encapsulating JavaScript inside ${}.

Get rid of your console.log() in image-compress.js. In terms of what order variables, imports and functions should appear in your file, the imports should always appear first. You shouldn't call on a variable before you've declared it. Some developers say you should declare all variables at the top of your file, but this isn't always practical (what about variables which occur inside of functions?).

I personally think that if your code includes an if statement, then moving what variables you can to inside the statement helps lower the memory footprint (as they're never put into memory, if the code isn't parsed).

This would leave us with the following code:

import { argv } from "node:process";
import path from "node:path";
import sharp from "sharp";

// Destructuring the Array from Node which includes data we need
const [node, thisFile, filePath, fileEvent] = argv;
// White-list of events which should cause Sharp to generate images
const triggerEvents = ['add', 'change'];

// If the wrong kind of event triggers this script, do nothing
if (triggerEvents.includes(fileEvent)) {

  const trimPath = thisPath => thisPath.replace('src', '');

  // The path from the root of the Node application to the filename of the image
  const dirName = path.dirname(filePath).replaceAll('\\', '/');
  // The image name, plus file extension
  const baseName = path.basename(filePath);
  // The image file extension
  const extName = path.extname(filePath);
  // The path to the source image, minus the `src` bit
  const subPath = trimPath(dirName);
  // The name of the image, without the file extension
  const fileName = baseName.replace(extName, '');
  const distPath = `./dist${subPath}`;

  sharp(filePath)
    .webp()
    .toFile(`${distPath}/${fileName}.webp`);

}

We've still plenty more to do, but let's recap what we've learned:

We can use the onchange package to pass events from the file system to our JavaScript
We can run arbitrary JavaScript files directly in Node - no web browser required
Node gives us access to different methods of accessing path and filename information
Sharp is this season's must-have image optimisation package (although perhaps that's changed now, if you are reading this in the future)

View Chapter 3 code snapshot on GitHub

Quiz

Chapter 2: Previewing our site in a browser

Ross Angus — Wed, 05 Mar 2025 17:01:06 +0000

Cover image by Igor Starkov

Recap

Last time, we got through quite a bit:

created a new GitHub repo
initiated the repo
been introduced to JSON
learned how and why to split up CSS
added some directories and a landing page
installed our first package: SASS
hidden files from version control
written some SCSS files
written two package.json commands
generated our final CSS
checked our changes into GitHub

This lesson will be a little more modest in scope. We're going to try and walk and chew gum at the same time.

Previewing our site in a web browser

Wouldn't it be nice to see what our site looks like as we work? And to have the browser refresh automatically whenever we made a change to our code? Guess what - There's A Package For That™!

Type this into the terminal in VS Code:

npm i -D browser-sync

I know we've covered this before, but let's go over some of the new, hip slang:

npm - switch to Node Package Manager mode
i - short for "install", so run the install command
-D - this is the shorted form of the --save-dev flag (which ensures that none of the code for this package reaches the live site)
browser-sync - this is the package we're installing

What does browser-sync do?

Node comes with a web server built in. browser-sync allows us to spin up a server, open a web browser window and point at it and automatically refresh it, when we've make changes to the source files.

Configuring browser-sync

In package.json, add a new command to the scripts node:

"serve": "browser-sync start --server \"dist\" --files \"dist\" --watch \"dist\""

Let's break this down:

serve - this is the name for our new command. We can call it by running npm run serve inside a terminal
browser-sync - call the new browser-sync package
start - this calls the start method within browser-sync which starts the browser-sync server. This might seem redundant (why call browser-sync at all, if you don't want to start it?) but the browser-sync function does other stuff too, such as reloading or setting up an init file
--server - this flag specifies that the particular service we want from browser-sync is for it to be a fake server.
\"dist\" - this points to the "root" of this particular server. Which is dist. And because we needed to use nested quotation marks, we had to "escape" them using \ (see escape characters, below)
--files \"dist\" - this specifies a location to watch for files other than HTML - for example images.
--watch \"dist\" - this tells browser-sync to watch a particular directory for changes. If those files update, then browser-sync should automatically refresh the web browser.

Remember that because we've added a new node to package.json, we'll need to make sure that the preceding node has a comma in the right place. VS Code should show you some angry red wiggles, if you've done it wrong. Usually on the following node from where the comma should be.

Escape characters

An escape character is not the same as Harry Houdini. Instead, it's shorthand for "ignore the next thing I type". So let's say you wanted to use a double quotation mark in JSON, you couldn't just do this:

{
  "actor": "Dwayne "The Rock" Johnson",
  "character": "Harry "King of Handcuffs" Houdini"
}

... because if you did so, the strings The Rock and King of Handcuffs will escaped their quotation marks and roam free inside the JSON file.

Instead, you'd need to type:

{
  "actor": "Dwayne \"The Rock\" Johnson",
  "character": "Harry \"King of Handcuffs\" Houdini"
}

The JSON parser would read the actor value as: quote Dwayne ignore the next character, I'm not finished "The Rock still not finished" Johnson OK, I'm done now, end quote.

Testing browser-sync

Inside a terminal, call your new command using:

npm run serve

It might take a few seconds but eventually a new tab should open in your web browser pointing to your example page. And the text Hello Worm should appear. It should not be in the Times New Roman font. Note how serve is still running in the terminal.

Windows firewall warning

You might also see a warning about Windows Firewall blocking some features of this app. Click on Allow access. Browser-sync's cool.

Look at how we linked the CSS file in the HTML file (dist/index.html) using the path /css/main.css. That initial forward slash means "start from the root of the site". So if we owned the domain "node.com", the CSS file could be found at this URL: https://node.com/css/main.css. However, if we dragged the HTML file into a browser, that path wouldn't work because Windows boxes think of the root on their file system differently.

This means that browser-sync is opening the local server correctly!

Watching the SCSS

Remember the watch-scss command we wrote? That isn't currently running. Under Windows, we can't just run two commands at the same time. Until we install another package, that is!

Let's stop serve from running. Put the terminal in focus and type CTRL + C and agree to stop the server.

Installing npm-run-all

Let's install npm-run-all. Into a terminal, type:

npm i -D npm-run-all

Configuring npm-run-all

This is the new command we need to add to the scripts node of package.json:

"start": "run-p serve sass-dev"

(quick angry red wiggles check: is your package.json valid json?)

We're defining a new command but hang on - it calls run-p not npm-run-all. What gives?

Buried deep inside the source of npm-run-all is the run-p command. run-p is short for "run in parallel". This means it will run our serve command and also our sass-dev command at the same time.

What's in a name?

There's a reason we called this command start. It's a special name which is assumed to run whatever the default action of our codebase is.

Normally, when we run a command from package.json, we'd need to type the following into the terminal:

npm run my-command-name-goes-here

However, with start we just need to do this:

npm start

Let's try it out! Type the above command into a terminal and a browser window should open and display the text Hello Worm.

Now, open src/scss/_fonts/scss and add a new typeface to the front of the SCSS variable. Use "Comic Sans MS" (also add the quotation marks).

It should now look like this:

$font-system: "Comic Sans MS", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;

body {
  font-family: $font-system;
}

Your page should update with this "classic" meme font as soon as you hit save.

Change of plans

npm-run-all is nice, but I've changed my mind. Have a look at the NPM page for npm-run-all. What do you notice? I'll give you a hint: it was last published (at the time of writing) six years ago.

That is roughly the Victorian period of web development. I've forced you to bolt a steam engine to a spaceship. What can we do about this?

Out with the old

Working with Node is confusing at the best of times so I want you to know we can always reverse a mistake. Let's wrench out the steam engine and watch as it drifts away in space, leaving behind lumps of coal, glittering like asteroids. To uninstall a package from our application, we can type npm uninstall and then the name of the package. First cancel the start command with control + c and a terminal, type:

npm uninstall npm-run-all

We'll leave the package.json unchanged at the moment.

Perhaps, like me, you're suspicious of this. So in Windows Explorer, navigate to your application directory inside GitHub and peek inside the node_modules folder. There should not be a folder inside there called npm-run-all.

(try not to think about how much code is already inside node_modules. It's a black box, remember?)

The nuclear option

Sometimes, your node_modules folder gets a bit corrupt. I haven't experienced it in a while. Perhaps it was an issue which effected older versions of Node more. But here's the nuclear option: simply delete the whole directory.

Remember that node_modules won't ever live in your Git repo. So in order to build it up from scratch, in a terminal type:

npm install

This will look through your package.json file and treat it like a shopping list, tootling round the aisles of NPM and grabbing all the packages we need for a fresh install.

In with the new

OK, so what's the new hotness which replaced npm-run-all? It's called concurrently. We can tell it's the new hotness for a couple of reasons. At the time of writing:

It has multiple million weekly downloads
The repo was updated within the last month

Install concurrently by going to your terminal and typing:

npm i -D concurrently

Configuring concurrently

The syntax is similar to npm-run-all, but each different command call should be wrapped in quotes. So the command in package.json which currently reads:

"start": "run-p serve watch-scss"

... should now read:

"start": "concurrently \"npm run serve\" \"npm run sass-dev\""

(There are those escape characters again. They still look weird but you should get used to them eventually)

Let's test that out! In a terminal, run npm start. Your "Hello worm" page should load. It should still be in MS Comic Sans. Edit your _fonts.scss file so that the $font-system variable is back to normal. The variable should be:

$font-system: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;

Hit save and your browser window should automagically update with whatever counts as a normal system font in your world. Yay! Your current setup can walk and chew gum at the same time!

Collaborating

Remember when we hid the directories dist and node_modules from Git? We did that because I claimed that a new developer could download our code and derive all the dist files using just the src files.

The command we've just added will do this, but only when a developer runs the start command and happens to edit a SASS file. What about when a new developer joins the project and runs the site for the first time? There won't be any dist directory and all the files inside.

As we add more functionality to this toolkit, we're going to need to increase what needs to be done when someone first runs the site. We'll also need to add a command which you can run when you want to build all of the files for the production website. Hey! These are the same thing!

Adding a new `prepare` command

Let's add a new command to package.json. Call it prepare. It should look like this:

{
  ...
  "scripts": {
    "sass-dev": "sass --watch --update --style=expanded src/scss:dist/css",
    "sass-prod": "sass --no-source-map --style=compressed src/scss:dist/css",
    "serve": "browser-sync start --server \"dist\" --files \"dist\" --watch \"dist\"",
    "start": "concurrently \"npm run serve\" \"npm run sass-dev\"",
    "prepare": "concurrently \"npm run sass-prod\""
  }
  ...
}

prepare is a special keyword for NPM because this command runs automatically after a developer runs npm install in their terminal.

This means that our hypothetical second developer will download the repo, then run npm install and will automatically generate out all the CSS into the dist directory without realising they're doing it. And that CSS will be based on the latest version of the SCSS.

Perhaps you're wondering why we're using concurrently - we're running exactly one task. The answer is that you are at the start of a wonderful journey of discovery. During this epic quest, we'll be adding many more commands to package.json which take files from src to dist and compress them in different ways. And we'll be adding these commands onto our new prepare command as we go. It's going to be really cool, I promise.

Check-in time

Open up GitHub Desktop and check in your work. Remember to push it to GitHub too!

Summary

Here's what we've achieved in this lesson:

We installed browser-sync so we can see the contents of dist in a web browser
Learned about escape characters
Ran more than one command at the same time
Learned about the special start command name
Installed, then removed a package because we changed our mind
Learned that if something goes wrong with node_modules we can always nuke it and start again

View Chapter 2 code snapshot on GitHub

Quiz

Chapter 1: setup, CSS, version control and SASS

Ross Angus — Wed, 05 Mar 2025 16:25:33 +0000

Cover image by Rodolfo Quirós

Recap

Last time, we introduced you to a whole bunch of different software you'll need to get started with Node. This gang:

Imagine these are your new work colleagues. Some of them we'll be spending a lot of time with. Perhaps eating lunch together, maybe going out for drinks after work. Others we just needed briefly and can casually discard like yesterday's socks. Some will make awkward eye-contact with us, but we'll ignore them completely.

Today, let's get to know GitHub a little better and get our new project set up.

Create new GitHub repo

(these instructions assume you have both a GitHub account and have downloaded and installed Github Desktop)

Open Github Desktop and from the File menu, select New repository. The Name field will be the name of the folder you'll create, so although it's a little counter-intuitive, you should create the repository in the root of your GitHub folder. For example, mine is here:

C:\Users\Ross-Angus\Documents\GitHub

Think up a name for your test project. Personally, I'd keep your name lower-case and without spaces (use hyphens instead, if you like). But perhaps this isn't relevant any more and I've just got into the habit. While it's possible to change the name later, it's the sort of thing where the old name might keep cropping up and annoy you, so choose well.

I've called my version node-js-for-developers. At the end of each chapter, I'll include a link to a snapshot of my code so you can compare it to your own, in case you run into problems.

Open your new folder

From your IDE, browse to your new folder and open it. The only file inside should be a .gitattributes file.

This is a configuration file for GIT. We won't be editing this. Don't open it. I forbid it!

Allow Node to move in

Open a terminal in VS Code (from the View menu, select Terminal) and type:

npm init

The terminal will ask you a series of questions. If you feel inclined, pretend you're in the film Wargames. If you press enter, rather than answering the questions, the default answer will be chosen. Most of the defaults are sensible and don't worry - we can always change them later.

Let's break down this npm init command. We've already talked about package managers like winget but npm is a package manager we're going to use more than once. npm is also used to run commands in Node. Which is what we're doing now.

By typing npm, we're switching the terminal to npm mode, where it has access to other methods.

Calling init is one of these methods. init is short for "initiation". It sets up the current directory as the root of a new Node application. That boils down to creating a new file called package.json. We're going to spend a lot of time editing package.json. In many ways, it's the heart of the application.

Open package.json in VS Code. This is the sort of boilerplate for the repo. Or perhaps like a library card for a book, if you remember the last century. Note how your default answers to the quiz Node just made you take appear inside package.json. This is where you can change them.

This is what mine looks like currently:

{
  "name": "node-js-for-developers",
  "version": "1.0.0",
  "description": "A course on Node.js for front end developers",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Ross Angus",
  "license": "ISC"
}

Let's go through each of these, although NPM has a more detailed article.

name - this is the name of the directory for your project. Think of it as the short, computer-friendly version of your project name.
version - we'll talk about version control at the end of this lesson but this allows you to give an arbitrary number to the version. Is it bad to admit I tend to ignore this field?
description - this text appears when users search for your package on npm. Think of it like a summary of your project.
main - this is the entry point of our application. During this course, we're going to install a lot of packages which will help us to perform certain tasks. These packages will live in a folder called node_modules. Each package is a project in its own right and has its own dependences (yes, sometimes there's another node_modules directory inside the package's folder inside node_modules. How deep does the rabbit hole go? No-one knows). When Node is deciding how to load these packages, it needs an entry point to the package. That's what this node is for. Hey - guess what main defaults to, if you don't declare it? That's right - index.js. So this is useless and can be deleted. Thanks for coming to my TED talk.
scripts - we're going to spend a lot of time inside this particular node of package.json. scripts lets us give nicknames to long, complicated commands we'd usually run within the terminal. We can add as many as we want (and I'm going to add plenty). More on this later.
author - your name should be here. Next chance you get, change your profession on your passport to "Author" and refuse to elaborate.
license - this is the software licence which you're assigning to your code. It defaults to ISC which I'm going to paraphrase as "you can use this but if you die doing so, it's not my fault".

JSON files

package.json is written in json format, or JavaScript Object Notation to it's mum. It's a data format which should be familiar if you've worked with JavaScript objects. However, where it differs from JavaScript objects is it's a little more strict. In JavaScript, you could create an object like this:

const myObject = {
  firstName: "Joseph",
  surName: "Merrick",
  born: "1862-08-05",
  died: "1890-04-11",
  catchphrase: "I am not an object, I am a human being!",
  human: true,
};

If we expressed this data as JSON, we would need to place all the name properties in quotes like this:

{
  "firstName": "Joseph",
  "surName": "Merrick",
  "born": "1862-08-05",
  "died": "1890-04-11",
  "catchphrase": "I am not an object, I am a human being!",
  "human": true
}

We also couldn't have a comma on the last name/value pair, so instead of "human": true, we have "human": true.

Here's a more complicated example, with more data-types. Look at what happens to the final node within nested objects:

{
  "text-example": "This is a text example",
  "array-example": ["This value is an Array", 4, 3, 2, 1, 0],
  "object-example": {
    "nested-text": "This example contains json inside your json",
    "boolean-example": true,
    "nested-integer": 1000,
    "nested-array": [true, true, true, true],
    "last-node": "As this is the last node inside the nested object, it has no comma to the right ->"
  },
  "final-node": "No comma to the right->"
}

Our old pal VS Code will probably throw up some wiggly red lines if we do it wrong, so look out for them. If you're struggling to see why it doesn't work, try an online JSON Validator and see if it pushes you in the right direction.

With that done, let's start working on the CSS of our site.

Handling CSS

Legacy CSS

In some legacy sites you might work on during your career, you might encounter CSS files which are thousands of lines long. You probably won't have time to refactor this code (most likely you're just adding a quick fix) but when projects reach this level of complexity, the best thing we can do is to nuke them from orbit and rebuild from scratch.

How can we do this better from the start?

If we split out CSS into different files where each one is concerned with a different part of our application then in theory, when we remove a component, we can remove its CSS at the same time and not impact any other part of the site.

Of course, we could do this with existing technology by simply importing many different CSS files into each page, like this:

<!doctype html>
<html lang="en-GB">
  <head>
    <title>Lots of CSS files</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/css/fonts.css">
    <link rel="stylesheet" href="/css/grid.css">
    <link rel="stylesheet" href="/css/header.css">
    <link rel="stylesheet" href="/css/footer.css">
    <link rel="stylesheet" href="/css/typefaces.css">
    <link rel="stylesheet" href="/css/heading.css">
    <link rel="stylesheet" href="/css/bodytext.css">
    <link rel="stylesheet" href="/css/call-to-action.css">
  </head>
  <body>
    ...
  </body>
</html>

This would work! But here's the downsides:

Unless the site is served using HTTP2, each of those CSS files adds a little bit of overhead to the browser, as it needs to handshake a new connection each time to the server
Each of those files has lots of whitespace which helps us, the developers, see what's going on but is irrelevant to the browser. Why force our users to download whitespace?
Each CSS file requires a new link tag to be put into the relevant pages. If we do remove a CSS file, all those pages need to be updated.

In addition to this, we might want to use some of the power of SASS on our site.

What's SASS?

SASS is an extension of CSS which allows us to do stuff which wasn't originally build into CSS. It's been so influential that CSS has copied some of its homework.

One of its many features is that it lets us nest rules inside each other which has some advantages:

It lets us specify and class at the top level and the nested rule automatically inherits that classname
If we need to change a class name, this can be done at the root just once
It can be used to reflect the structure of the HTML, meaning there's a closer relationship between the HTML and CSS

However, it's also possible to accidentally generate a lot of CSS with relatively simple SCSS rules, so it should be used with care.

So a good solution to this problem looks like this:

We can create as many CSS (or SCSS) files as we like, in a nested directory structure if we want
When we remove an SCSS file, the final CSS file will reflect this
We can use comments in these files which won't reach the live site (this only works in SCSS, when we use comments which start with //)
All this SCSS is converted into a single CSS file
The CSS file has the minimum amount of whitespace in it

Splitting up our CSS

The first problem we want to solve is to have our CSS split into different parts which do different jobs. There's lots of different theories about the best way to do this but I'm fond of a mixture of Atomic Design for global styles and BEM for styles which only exist on one component.

That's quite a lot of homework I've just given you! What's more important than learning a methodology and enforcing it rigidly is adapting to how things are done in your current workplace.

For example, if we order our CSS rules any old way, it's difficult to spot when a declaration has been repeated, especially when the rule gets long:

.logo {
  position: absolute;
  top: 0;
  left: 0;
  border: none;
  opacity: 0.5;
  width: 200px;
  height: 150px;
  z-index: 1;
  border: none;
}

(Fun quiz: find the repeated declaration in the above rule. Now do this with any legacy CSS you encounter for the rest of your career)

I got used to ordering my declarations alphabetically, to ensure this repetition didn't happen. But then I worked on a project which enforced the Airbnb CSS / Sass Styleguide, which had a different take. And I couldn't even check code in which didn't match their method.

Try and keep an open mind about these things, because they're liable to change. And if you're in a position to change things, do so with compassion.

Make some sub-folders

With all this in mind, let's set up some directories for the files we're going to be creating. Our application will have two parts:

The source folder
The distribution folder

We're going to do all our edits on files within the source folder, then packages we're going to install in a bit will automatically copy these over to the distribution folder in a format which is web-ready. For example, an SCSS rule such as this:

p {
  button {
    border: none;
    padding: 0;
  }
}

... will end up as the following CSS:

p button{border:none;padding:0}

This kind of file is really hard to read, but downloads slightly faster.

However, we're not going to use the words "source" and "distribution", we're going to use their street names: src and dist. Your application directory should look like this:

🗀 dist
  🗀 css
🗀 src
  🗀 scss
.gitattributes
package.json

Just empty folders are fine for now.

Create a landing page

A good place to start is the HTML5 boilerplate project. We just need a simple HTML page for now. Like this one:

<!doctype html>
<html class="no-js" lang="en-GB">

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Hello Worm</title>
</head>

<body>
  <p>Hello Worm</p>
</body>

</html>

Create a new file inside the dist folder by right-clicking on it and selecting New File from the pop-up menu. Call the file index.html and then open it in VS Code. Paste the HTML markup above into it and save it.

Install our first package: Sass

Right, we've had a peek at SCSS. Let's install it!

Installing

In the terminal, type:

npm install --save-dev sass

Let's break down what each part of this command does:

npm - this invokes Node Package Manager. Think of this as switching the terminal to NPM mode (but just for the length of time it takes the command to execute).
install - this calls the install method, which is built in to NPM. It's a bit like calling a function, but this function lives within the NPM world.
--save-dev - this is a "flag" (flags start with a hyphen). NPM gives us access to many JavaScript libraries, some of which are useful just while we're developing, and some of which are useful on our actual live site. This particular package (sass) is only useful while we're developing. None of the code which helps us convert scss to css should end up on the live site. So this flag ensures that remains the case. We can see this the effect of this on package.json in a moment.
sass - this is the name of the package on the NPM database.

What's changed?

Let's look at package.json once more - the new node looks like this:

"devDependencies": {
  "sass": "^1.83.4"
}

As we've used the --save-dev flag, the package is inside a node called devDependencies. This means that the code which Sass uses won't end up on the live site.

That number (1.83.4, in my example) represents what version number of the package is installed. Note that packages age like milk - they can and will go out of date, develop security holes, fall out of development, get replaced by different packages. It's basically a nightmare.

The caret (^) symbol (yes, I had to look that word up) means "this version of sass is supported, along with all future versions".

What we've done with the install is to dump a bunch of code into a new folder called node_modules. You can think of this folder as "here be dragons". You should not edit any code inside here or check this folder into your repo. All of this code is pulled down remotely from NPM and when another developer pulls down your code, they will pull down the contents of node_modules afresh from NPM, rather than getting it from your repo.

This means your repo remains relatively small, but node_modules can get big. Like, really big. It's scary how big it gets. Try not to think about it too much, or you'll start to cry (speaking from experience).

Hide `node_modules` and `dist` from GIT

Because of what I've just said, we really don't want to check node_modules into GIT. And by "really" I mean "I forgot about this bit, the first time I tried this".

Here's what you need to do: create a new file in the root of your project called .gitignore. Here's what should be inside it:

node_modules
dist

.gitignore is another configuration file, like package.json or (don't look at it!) gitattributes. It (and stop me if I'm going too fast here) contains a list of files and directories which GIT should ignore.

That's it. GIT will now ignore any files inside the node_modules or dist directories. You can add other files and paths in this file in the future, should you need to. You might notice that your new dist folder has turned dark grey in VS Code. This indicates that you've done everything right and the contents of dist are being ignored.

Wait, why are we ignoring `dist`?

The important files in the repo are the source files. All files in the dist directory will (eventually) be derived purely from the source.

If a different developer downloaded this repo, they'd need to install it (basically download their own version of node_modules), then run it, in order to generate the contents of the dist folder.

Don't worry: we'll cover all this again. Unless I forget.

File setup

SASS takes scss files and transforms them into CSS files. Specifically, one CSS file.

We're going to use it to split our CSS up into lots of different files, then squash them all together into an unreadable mess (just like I showed earlier), but just for the live site. Let's do some setup!

Inside the src/scss folder, create two files:

main.scss
_fonts.scss

_fonts.scss should look like this:

$font-system: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;

body {
  font-family: $font-system;
}

This is a very simple Sass file which assigns a long string (the list of local typefaces) to a variable ($font-system) and them applies it to the body tag. Variables are native to CSS now, but let's pretend that isn't true.

main.scss should look like this:

@use '_fonts';

This imports the whole of the _fonts.scss file into the main.scss file. Note that any @use rules you add to your Sass files should appear before any actual CSS code. But that won't be an issue with us, as we probably won't be mixing the two in the same file.

Note the underscore as well. We'll come back to that later. (My editor informs me that foreshadowing helps to develop narrative tension. Is this working? Are you feeling tense?)

Configuring

Using our new sass package in node_modules, we can convert scss files into css files, but our site doesn't know how to yet. Let's configure package.json so it knows how to do this.

The scripts part of package.json currently looks something like this:

"scripts": {
  "test": "echo \"Error: no test specified\" && exit 1"
}

We need to change it, so it looks like this:

"scripts": {
  "sass-dev": "sass --watch --update --style=expanded src/scss:dist/css",
  "sass-prod": "sass --no-source-map --style=compressed src/scss:dist/css"
}

I've set a little trap for you here - your scripts node in package.json won't be the final set of nodes in your file. That means that the closing brace (}) should have a comma after it. Hopefully the angry red wiggles inside VS Code should indicate where the error is.

What does this mean?

Each new node in the scripts object represents a command we can run from the command line. The name part (for example sass-dev or sass-prod) is a little like a variable in JavaScript - it's a shorthand we can use to refer to the value part. The value part (for example sass --watch --update --style=expanded src/scss:dist/css) is a whole command line which runs when we type out the first bit.

Let's break down exactly what the sass-dev command does:

sass - calls the sass executable
--watch - this is the "watch" flag. This means that the sass executable will watch a bunch of directories and files for any changes, then do something. This kind of behaviour is possible in Node, but not in native JavaScript.
--update - this checks the change date of the SCSS file against the CSS file it's going to create. If the SCSS is younger, then it overwrites the CSS file
--style=expanded - this is a flag (style) with an argument (expanded) passed to it. This defines what kind of CSS will be generated. An expanded style will use what is called a source map which means even though the browser is parsing CSS, when we inspect an element, we'll see the source SCSS instead! This will be really helpful for debugging.
src/scss:dist/css - these are two paths, separated by a colon. Translated into English, this means "look inside the src/scss directory for your source files, then output them to the dist/css directory".

The underscore

Remember how the scss source had two files, main.scss and _fonts.scss? Here's the clever bit: Sass will ignore all scss files which start with an underscore. It will take the remaining files and replicate them in the target directory (in our case, dist/css). But because we've pulled the _fonts.scss file into main.scss using @use, it gets added in anyway.

Testing it out

We've defined two custom commands. Let's try the sass-prod one out. In a terminal, type:

npm run sass-prod

Quick reminder: this switches the terminal to Node Package Manager mode, calls the run function, then executes the sass-prod. npm will look inside package.json for a matching name inside the scripts node and attempt to run it.

This is invaluable when you're downloading a new project and you don't know how to make it start up. Check inside package.json to see what it does (I mean, the documentation should tell you, but it might not).

Now open up the new file which has been created inside the dist/css directory. It should be our CSS, but all squashed up. This is the command we need to run when we've finished development and we want to generate the production-ready CSS which lives on the live site. It won't be generated with source maps and all unnecessary white space will be removed.

Source maps

Source maps are a way of telling the web browser exactly where a particular bit of code is coming from. Let's say we have a style sheet called call-to-action.scss which is being compiled into a CSS file called main.css. Under normal circumstances, when we inspected an element using the developer tools, it would tell us the CSS was coming from main.css. And if we're removing all of the white space from our CSS, it will also helpfully report that the CSS appears on line one (line one is 20,000 characters long).

We can use source maps during development (and only during development) to allow the browser to point us in the right direction. They're really cool and you'll quickly take them for granted.

Let's link our new CSS file into our example page. Inside the head tag, add:

<link rel="stylesheet" href="/css/main.css">

Saving and versioning our work

Hopefully you've been saving your work as you go along (most stuff simply won't work if you don't). But now we've made a bit of progress, it's time to version our work. This takes a kind of snapshot of what we've done, so if we need to, we can return to it later.

Pointing GitHub Desktop at your files

We do this in GitHub Desktop. Open it and from the File menu, select the option Add local repository... Browse your computer for the right directory (it's probably in Documents > GitHub and whatever name you gave it) click the button Select Folder then on the next window, the Add repository button.

GitHub Desktop anatomy

The GitHub Desktop window has three parts to it. On the left is a list of all the changed files. These could be new files you've added or old files which have changed since you last checked them in. If you select any of these files, you can see the code changes on the right hand side.

This right hand side panel has two parts. If the file is already in the repo (none of our files are like this) then the left hand side will show what the file looked like before you changed it. Anything you've changed or deleted will be in scary red. On the right hand side is the same file with the new parts highlighted in green. All of our files are new, so they will all consist just of the green parts.

Finally, at the bottom right is a window for adding notes to your check-in. This has your avatar against it, to remind you that everyone will know what you typed and will judge you for it.

Commit messages, a political history

Developers take writing a good commit message very seriously and have Opinions™ about it. I wouldn't be surprised if at least one land war in Asia was triggered by a bad commit message.

Perhaps the take-away here is that a commit message isn't necessarily a summary of what you've changed - because developers can work that out from the files themselves. But it's perhaps better to say why you changed it.

For example, let's say you've been assigned a support ticket for an existing website. This ticket will have an ID and this is crucial to note in the message, as it will give anyone following you a breakdown of the whole job. But just in case the ticket is inaccessible, try and summarise why the change was made in a short message after the ID.

But before you get too attached to this methodology, remember that different work places will have different ways of doing this. One attempt to standardise the practice is Conventional Commits. Try and stay flexible and follow the best practice where you work.

Once you've completed all of these fields to your satisfaction, click on the Commit to main button.

Hang on - what's main?

A full understanding of version control, branching and merging is a little outside the scope of this course but one of the most powerful aspects of Git is that you can take a copy of the codebase off on a little detour, while the rest of your colleagues work on it in isolation. Then, once you've finished your work and someone has checked it over, it can be merged into the main trunk of the repository.

What we're doing here is considered beyond reckless - working on and checking into main directly. In the so-called real world, you'll be working on a branch of a branch of a branch. Someone much more important than a developer will merge your work into the main branch.

But you are (and you should feel a warm glow of satisfaction any moment now) the most important person in this project. You work on the main branch and live your best life.

Local and remote

Just one more small point to make about Git: you've successfully checked in your code now, but it still just lives on your local machine. This is fine, but not so good if you want to collaborate with other developers. In order for that to work you need to push your code to GitHub itself.

If you do that (and you should - aside from everything else, it's a useful backup), you can choose to make it public or private. So you shouldn't just save and commit your work, you also need to push it to GitHub.

Summary

We've done a lot in this lesson! We've:

created a new GitHub repo
initiated the repo
been introduced to JSON
learned how and why to split up CSS
added some directories and a landing page
installed our first package: SASS
hidden files from version control
written some SCSS files
written two package.json commands
generated our final CSS
checked our changes into GitHub

That's a lot. While we've only seen the output CSS inside VS Code, in the next chapter, we'll install another package which will let us see the results in the browser, just as it would appear on a server.

View Chapter 1 code snapshot on GitHub

Quiz

Chapter 0: installing and updating Node

Ross Angus — Wed, 05 Mar 2025 14:33:44 +0000

Cover image by Tima Miroshnichenko

Introduction

This is a course to introduce a developer to Node.js, as it's used in the world of front-end development. It's split into chapters and will take you through the process of building a static HTML site in a modern way using the latest tools (at least at the time of writing). There'll be jokes. There'll be quizzes. There'll be a lot of code. But we're going to take it slow, OK? OK.

This is the course I wish I could have taken as a younger developer. Hopefully it's useful to someone else.

Ground rules

I think there's two kinds of developers:

Developers who are in love with technology
Developers who want to build things

We need both! The first kind go on to become principle developers or work in DevOps. I'm the second kind.

This means when I encounter a new technology, I'm not automatically excited by it because it means I need to take days out of my life to learn it, when I could be building stuff instead.

So my first question when someone tells me about some new tech is "yeah, but why?"

I'm going to take this approach in this guide. Because we're going to encounter a lot of technology in this guide, all stacked on top of each other like the level in Getting Over it With Bennett Foddy. And at certain points, you're probably going to feel frustrated and think that web development requires an insane footprint just to render Hello world to a web page (this is a normal reaction).

Here's the thing: this guide assumes you already know how to do a bit of programming in JavaScript. But this guide isn't about programming, it's about engineering. We're going to be wearing hard-hats, hi-vis vests and boots with regulation toe-caps. We'll be building an application which others can contribute to easily and safely. This, for better or worse, is more or less what web development looks like in the real world.

Assumptions

You, the reader has:

learned a bit of CSS, HTML and JavaScript
done some tutorials and have got the hang of things
want to build something a little more complicated (perhaps you've already given it a go, and it got unwieldy really fast)
keep encountering code which doesn't make any sense and references to technology which you haven't learned about yet

Version control

This guide expects you to have an account with GitHub and to have the vague idea that version control is like saving stuff "with knobs on". Please go set one up! It's free and you'll likely use it professionally, so don't choose a silly username.

I also make use of GitHub Desktop right at the start. It's true that you can do everything in GitHub Desktop using the command line, but give me a break. I want to build user interfaces. Don't judge me for wanting to use them too.

IDE (Integrated Development Environment)

Developers these days generally edit their code using an IDE. This does nice stuff like syntactic highlighting and shows all your other files on the left. I use Visual Studio Code (it's friends call it "VS Code", but I'm more of a work colleague). It's fine!

VS Code lets you open a terminal (Windows sometimes calls this a "command line") and type commands right next to your code. This means your IDE mostly consists of three parts:

Your code
The other files and folders which make up your application
The terminal

You can open the terminal in VS Code by going to the View menu and selecting Terminal.

OS

This guide is written from the assumption that you're using a fairly recent version of Microsoft™ Windows™. Sorry. It'll mostly work in other operating systems but I've not tested it. Windows™ can sometimes be the most difficult to get this tech stack working¹.

I'm going to call "folders" "directories" in this guide because that's what the other operating systems call them. If you get into this habit, other developers will think you are 10% more cool.

Let's get started with Node.js!

Hold up - what even is Node?

Like me, I'm sure you've looked at something in the real world and thought "hmmm. It sure would be useful to manipulate that object's methods, properties or events using JavaScript". Objects such as your pet or spouse, for example.

A similar thought occurred to Ryan "Not Roald" Dahl in 2009. He wanted to expand what JavaScript could do.

JavaScript is what's called "sandboxed". Because JavaScript was originally designed to be downloaded from a distant website and executed in the browser, there wasn't any way to ensure if code was safe or not. So browsers ran the code inside sandboxed environments, where it was restricted from browsing your hard drive and looking for passwords. It was a bit like putting it in jail.

Ryan wanted a version of JavaScript which ran on the server and did have access to the hard drive. This means it could do useful stuff like squashing together a bunch of different CSS files into one big CSS file which is completely unreadable becausemostofthewhitespacehasbeenremoved or taking your boring old JPEG images and converting them into the new image formats such as (in ascending order of coolness) JPEG 2000, WebP or AVIF.

But Ryan was also wise enough to know what Node shouldn't do. He knew that as long as he focused on the core of the technology, all the other stuff would be written by other people and they could be equally focused in making their stuff do one thing really well.

Is Node installed?

All of the following technology is reliant on Node, so first, let's check if that's installed or not.

From the terminal in your IDE (probably VS Code), type:

node --version

or if you're short of time, type:

node -v

Press enter, obvs.

What we're doing here is checking if Node exists within your development environment or not. Right from the off, I want you to feel comfortable with the terminal throwing up weird messages at you. It's likely that some angry, red, bold text is shouting at you right now, claiming that Node isn't recognised or that you are bad at spelling. Try not to let the error messages upset you. Think of them as being shouted by a toddler who is cross because they need something to eat.

The two commands above mean the same thing, but the second one is the sort of street-slang version. We'll see this sort of thing a lot in the following lessons.

If Node is installed, then the second part of the command (--version or -v) will be parsed. This part is called a "flag" and works a little like an argument being passed to a function. Yes, we've called on Node, but what do we want it to do? (we want it to tell us what version it is)

Why are there two ways of saying the same thing? I guess sometimes you're in a hurry and value expediency over readability.

No Node? What now?

You can download Node as a normal installer, but where's the fun in that? Real developers use Package Managers instead.

Wait, package managers? Like the post office?

Package managers are a type of service (usually driven through the terminal) which allow you to add or remove packages to your application. They work a bit like plugins in your web browser. We'll need to install a lot of them as we go through this course.

We're going to use one package manager (winget) to install a second package manager (Node Package Manager or npm). If this seems daft to you, strap in, because there's a lot more where that came from.

winget comes built-in to Windows. Node does not. winget is only available on Windows so won't work for other operating systems. This means we need a second package manager because people who somehow manage to exist without Windows don't use winget.

So think of using winget to download npm as opening up Microsoft Edge in order to download the superior Firefox. ²

The instructions on the Node site at the time of writing look like this:

# Download and install fnm:
winget install Schniz.fnm

# Download and install Node.js:
fnm install 22

# Verify the Node.js version:
node -v # Should print "v23.7.0".

# Verify npm version:
npm -v # Should print "10.9.2".

We need to work through this one line at a time. First, type (or copy-and-paste) this into your terminal:

winget install Schniz.fnm

Next (and this doesn't seem to be covered in the instructions) you need to shut down VS Code and restart it. Not sure why this is required. Perhaps VS Code needs to sleep on it?

Let's go through this command item by item:

winget - this invokes the winget software, which is built-in to Windows. Think of this as switching the terminal to winget mode, for the duration of the command.
install - this is like a function call to the install part of winget
Schniz.fnm - this requests that we install the Fast Node Manager package from the winget package library. Schniz is the name of the user who wrote this package. fnm is the name of the package. Once we get to Node Package Manager, it works in a slightly simpler way.

Fast Node Manager (fnm)

The first thing we did - before installing Node itself even - was install something called fnm or Fast Node Manager. This is a much bigger deal that you might think.

Fast Node Manager lets us do a whole different bunch of things:

Download old versions of Node
Download a newer version of Node which has just come out
Switch between different versions of Node
Automatically use a particular version of Node for one particular project
Give these different versions of Node nicknames which only we understand (just go with it, OK?)

Why is this necessary?

Node is under active development. It's moved up three versions since I started writing this course and I expect it to release a new version by the time you've finished reading this sentence. Sometimes, these new versions break something in the older versions. Or we might use a package which relies on a technique which has changed in later versions of Node. This means we might need to run different versions of Node for different projects.

Fast Node Manager lets us switch between them quickly. It's written in Rust which is a very cool language I know nothing about other than it runs really fast and is used for mission-critical systems.

Let's continue installing Node!

We can use Fast Node Manager to install the current version of Node. But the "current version" comes in two flavours:

LTS ("Long Term Support" - not short for "latest", as I originally thought)
Current (under active development)

The Long Term Support edition (which is one version number behind current) is the "stable" release. It's been heavily tested and is only changed in order to address security holes or bugs. This is the version Node suggests you use on production environments (that's what web developers call the live web server).

The current edition has all the new features and is a little more experimental. It's useful for authors of packages (which we'll come to eventually) to check if they still work when the new version comes out.

Let's be conservative and install the LTS version of Node, which, at the time of writing, is 22. But just in case I forget to update this every six months for the rest of my life, have a quick check on the Node download page. In the terminal, type (or paste):

fnm use --install-if-missing 22

Let's break down this line:

fnm - calls Fast Node Manager
use - invokes the use function, which is part of fnm. This tells fnm that we want to change the current version of Node to a different one.
--install-if-missing - this tells fnm that if it doesn't find version 22 already installed, it should download and install it
22 - specifies that version 22 of Node should be installed. fnm won't install the version number 22.0.0. Instead, it will look for the very latest version of release 22 which has come out. Reminder: if you're reading this in the future (the only possible outcome, due to the linear nature of time), the number on the Node site might be bigger now. I think this is due to inflation.

Finally, we get to check which version of Node we have installed, which is where we got into this whole sorry mess in the first place. We do this with the commands:

node -v

... for Node and:

npm -v

... for Node Package Manager.

Great work, team!

Configuring the environmental variables

For reasons the authors of Fast Node Manager are keeping a closely guarded secret, we now need to configure some environmental variables. This used to be part of the install process of Node but with the latest versions, they've removed it. Perhaps someone decided the learning curve was looking a little shallow.

You'll encounter environmental variables during your career but in this context, they're basically the settings for Node. But before I get into how to change them, I'll need to introduce you to PowerShell. We've talked about the terminal and how that's what the cool people call the command prompt. But Windows these days comes with a sexed-up version of the command prompt called PowerShell. It's what's running inside VS Code when you open the terminal.

We can create a profile for PowerShell by typing this into the terminal:

if (-not (Test-Path $profile)) { New-Item $profile -Force }

This is an if statement which tests if PowerShell has a profile or not, and creates one if it doesn't. Whichever version of reality you live in, after you've run this, a profile will exist for PowerShell. You can open this profile by typing this into the terminal:

Invoke-Item $profile

I like the idea of Invoke-Item. Makes me feel like a wizard. An empty file will probably appear. Not in VS Code, but in something horrible like Nodepad. Add the following line to it:

fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression

Save the file and close it. Close, then re-open VS Code for good measure. I'm not 100% sure this is required, but we need PowerShell to load its environmental variables from scratch and it seems sensible. Sometimes, web development is indistinguishable from superstition.

Here's what I think is going on with the line we added to the PowerShell profile:

fnm - now we've installed Fast Node Manager, we're calling it for the first time, which is a little like switching the terminal to fnm mode.
env - this sets a new environmental variable
--use-on-cd - hey, I remember this! This is a flag! This particular flag allows fnm to switch Node versions on the fly. For example, let's say you need to edit a Node project which requires an antique version of Node. fnm will find a configuration file in the root of the project and then use an older matching version of Node.
--shell - a "shell" is another word for "terminal". Or command prompt. This flag allows us to choose a shell to assign this environmental variable to, even though it appears inside the profile file for PowerShell.
poweshell - this confirms that the shell we want to assign this environmental variable to is PowerShell.
| Out-String | Invoke-Expression - Full disclosure: I can't find either of these commands in the documentation. Let's spin this as a learning experience. Sometimes, we have to use commands we don't fully understand and just have faith in how they work. (Did that sound convincing?)

Updating Node

Wait, we've just installed Node and we already need to know how to update it? Yup. The world of Node moves very quickly but by default, Node (or more accurately, fnm) keeps us locked into the version we first installed. This is to ensure that any breaking changes introduced with future versions won't break old code.

fnm lets us juggle multiple version of Node which we can swap between on a whim. Just for fun (YMMV), let's get fnm to list all the versions of Node it knows about. In the terminal, type:

fnm ls-remote

ls is short for list. So this asks fnm for a list of all the different Node versions it's possible to use. Let's install whatever the stable version is this week. In the terminal, type:

fnm install -lts

You might recognise the -lts flag from earlier - it stands for "long term support". If Node has moved up a level or two since you last installed it, this will automatically pull down the new version. However, we won't automatically use it. Let's see what versions we have locally installed. In a terminal, type:

fnm ls

My console shows this:

* v22.13.1 lts-latest
* v23.7.0 default
* system

The line highlighted in blue in your terminal will represent the version of Node which is currently in use. In order to switch to a different one, you can either use the version number like this:

fnm use 22.13.1

... or the alias (I called it a "nickname" earlier), like this:

fnm use lts-latest

List off your Node versions again and the blue highlight should have moved to lts-latest. You can double-check this by typing:

node -v

Uninstalling old versions of Node

If you have a version of Node you're no longer using and which is just cluttering up your hard drive, you can remove it using the uninstall command. It works like this:

fnm uninstall 20

Updating Fast Node Manager itself

According to the GitHub page, updating fnm should be as easy as typing this into the terminal:

curl -fsSL https://fnm.vercel.app/install | bash -s -- --skip-shell

I couldn't get that to work but there's an easier way: you can download the code directly from the releases page and install it like a normal Windows application (the one you want is probably fnm-windows.zip).

Summary

That was quite a lot to take in, but we're still laying the (metaphorical) foundations for the beautiful website we're going to build. Where this metaphor breaks down is that we tend to think of foundations as being stable. And Node is under active development which means things change all the time.

Most of the time, this won't impact us. We can update to the latest version of Node and our code will sit on top quite happily.

Why do things change so much?

New exploits and vulnerabilities are constantly being found in web servers and Windows itself. It's why your computer keeps nagging you to restart every so often. But the good news is this: nothing we write in Node will end up on a web server. All of this code is in service of generating nice, comfortable, flat HTML pages (at least on this course). So even if we do encounter terrible security holes (and we will), it won't harm the site you build. But we'll cover that as we go.

Quiz

Where as in other operating systems, you can nest quotation marks like this: "Here is the outer quote 'here is the inner quote' and we are back outside again", in Windows we can't use single quotes and we need to "escape" the inner quotes. We'll be covering this in more detail later. ↩
It hurts to make this joke because I prefer Edge to Chrome. ↩

Forem: Ross Angus

[Boost]

How to talk to people

Mobile tables

Don't bore us, get to the chorus:

How this works

Using floats for layout? In the 21st century?

Where this breaks down

Workarounds

Native CSS carousels and positioning controls

Chapter 8: HTML part three

Recap

Watching fragments

Generating all HTML

Choosing how much HTML to generate

Back to fragments again

Using rebuildAll to decide what to do

Testing it out

Building all HTML files on first run

Updating package.json

Passing complicated markup to a HTML module

Nesting modules

Summary

Quiz

The end

Stretch goals

Auto-resizing images

Linting

TypeScript

Chapter 7: HTML part two

Recap

Images in HTML5

The srcset attribute

The picture tag

Revisiting our markup

Limitations of this approach

Adding a second page

Calling PostHTML

The page has updated

Adding a new folder

Call PostHTML

Calling callPostHTML from inside html-update.js

Quiz

Chapter 6 HTML part one

Recap

Working with HTML

MVC

JAMSTACK

Installing PostHTML, posthtml-cli, posthtml-modules and htmlnano

Should I even care?

Configuring PostHTML

Setting up the new commands

More new directories

What the new package.json commands mean

onchange watching two different directories

Adding the new commands to the start and prepare commands

Moving and splitting the HTML

Summary

Quiz

Chapter 5: JavaScript

Recap

JavaScript

Introducing Webpack

Installing Webpack

Configuring Webpack

Bespoke configuration file

Wait, if it's fancy JSON, how come each node ends with a comma?

Setting up our directories

Add your entry point

Loading the configuration into Webpack

Adding in a production build

Installing webpack-merge

Splitting up our configuration

Remind me: why do we need a development and production mode configuration?

Testing it out

Adding a production configuration

Immediately Invoked Function Expressions

"use strict"

Adding in our new commands to package.json

Testing out the production JavaScript

Using `rebuildAll` to decide what to do

Updating `package.json`

The `srcset` attribute

The `picture` tag

Calling `callPostHTML` from inside `html-update.js`

What the new `package.json` commands mean

Adding the new commands to the `start` and `prepare` commands

Adding in our new commands to `package.json`

Adding `watch-images` to our `start` task

Use `getFiles()` to pull in a list of the images

Making `image-compress.js` more modular

Adding a new `prepare` command