DEV Community: Jonathan Land

Live-updating Sass in Eleventy and WordPress with Gulp and BrowserSync

Jonathan Land — Tue, 14 Sep 2021 00:00:00 +0000

I love Sass. Not SCSS, mind you. I'm talking about the original Syntactically Awesome Stylesheet syntax, AKA The Indented Syntax. It's not that I'm particularly old-school, or that I don't see that value in SCSS being a superset of CSS. It's just that I hate looking at extraneous pointy shapes in my code, and Sass gets rid of the sharpest, pointiest ones — {, }, and of course ;. It might seem a weird thing to care about, but being a visual designer is, among some wonderful things, a bit of a curse.

Needless to say, I'm always on the lookout for the best way to integrate Sass in whatever environment I happen to be working. The best DX, in my opinion, it when style changes are injected on to the page without needing to reload. It's the kind of thing you get with HMR-capable build tools (Vue CLI, Vite, etc.), and the result is instant feedback with minimal interruption.

Environment

When I'm building with non-JavaScript-centric tooling, Gulp has been my trusty go-to for years. I use it to orchestrates the bundling of my CSS and JavaScript, and every time I think to myself "Yeah, I could probably do that in Node scripts", I end up finding a new reason to stick with it.

One tool I consistently use with Gulp is BrowserSync. If you're not familiar, BrowserSync is a nodeJS utility that sets up a local server. It's the engine behind Eleventy's watch mode, and can do a ton of cool things to speed up development. Critically, the watch option allows BrowserSync to update the browser, whenever it detects a change to files. An amazing sub-feature of this watcher is that it can inject CSS changes without reloading, very similar to HMR.

Eleventy

The setup for Eleventy was a bit tricky to figure out, but works very well. The gist of it is to send the bundled files directly to the output folder (Elevnety's default being _site), and tell Eleventy's BrowserSync instance to watch for changes. It looks like this:

// gulpfile.js

const gulpSass = require('gulp-sass')(require('sass'))

const sass = () => gulp.src('path/to/sass/files')
  .pipe(gulpSass.sync({ outputStyle: 'compressed' }))
  // ... fun gulp stuff
  .pipe(dest('./_site/assets/css'))


// .eleventy.js

module.exports = (eleventyConfig) => {
  // ... fun eleventy stuff
  eleventyConfig.setBrowserSyncConfig({
    watch: true,
  })
}

This extends Eleventy's BrowserSync settings, adding the watch option on the project's folder. And the wonderful thing about this is that, by default, BrowserSync will inject CSS changes rather than reload the page.

It took me while to get to this because I was previously using Eleventy's addPassthroughCopy to send bundled assets to the _site folder. I thought that would be the only way to have the page update every time a change was made. But it turns out all I needed to do was tell the BrowserSync instance itself to watch for changes.

WordPress

Another great feature of BrowserSync is the ability to proxy existing local servers and watch their underlying folder for changes. Assuming my local WordPress server is at http://website.local (I use Local for all my WordPress sites), I can add the following to Gulp:

// gulpfile.js

const browserSync = require('browser-sync').create()

exports.serve = () => {
  browserSync.init({
    proxy: 'http://website.local',
  })
  gulp.watch('path/to/sass/files', sass)
}

const sass = () => gulp.src('path/to/sass/files')
  .pipe(gulpSass.sync({ outputStyle: 'compressed' }))
  // ... fun gulp stuff
  .pipe(dest('output/path/for/css/files'))
  .pipe(browserSync.stream())

First I initialize a BrowserSync instance at the top of my serve function, and then I pipe the stream method to the sass stream. Now, instead of pointing my browser at http://website.local, I can run gulp serve and go to http://localhost:3000 (the address and port are configurable, but I tend to stick with the default on this). Any time Gulp processes my Sass, it will stream (i.e. inject) the changes automatically in the browser.

Build your personal toolbox with git submodules

Jonathan Land — Thu, 09 Sep 2021 00:00:00 +0000

No matter what web-based thing I'm building, there are some bits of code I've come to rely on. It started with css reset (am I alone in never having designed a website with an eight-pixel margin on the page and a forty-pixel margin to the left of all bulleted lists?). Then, once I was pleased with a few Sass mixins I had written, I found myself copy-pasting them at the start of every new project. But since I was improving and fixing them all the time, I'd have to make sure I was copying from the most recent project. Going back to work on older projects meant copying back all the newer changes, and praying it all held together. As one might imagine, it often didn't.

The only reason I got away with this was that I was a one-man-team. I can't imagine inflicting this anti-system on a fellow developer.

"There must be a better way!", I thought. "I need a way to place the same code in every project, and synchronize changes everywhere". Fast forward some trial and lots of errors, and here's the solution I've landed on:

git submodule

Among its many hard-to-discover tools, git supports something called submodules — essentially allowing us to use one repo (for our purposes, let's call it the toolbox) inside another (say, our project) and track it independently. You can read all about it in the docs, if you have the time, but it basically goes like this:

Have a repo you want to add into your project.
Run git submodule init in your project folder to tell git you're going to track submodules. This creates a .gitmodules file, that'll track what submodules you're using.
Run git submodule add <repo origin url> in your project folder, and watch the magic happen.

The magic, in this case, is git cloning the toolbox's repo into a subfolder of your project. By default it'll use the repo's name, but you can change that by specifying the desired path at the end of the add command.

Now the project has access to everything in the submodule. The project files and submodule files live side-by-side, so you can easily make changes without needing to change contexts. These changes will be tracked by git separately, so the project repo will only know if any changes were made to the toolbox repo — it doesn't care what they are. Conversely, you can add the toolbox repo to any number of projects, and it won't know anything about them.

Once you've made changes to the toolbox, you can commit and push them to the toolbox's origin by cding into the subfolder and running the usual git commands. Once you've pushed changes to the toolboxou can run git submodule update --remote --merge in the root folder of any other project that uses it — that'll pull in changes from the remote origin and sync everything up.

The final technicality I should mention happens when cloning projects that already have submodules added to them. You'll need to add the --recurse-submodules flag to the git clone command, to make sure the submodule is cloned in together with the project.

What's in the box?

So what should we place in our shiny new toolbox? Anything we've ever found ourselves copying and pasting, basically — snippets, mixins, directives, functions, macros, what have you. My personal toolbox is mostly Sass and JavaScript functions for common interactions.

For example, I've found that most websites I build end up having a sticky header that changes style once the user has scrolled a certain amount. It's a common pattern, and the kind of code you can easily find yourself writing again and again. Instead, I've written a generic headerClass function that sets it all up, targeting elements with data attributes. To make it versatile, the function uses parameters with defaults with an optional offset and data attribute overrides.

Now, when I build a new kind of functionality on a site and I think I might need it in the future, I'll write it as part of my toolbox right from the start. And later, when the next project inevitably requires expanding it or add customization options, I know I'll be able to safely pull in these changes into older projects as well.

Another great use for a toolbox like this is Sass functions, variables and mixins. For example, I can't count how many times I've used my simple +flex-center mixin:

=flex-center($direction: column)
  display: flex
  flex-direction: $direction
  justify-content: center
  align-items: center

Sure, I could write those four lines each time. But it's just the kind of thing I want to solve once and, if possible, never think about again.

Just be careful

As with all things software, the one major thing to be aware of is the potential damage of breaking changes. It can be a bit of a footgun for your project code to depend on toolbox code that can change on pull. If you can avoid breaking changes by writing smart, resilient and backwards-compatible toolbox code, go ahead. For us humans, though, a measure of control can be achieved by checking out a specific branch, tag or commit of the toolbox. Remember — inside the toolbox's subfolder, you're essentially in a separate repo.

Over the years I've split my toolbox into separate repos for Sass, JavaScript and PHP. Feel free to peruse, and apologies in advance for the mess — this may be my most idiosyncratic code ever. No warranties :)

Optionally chaining String.replace()

Jonathan Land — Thu, 01 Oct 2020 00:00:00 +0000

Using ternaries and a bit of regex magic, we can add inline logic to String.replace() statements. Here's a slightly contrived example, using the named function parameters pattern:

const presentableUrl = (fullUrl, { removeProtocol = true, removeWww = false } = {}) =>
  fullUrl
    .replace(/(https?:\/\/)/i, removeProtocol ? '' : '$1')
    .replace(/(www\.)/i, removeWww ? '' : '$1')

How

What's going on here, you ask?

String.replace() has two important properties: It returns a new string, so we can chain calls; and it allows us to replace a substring with any matched group in the search pattern. This is done with a special string like '$1', where the number after the $ represents the index of the group, counting from 1. This means that by grouping our entire pattern (i.e. surrounding it with round brackets), we can then refer to the entire match as '$1'.

We then use the original match as the falsy expression of a ternary statement. This means that if the condition evaluates to false, it returns an identical string, effectively short-circuiting that specific replace.

So the line

fullUrl.replace(/(https?:\/\/)/i, removeProtocol ? '' : '$1')

can be translated to pseudocode as

replace _match_ with
    if removeProtocal is true
        ''
    else
        _match_ /* replace it with itself */

Why

Writing functions that perform a sequence of string transformations is quite common. In most cases we want the functions to be pure — a string goes in, a string comes out, and that's that. Simple. One-linery. Arrow-functiony.

However, if we want relatively generic functions, we sometimes need to allow optional transformations. So where do we insert that condition in our function's logic? We could just put it in an if statement. The earlier example would become:

function presentableUrl (fullUrl, { removeProtocol = true, removeWww = false } = {}) {
  let url = fullUrl

  if (removeProtocol) {
    url = url.replace(/https?:\/\//i, '')
  }

  if (removeWww) {
      url = url.replace(/www\./i, '')
  }

  return url
}

A bit of cringe-worthy, isn't it? We now have internal variable to track, and any condition we add in the future brings along another if statement and 3 lines of code. It's gonna get long. Also, it's not immeadtely clear from looking at this function that all it does is string in,string out — someone (e.g. future us) could accidentally add non-pure functionality to it, and it wouldn't be immediately obvious.

This is exactly the kind of problem that arrow functions and ternaries help us solve.

When

I've tagged this pattern an Elegant Footgun™, and it defiantly makea it easy to shoot yourself in the foot.

Code-superlatives like "beautiful", "elegant" and "readable" can be very personal and depend on many factors. Personally, I find this pattern to be an elegant, readable expression of simple logic ("beautiful" would be pushing it).

I'm also emotionally prepared for the day I find myself staring at my code, trying in vain to re-understand my own cleverness. If that day comes, I hope I'll be gald I wrote this article.

Named function parameters in ES6

Jonathan Land — Mon, 14 Sep 2020 17:42:01 +0000

By adopting destructured objects with default parameters in place of regular parameters, we can make our reusable functions highly versatile and resilient. This allows them to grow in functionality over time, without refactoring call sites.

How

The basic idea is that instead of writing a function like this

function myFunction (myString, myNumber) { /* ... */ }

we write it like this

function myFunction ({ myString = '', myNumber = 0 } = {}) { /* ... */ }

What is all this curly-braces-and-equals-signs nonsense, you ask? It might not look very intuitive, but all we're doing is grouping the parameters in a single object and giving them default values.

Let's break it down. ES6 provides two amazing language features — default parameters and object destructuring.

The first is a way to provide defaults to regular function parameters. The syntax is rather simple:

function myFunction (myString = '', myNumber = 0) { /* ... */ }

Just add an equals sign and a value. The value could also be a boolean, an object, an array, or even null. This is very useful for making parameters optional, so that rather then defaulting to undefined they have a value to fall back on.

"Defaults! Great! Reming we why we're bothering with all the destructuring business?"

Well, if you're absolutely positive that you'll never, ever, ever, ever, ever change anything about what any of your functions do, ever, you can stop reading here.

Still here? I had a feeling.

The short answer is that function parameters are indexed by their order, whereas objects are indexed by key. Here's the longer answer, after which we'll look at a real life example.

Why

Javascript is a very (very!) loosely typed language. The kind of loose where {} + [] === 0 returns true. Seriously. This forgiving nature of the language is by design, and in many cases a great benefit. When we write client-side Javascript, we know almost nothing about the environment in which our code is going to run — what operating system, which browser, what browser version, even which Javascript runtime will be running it or what it supports. It's all quite dynamic, in ways that programmers from other fields might call crazy. But it's our web, and we love it.

Forgiving can easily turn into confusing, though. Worse, loose typing makes room for the kinds of bugs that, once fixed, leave us feeling utterly silly. Like confusing the order of arguments in a function call. Switch a DOM element parameter with some boolean flag, and suddenly you're hit with a not-as-helpful-as-it-seems-to-think TypeError, telling us that, apparently, the browser Cannot read property 'foo' of undefined. Since Javascript treats the arguments passed to a function as an array, their names have no meaning outside of it.

This can become a real problem when we want to add functionality to an existing function. The only way to be sure it won't break all existing calls, is to add the new parameter at the end, and make sure the function can handle the new parameter possibly being undefined.

This can get problematic very quickly.

Real Life Example™

Say we have a (simplified) function that sets up a slideshow for each slideshow container in the page:

function setupSlideshow (interval) {
  document
    .querySelectorAll('[data-slideshow-container]')
    .forEach($container => {
      const $slides = $container.querySelectorAll('[data-slide]')
      let currentIndex = 0
      function setIndex () { 
        $slides.forEach(($slide, slideIndex) => {
          $slide.toggleClass('active', slideIndex === currentIndex)
        })
      }

      // ... all kinds of code to track state, looping, etc

      const timer = setInterval(() => {
        setIndex(currentIndex + 1)
      }, interval)
    })
}

setupSlideshow(3000)

So far so good. We get the slideshow container and the slides, we track an index, we toggle a class, and we change slides every n milliseconds, based on the single parameter.

And then life happens

We successfully use this function for several sites, only to find ourselves in a bit of a pickle — in our current project, we can't use active as the toggled classname. Oh, and we need to add customizable classes to the previous and next slides, as well. Oh, and wait, the container can't have data- attributes on it, so it has to be selected by class name.

Technically this isn't much of a problem, and adding the required parameters (with defaults!) seems simple enough:

function setupSlideshow (
  interval = 3000, 
  containerSelector = '[data-slideshow-container]', 
  toggledClass = 'active', 
  prevClass = 'prev', 
  nextClass = 'next'
) {
  /* ... */
}

setupSlideshow(3000, '.slideshow-container', 'current-slide')

Amazing work!

On our next project we find that the defaults we set are great. But for whatever reason, we need to customize just the previous slide class name. This means w'll need to explicitly pass all the earlier arguments as well:

setupSlideshow(
  3000, 
  '[data-slideshow-container]', 
  'active', 
  'special-classname-for-a-super-special-slide'
)

"My defaults! [sobbing] My beautiful defaults!"

I know how you feel. Not to mention, looking at this function call, it might not be clear what each parameter is. "Everybody knows that the 3rd parameter of a slideshow setup function is the toggled class name" said no one, ever, hopefully.

Destructuring to the rescue!

What if our function was constructed like this:

function setupSlideshow (args) {
  // ...
  const $slides = $container.querySelectorAll(args.toggledClass)
  // ...
}

const myArgs = { toggledClass: 'active', /* ... othes */ }
setupSlideshow(myArgs)

Explicit argument naming! No more indexing by order! But, alas, where have all the defaults gone?

We could use a default parameter for args:

function setupSlideshow (
  args = { toggledClass: 'active', /* ... others */ }
) {
  /* ... */
}

But object destructuring inside the function's parameters allows us a more elegant way of writing essentially the same thing:

function setupSlideshow ({ toggledClass: 'active', /* others */ } = {}) {
  /* ... */
}

Basically we're passing in a default args object, and using an additional default (that's the weird-looking = {} at the end) to make sure the object is never undefined. Kind of like a default for the default, just that it applies to each value on the object. This means that whatever key-value pairs we don't pass in our call will just default.

So we can write our function as

function setupSlideshow ({
  interval: 3000, 
  containerSelector: '[data-slideshow-container]', 
  toggledClass: 'active', 
  prevClass: 'prev', 
  nextClass: 'next'
} = {}) {
  /* ... */
}

setupSlideshow({
  prevClass: 'special-classname-for-a-super-special-slide'
})

and all of the unspecified values will be set to their defaults when the function runs.

The next time we need to add more customization, we can just add it to the object, anywhere we want. This can be very important when reusing the same code in many projects — we can add new customization options without breaking old function calls. Say we need an autoplay parameter:

function setupSlideshow ({
  interval: 3000, 
  containerSelector: '[data-slideshow-container]', 
  toggledClass: 'active', 
  prevClass: 'prev', 
  nextClass: 'next',
  autoplay: false
} = {}) {
  /* ... */
}

setupSlideshow({
  autoplay: true
})

Assuming the function's internal logic does nothing different if autoplay is false, all of the existing calls will keep working with no change.

Another advantage of this pattern is that we can easily separate required arguments from optional ones — anything without a default can be a regular parameter, and everything optional can be in our single object:

function setupSlideshow (slideshowUniqueId, {
  interval: 3000, 
  containerSelector: '[data-slideshow-container]', 
  toggledClass: 'active', 
  prevClass: 'prev', 
  nextClass: 'next',
  autoplay: false
} = {}) {
  /* ... */
}

setupSlideshow('slideshow-5', {
  interval: 7000
})

Conclusion

On the web, as in life, change is (sometimes) the only constant. Writing code that can change gracefully is an important skill, and it's worth it to always be asking yourself "what if this bit needs to change at some point?".

It's a bittersweet irony that dynamic typing sometimes leads to rigidity. Flexible coding can help.

Functional Computed Properties in Vue Components

Jonathan Land — Mon, 14 Sep 2020 17:39:12 +0000

Computed properties are easily one of my favorite expressions of Vue's reactive paradigm. They allow us to store a reference to a result, abstracting the tracking of changes and cleaning out logic from our templates¹.

Sometimes computed properties are complex units of logic, running loops, building internal data structures and finally churning out a result. More often, though, I find myself using them for simpler things — concatenating strings, multiplying one thing by another, mapping an array of objects to expose specific properties. Exactly the kinds of jobs that arrow functions were made for.

How

Functional computed properties are written in the following way:

computed: {
  fullName: ({ firstName, lastName }) => firstName + ' ' + lastName
}

Let's break that down. The regular syntax for that computed property would be:

computed: {
  fullName () { 
    return this.firstName + ' ' + this.lastName
  }
}

Not too bad, but a bit verbose. If we were writing regular old ES6, outside of a Vue component, we'd probably want to turn that into an arrow function. However, inside our component the following code wouldn't work:

// DOES NOT WORK

computed: {
  fullName: () => this.firstName + ' ' + this.lastName
}

That's because a central feature of arrow functions is that they bind their parent's lexical scope, which is a fancy way of saying that they don't have their own this. We would end up with a TypeError, telling us that this is undefined.
So we know we need to get our component's this into the function, but from where? Well, it turns out that Vue injects the whole component as the only argument of every computed property! That how we have access to this in the regular syntax. You can test this for yourself like this:

computed: {
  testThis () { 
    console.log(arguments)
  }
}

Javascript's magical arguments variable represents an array of all the arguments provided to a function. Once you load the component, you'll see in the console an array containing a single object — your Vue component, complete with your data, computed, methods, $root etc.

So now we can write our property as:

computed: {
  fullName: (this) => this.firstName + ' ' + this.lastName
}

The final touch is destructuring this, pulling in only the properties we need:

computed: {
  fullName: ({ firstName, lastName }) => firstName + ' ' + lastName
}

Why

So what have we gained? Well, for starters we've turned our 3 lines into a punchy one-liner. We've made it clear that this is a function that takes in some values and returns a new value, with no side effects. Finally, we've made it explicit what data the computed property depends on and tracks — no matter what other data is in the component, we know that this property can only depend on the values we've provided it.

If we have many computed properties, they're easier to skim and reason about:

computed: {
  fullName: ({ firstName, lastName }) => 
    firstName + ' ' + lastName,

  shortNameToDisplay: ({ firstName }) => 
    firstName || 'Please enter your name',

  isInFirstNamesList: ({ firstNamesList, firstName }) => 
    firstNamesList.indexOf(firstName) !== -1,

  // we can even call the fullName computed property, 
  // since it's available in the component as this.fullName
  nameUrl: ({ baseUrl, fullName }) => 
    baseUrl + '/' + fullName.toLowerCase(),
}

A great use case is for 'destructuring' props to simplify templates in presentational components:

<template>
  <img :src="photoUrl">
  <h3>{{ firstName }}</h3>
  <p>{{ bio }}</p>
</template>

<script>
export default {
  name: 'PersonCard',
  props: {
    person: { type: Object }
  },
  data () {
    baseUrl: 'https://foo.bar/baz'
  },
  computed: {
    firstName: ({ person }) => person.firstName,
    bio: ({ person }) => person.bio,
    photoUrl: ({ baseUrl, person }) => baseUrl + '/' + person.photo
  }
}
</script>

When

As a rule of thumb, functional computed properties (and arrow functions in general) are most useful when their logic is simple and requires no temporary variables. If you think of your property as "this thing in relation to that thing", it's probably a good candidate.

On the other hand, as soon as you find yourself adding braces to a functional property and running logic before you return, it's probably time to refactor back to the regular syntax. Remember, the improvement here is solely to code readability, so the question should always be "is this easier to understand?"

As per the recommendation of the Vue style guide ↩