DEV Community: mattstobbs

5 Reasons To Use TypeScript

mattstobbs — Thu, 28 Oct 2021 12:51:54 +0000

This post was originally posted on my blog, 5 Reasons To Use TypeScript. Some changes have been made from the original post to fit the styling of dev.to. I recommend reading the post on the original site to see it styled as intended.

The rise of TypeScript seems to have happened slowly, then all at once (like ketchup coming out of the bottle).

Over the past five years, it has continued to grow in popularity until it is now by far the most liked "JavaScript flavour". According to the State of JS 2020 survey, TypeScript is now one of the most used frontend technologies and one with the highest positive opinions.

As I mentioned in my previous post, I was sceptical, but have grown to love TypeScript so that I would recommend it as the default flavour for any new JavaScript project. TypeScript had so many benefits that I hadn't appreciated before I tried it.

In this post, we'll take a look at five of those benefits:

Compile-Time Errors
Clearer Code
Tooling Over Documentation
Safe Refactoring
Incredible Autocomplete

1. Compile-Time Errors

Let's get this out of the way first - the obvious benefit to using TypeScript is compile-time errors for type safety.

Did you forget to check if a value is null? Typescript won't.

Missed a case in a switch statement? Typescript won't.

Added an argument to a function but overlooked the existing uses of the function? Typescript won't.

This is generally how people describe TypeScript. It means that, from my experience, when people are hesitant about whether TypeScript is worth the extra effort, this is all they're thinking about.

Compile-time errors are useful, but it's the secondary benefits that you get because of the type checking that makes TypeScript really exciting.

2. Clearer Code

TypeScript requires you to be more explicit with your code and with your mental model of how the code works.

It is said that writing forces you to clarify your thinking. It's so hard to write what's in your head - attempting to write it down forces you to organise your thoughts, challenge your assumptions, question whether there is a better way. TypeScript is the equivalent of frontend development.

Programming is hard. There are huge amounts of complexity. TypeScript restricts the freedom of JavaScript, but by doing so, it reduces the complexity of the code. This makes it a lot easier to catch bugs and move forward with confidence with what we're writing.

TypeScript reduces the complexity of the code. That may surprise you. One of the common complaints against TypeScript is how complicated it is. Sure, the basic use cases may be easy, but pretty soon you're down a rabbit hole with type-generics and conditional types and you're spending more time reading the TypeScript documentation than actually coding.

When this happens to me, 9 times out of 10 that's a flag that my code is too complicated. When I think about what I'm trying to do, I can usually simplify my data structures and function signatures. The advanced parts of TypeScript are positive friction, slowing me down enough to question whether there are better ways of designing my app.

"If you find yourself struggling with writing types or you're basically spending time developing your types instead of developing your app, maybe the code you're writing is too complicated." - Ben Ilegbodu

3. Tooling Over Documentation

Documentation is essential for the long-term health of a project. However, it's also easy to neglect, hard to enforce, and can't report if it is no longer up-to-date. So if it's possible, tooling should be prioritised over documentation.

When I started working at a new company, part of my onboarding involved reading the company's coding style guide. I skimmed through it, but very little stayed in my head. I told myself once I was coding, I would refer back to the style guide to make sure I was following the standards. Unsurprisingly, I never did.

Tools like ESLint and Prettier document your code styles. But they go a step further and enforce those styles while you're coding. You no longer need to worry about stray console.logs or inconsistent semi-colons. Instead of the style guide being one extra thing you have to hold in your head, it becomes something you don't even have to think about. You just focus on what really matters.

TypeScript is a tool that forces you to extract knowledge out of the developer's head and into the code. It documents what arguments a function is expecting, what shape objects are, and which variables may be undefined. And it will remind you when it is no longer up to date and where exactly you need to update.

Without TypeScript, so much redundant time is spent by each developer having to track down the shapes of objects. It requires searching through documentation and praying they are up-to-date. Or it requires debugging the code and praying your guesses of which fields are required/optional are correct.

TypeScript is an up-front investment that saves you and your team much more time in the future.

"TypeScript shines on a team. Even if the team is you and you-from-6-months-ago" - @swizec

4. Safe Refactoring

I recently had two refactoring experiences that were a world apart.

In the first case, I was updating all our buttons to use our common Button component. It was a straightforward change, and completely terrifying. The codebase was JavaScript, there were too many buttons to manually check each one and our test coverage was spotty at best. It felt like I was walking on the edge of a cliff, knowing that if I missed or misspelt a prop, that could potentially stop a button from working - a critical bug.

In another refactor, I was changing the shape of the state. Originally we just needed a list of titles but now we needed a title and a description for each item. Fortunately, this time I was working on a TypeScript codebase so I updated the type from string[] to { description: string; title: string; }[] and then just let TypeScript tell me exactly what would need updating. It was only halfway through that I suddenly realised how hard this could potentially be in JavaScript. Instead, I hardly needed to think at all.

TypeScript not only gives you confidence that you haven't missed anything when you refactor but also shows you where you need to update. You no longer need to manually track your variables all over the code - just follow the red squiggles.

5. Incredible Autocomplete

This section assumes you're using VSCode as your IDE. Both TypeScript and VSCode are developed and maintained by Microsoft so are designed to integrate well with each other.

Other IDEs have TypeScript plugins which also give you Autocomplete. However, I have no experience with using them, so can't comment on how good they are.

The TypeScript autocomplete unexpectedly has become one of the biggest reasons why I love TypeScript. I imagine it's one of the reasons why it's so popular among developers.

Autocomplete means I don't have to worry about typos (did we name this prop color or colour?). I don't have to keep jumping between files to see which component props I need. I don't need to keep googling the names of string and array functions.

Let's say I have a string variable that could be undefined - string | undefined. I want to see if the string, contains a '#' character but I can't remember if I should be using .contains or .includes (happens every time!). I enter the variable name, press . and all the possible string functions are shown to me:

I find the function I want and press tab to select it:

Did you see that? Not only did it help us look up which function we wanted, but it also filled it in for us and used optional chaining to make sure we handle the cases where it's undefined. 🤯

All these mean you don't have to keep interrupting your flow. You can just tab and move on to the next thing. It's like having a co-pilot as you code.

TypeScript As A Default For New Projects

TypeScript isn't perfect. There are plenty of arguments against it (some better than others). But for me, TypeScript should be the default for any new project. Instead of asking if there is a good reason to include it, you should be asking if there is a good reason not to.

// Detect dark theme var iframe = document.getElementById('tweet-1453703985089630216-881'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1453703985089630216&theme=dark" }

Adding Dark Mode to an ElderJS Site

mattstobbs — Fri, 24 Sep 2021 07:50:36 +0000

This post was originally posted on my blog, Adding Dark Mode to an ElderJS Site. Some changes have been made from the original post to fit the styling of dev.to. I recommend reading the post on the original site to see it styled as intended.

One of the trickiest parts of creating this site was implementing the dark mode. I thought it would be simple:

Use CSS variables for all the colours. CSS variables are reactive, so they'll automatically update the colours on the page if their values change.
Define two sets of CSS variables, a default value for light mode and a dark mode value for when the body node has a class of dark.
Toggle the body node's dark class to switch between light and dark mode.

body {
  --colour-background: #ffffff;
  /* Define the other light-mode colours here */

  background: var(--colour-background);
}

body.dark {
  --colour-background: #111827;
  /* Define the other dark-mode colours here */
}

However, with this approach, we don't remember what the user's preference is. ElderJS doesn't use client-side routing, so when you navigate the site, each page will fall back to the default light mode. Refreshing the page or returning to the site later gives us the same problem.

It turns out solving this problem is more complicated than it seems. In this post, we'll look at how I implemented dark-mode for this blog so that the user's choice of theme is always the one they see.

A huge inspiration for this post is taken from Josh W. Comeau's excellent blog post The Quest for the Perfect Dark Mode.

While that post was written for sites built with Gatsby.js, the main strategy behind it was used for this post. It's worth reading if you're interested in learning more about why this approach was chosen.

If you just want to jump to where we start coding our final solution, you can find that here.

Proposed Initial Solution

When the user toggles between light and dark mode, we'll store their choice in localStorage.

When a user navigates to our page, we'll see if they have a previous value saved and use it as the initial value.

If localStorage doesn't define a value, we'll use their operating system preferences as our default. If no theme preferences are available, we'll use light mode as our default.

Our code will look something like this:

function getInitialColourMode() {
  const persistedColourPreference = window.localStorage.getItem('colour-mode');
  const hasPersistedPreference = typeof persistedColourPreference === 'string';

  if (hasPersistedPreference) {
    return persistedColourPreference;
  }

  const mql = window.matchMedia('(prefers-color-scheme: dark)');
  const hasMediaQueryPreference = typeof mql.matches === 'boolean';

  if (hasMediaQueryPreference) {
    return mql.matches ? 'dark' : 'light';
  }

  return 'light';
}

One Last Hurdle

Running this code in one of our components, such as the onMount of our layout component, exposes the last hurdle we need to overcome - the dreaded light-flash 😱

The problem is that we only have access to the window after the components have mounted. Therefore, the page renders using the default value of "light-mode" before our code runs and switches the page to dark mode.

We need a way of running our JavaScript before the page renders, which means we need to run it outside the Svelte components. We can do this by inserting a script tag before the <body> element of our HTML. Script tags are blocking, so placing it before the <body> element will mean the JavaScript inside will run before the page renders.

Implementing Dark-Mode

Ok, we're finally ready to start coding!

Setting the correct initial theme

Let's start with inserting the script tag before the <body> element to get our initial dark-mode value. One of the most powerful features of ElderJS is hooks, which allow us to plug into and customise any part of the page generation process.

We want to add the script to the head, so we'll use the stacks hook. It exposes a prop called headStack which we can mutate to add elements to the head:

// src/hooks.js

const hooks = [
  {
    hook: 'stacks',
    name: 'addDarkModeScript',
    description: 'Adds script to check for existing dark mode preferences',
    priority: 5,
    run: async ({ headStack }) => {
      const codeToRunOnClient = `
      <script>
        (function() {
          function getInitialColourMode() {
            // same as above - removed for brevity
          }

          const colourMode = getInitialColourMode();
          if (colourMode === 'dark') {
            document.documentElement.classList.add('dark');
          }
        })()
      </script>`;

      headStack.push({
        source: 'addDarkModeScript',
        string: codeToRunOnClient,
        priority: 80,
      });
    },
  },
];

We use getInitialColourMode to find our initial colour mode from the user's pre-defined preferences. If it's 'light', we don't need to do anything - that's our default. If it's 'dark', we'll add a 'dark' class to our HTML root element (this is running before the <body> element, so, for our purposes, the root element will be the only defined element).

Why do we define a new function and immediately call it?

This is called an IIFE (Immediately Invoked Function Expression). The main idea is that we won't be polluting the global namespace because everything is scoped within a function.

Showing the correct colours

Now that the root element has the right class, we can use CSS variables to show the correct colours. This is the same as the code in the introduction, but now our .dark class is on the HTML element.

body {
  --colour-background: #ffffff;
  /* Define the other light-mode colours here */

  background: var(--colour-background);
}

html.dark body {
  --colour-background: #111827;
  /* Define the other dark-mode colours here */
}

Now we're showing the correct initial value without any incorrect flashes after the page loads 🎉

Toggling the Theme

The last step is to allow the user to toggle the theme. We need a button/toggle which toggles the root element's class when clicked, and stores that new value to localStorage.

The only complication is that we won't know what the initial value should be when the component mounts. To solve this, we'll use Josh W. Comeau's solution: defer rendering the toggle until after we can read the initial value.

There are lots of ways to display a toggle. If you use a switch component, I recommend basing it off a library like Headless UI to ensure the component is fully accessible. For my blog, I use <Moon /> and <Sun /> components, which are just SVGs from Feather Icons.

<script>
  import { onMount } from 'svelte';
  import Moon from './icons/Moon.svelte';
  import Sun from './icons/Sun.svelte';

  const darkModeClass = 'dark';

  let isDarkMode;
  onMount(() => {
    isDarkMode = window.document.documentElement.classList.contains(darkModeClass);
  });

  const toggle = () => {
    window.document.documentElement.classList.toggle(darkModeClass);
    isDarkMode = window.document.documentElement.classList.contains(darkModeClass);
    window.localStorage.setItem('colour-mode', isDarkMode ? 'dark' : 'light');
  };
</script>

{#if typeof isDarkMode === 'boolean'}
  <button aria-label="Activate dark mode" title="Activate dark mode" on:click={toggle}>
    {#if isDarkMode}
      <Moon />
    {:else}
      <Sun />
    {/if}
  </button>
{/if}

Success 🎉

We've successfully created a dark-mode toggle for our ElderJS site, which shows the user's preferred theme when they first see the page in all its glory. First impressions matter, so it's vital to get the details right in the first few seconds of a user's experience.

If there is enough interest, this would be an excellent candidate for an ElderJS plugin. In the meantime, if you have any questions, feel free to reach out to me on Twitter.