DEV Community: Liam Hall

Exploring Typesafe design tokens in Tailwind 4

Liam Hall — Fri, 29 Nov 2024 11:55:00 +0000

Tailwind 4 has been on the horizon for a while, with the team first open-sourcing their progress in March 2024. One of the most noteworthy changes, in my opinion, is the shift from a JavaScript-based configuration to a CSS-based one. Tailwind 4 is currently in beta, and from what I gather, the team is still dealing with some challenges, especially with Safari compatibility.

NOTE: Later in the article, we'll assume you're using a component-based framework / library, but the concepts discussed are easily transferable to other approaches.

Changes in Tailwind 4

The move to a CSS config

I've heard some complaints about this, especially from TypeScript users. However, the roadmap for Tailwind 4.0 does include support for the classic tailwind.config.js as its top priority:

Support for JavaScript configuration files — reintroducing compatibility with the classic tailwind.config.js file to make migrating to v4 easy.

That said, it seems like this is intended primarily for migration purposes and may not be a sustainable long-term solution.

What does this mean for Typesafety

Under the hood Tailwind 4 uses the new @property CSS rules to to define internal custom properties.

We use @property to define our internal custom properties with proper types and constraints

As it stands I'm unable to find decent syntax highlighting support for @property rules in VS code, I have reached out on Bluesky to see if anyone has had more luck than me.

I'm hoping better @property support can aide us in future, more on that later.

What is the @property CSS rule

The @property rule represents a custom property registration directly in a stylesheet without having to run any JavaScript. Valid @property rules result in a registered custom property, which is similar to calling registerProperty() with equivalent parameters.

What are design tokens

Now that we've covered the upcoming changes in Tailwind 4 and their potential impact, let's take a moment to talk about design tokens. If you're not familiar with the term, here's a quick explanation: Design tokens are a method of storing and managing design decisions in a consistent, reusable format, typically as variables. They represent key visual properties of a design system, like colours, typography, spacing, shadows, in a structured way. The goal is to centralise these design values so they can be easily updated, maintained, and shared across different platforms and tools.

Design systems are typically made up of two main types of values: System values and Component values. For example, your system values might look something like this:

const SYSTEM_TOKENS: ISystemTokens = {
  /* ... */
  COLORS: {
    /* ... */
    GREEN: {
      LIGHT: "#E0E5D9",
      MEDIUM: "#3F6212",
      DARK: "#28331A",
    }
    /* ... */
  },
  TYPOGRAPHY: {
    /* ... */
  }
  /* ... */
}

You can then reference your system values within your component tokens like this:

import { SYSTEM_TOKENS } from "...";

const BUTTON_VALUES: IButtonTokens = {
  /* ... */
  COLORS: {
    /* ... */
    BACKGROUND: SYSTEM_TOKENS.COLORS.GREEN.DARK,
    /* ... */
  },
  TYPOGRAPHY: {
    /* ... */
  }
  /* ... */
}

If you're interested in learning more about design systems, it's worth exploring well-known systems likeMaterial Design.

Structuring component design tokens with Tailwind

About a week ago, I wrote an article discussing an alternative approach I’ve been using for creating component variants with Tailwind CSS. In brief, the article explores how we can leverage CSS variables alongside Tailwind to manage complex variants, setting variant values inline through dynamic component props and variable mapping. If you're curious about how I arrived at this approach, you can read more about it here: A different approach to writing component variants with Tailwind CSS.

We should start by identifying the parts of our component that depend on design tokens. As mentioned earlier, this will include colors, typography, spacing, and any other fixed system values that are integral to your design. Let's take a look at the following Button component, without design tokens:

<button class="p-4 bg-red text-white rounded-lg relative flex justify-center">Click me</button>

In the example above, we can pinpoint several values that can be tokenized. Each of the following classes could correspond to a value in our design system:

p-4
bg-red
text-white

Now that we've identified the values that can be tokenised, we can categorise them into two groups: static values and dynamic values. Static values are those in your component that remain constant, while dynamic values are those that can change based on the props passed to the component. For our example we'll make the padding (p-4) static, while the text colour (text-white) and background (bg-red) should be set dynamically via a theme prop.

Creating the tokens

Tailwind 4 config

First we need to define our System tokens in the new Tailwind CSS config:

@import "tailwindcss";

@theme {
  --color-white: #FFFFFF;
  --color-green-light: #E0E5D9;
  --color-green-medium: #3F6212;
  --color-green-dark: #28331A;
  --color-red-light: #F4CCCC;
  --color-red-medium: #D50000;
  --color-red-dark: #640000;

  --spacing-sm: 1rem;
  --spacing-md: 2rem;
}

System tokens

Next we need to create our system.tokens.ts file:

export type TColor = "--color-white" | "--color-green-light" | "--color-green-medium" | "--color-green-dark" | "--color-red-light" | "--color-red-medium" | "--color-red-dark";

export type TSpacing = "--spacing-sm" | "--spacing-md";


interface ISystemTokens {
  COLORS: {
    WHITE: TColor;
    GREEN: {
      LIGHT: TColor;
      MEDIUM: TColor;
      DARK: TColor;
    },
    RED: {
      LIGHT: TColor;
      MEDIUM: TColor;
      DARK: TColor;
    }
  },
  SPACING: {
    SMALL: TSpacing;
    MEDIUM: TSpacing;
  }
}

export const  SYSTEM_TOKENS: ISystemTokens {
  COLORS: {
    WHITE: "--color-white";
    GREEN: {
      LIGHT: "--color-green-light";
      MEDIUM: "--color-green-light";
      DARK: "--color-green-light";
    },
    RED: {
      LIGHT: "--color-red-light";
      MEDIUM: "--color-red-medium";
      DARK: "--color-red-dark";
    }
  },
  SPACING: {
    SMALL: "--spacing-sm";
    MEDIUM: "--spacing-md";
  }
}

System design tokens can be referenced in designs like so:
$system.COLORS.GREEN.LIGHT.

In an ideal world, we could directly export types from our CSS file’s @property rules into our TColor and TSpacing types, much like how SCSS imports can be transformed into JavaScript. Unfortunately, as of now, to the best of my knowledge, this isn't possible.

Component tokens

Now that we’ve implemented our system tokens, we can start integrating them into our components. The first step is to set up our <Component>.tokens.ts file. To illustrate this, let’s take the example of the Button component we looked at earlier, and create a corresponding Button.tokens.ts file.

To recap, here’s how our Button component was structured:

<button class="p-4 bg-red text-white rounded-lg relative flex justify-center">Click me</button>

Earlier, we discussed the distinction between static values (like p-4) and dynamic values (like bg-red and text-white). This distinction will guide how we organise our design tokens. Static properties, like p-4, should be grouped under STATIC, while dynamic properties, like bg-red and text-white, should be grouped under the appropriate prop identifier. In this case, since we’re controlling bg-red and text-white through a theme prop, they should be placed under the THEME section in our tokens file. For our example we'll assume 2 theme variables - PRIMARY and SECONDARY.

import { SYSTEM_TOKENS, TColor, TSpacing } from "./system.tokens.ts";
import { TTheme } from "./Button"; // PRIMARY, SECONDARY

interface IButtonStaticTokens {
  padding: TSpacing;
}

interface IButtonThemeTokens {
  backgroundColor: TColor;
  textColor: TColor;
}

export const STATIC: IButtonStaticTokens {
  padding: "--spacing-sm";
}

export const THEME: IButtonStaticTokens {
  PRIMARY: {
    backgroundColor: "--color-red-dark";
    textColor: "--color-red-light";
  },
  SECONDARY: {
    backgroundColor: "--color-green-dark";
    textColor: "--color-green-light";
  };
}

Component design tokens can be referenced in designs like so: $component.Button.THEME.PRIMARY.backgroundColor. My preference for naming conventions is to use:
$component.<ComponentName>.<PROP_NAME><PROP_VALUE>.tokenName

$component: Differentiate between $system and $component tokens
<ComponentName>: Follow internal file naming convention for components
PROP_NAME: Constant case
PROP_VALUE: Should follow internal prop value casing
Token name (backgroundColor): Camel case*

This is ultimately a matter of personal preference, and it's up to you to decide what works best for your workflow.

When naming tokens, I slightly deviate from Camel case if I need to specify a token for an element's state, such as :hover. In those cases, I prefix the token name with the state followed by two underscores, like so: hover__backgroundColor.

Using design tokens in components

As I mentioned earlier in the article, I previously wrote about exploringa different approach to writing component variants with Tailwind CSS. I'll be referencing that approach here, so if you haven't read it yet, it might be helpful to check it out first to understand the context behind this method.

This part of the article will assume you are using a Javascript framework or library to build your components.

Updating the Button component

We need to replace the existing tokenisable classes with Tailwind classes powered by css variables. Note the variable names match those in our 2 Button component token interfaces, IButtonStaticTokens and IButtonThemeTokens;

<button class="p-[--padding] bg-[--backgroundColor] text-[--textColor] rounded-lg relative flex justify-center">Click me</button>

Now that we've updated our classes, we need to dynamically apply the component styles and update the variables. To achieve this, we'll use a variableMap function on the component. Essentially, this function maps our tokens from Button.tokens.ts to inline CSS variables directly on the component, which our classes can then reference. For an example of a variable map please see the end of this article.

<template>
  <button
    :style="[variableMap(STATIC), variableMap(THEME[props.THEME])]"
    class="p-[--padding] bg-[--backgroundColor] text-[--textColor] 
    rounded-lg relative flex justify-center"
  >
    Click me
  </button>
</template>
<script setup lang="ts">
import { variableMap } from "...";
import { STATIC, THEME } from "Button.tokens.ts";

const props = /*THEME*/
</script>

Conclusion

I'm looking forward to the release of Tailwind 4 and what changes the team make between now and then. I've enjoyed experimenting with ideas to deal with some of the challenges around design tokens, variants and typesafety.

This is an experimental approach on which I'm sure there will be some strong opinions.

If you've found this article interesting or useful, please follow me on Bluesky (I'm most active here), Medium, Dev and/ or Twitter.

Bluesky - Dev community

Liam Hall — Sun, 17 Nov 2024 21:12:42 +0000

Bluesky finally seems to be getting some traction in the Dev community, I'd love to follow some developers from Dev.to, drop me a follow and I'll follow you back.

Follow Me on Bluesky.

Feel free to post a link to your profile in the comments.

A different approach to writing component variants with Tailwind CSS

Liam Hall — Sun, 17 Nov 2024 21:09:14 +0000

The problem

Traditionally when writing component variants with Tailwind CSS I've reached for simple class maps that map a prop value to component slots:

type TTheme = "DEFAULT" | "SECONDARY";
interface IComponentSlot {
  root: string;
  accent: string;
}

const THEME_MAP: Record<TTheme, IComponentSlot> = {
  DEFAULT: {
    root: "bg-red hover:background-pink",
    accent: "text-blue hover:text-green",
  },
  SECONDARY: {
    root: "bg-green hover:background-black",
    accent: "text-pink hover:text-white",
  }
}

<div :class="THEME_MAP['DEFAULT'].root">
  <div :class="THEME_MAP['DEFAULT'].accent">/**/</div>
</div>

The problem with this approach is keeping the required classes in line with one another, ensuring each variant has all the required classes, particularly in more complicated components. In components where we want to share a style, say text color, across different component slots it requires us to update each slot individually.

The limitations of Tailwind

Tailwind generates utility classes by scanning your codebase and matching strings, this means while Tailwind can create classes from arbitrary values, we can't initiate them dynamically without creating a safe list. So this will not work:

// .ts
type TTheme = "DEFAULT" | "SECONDARY";

const colors: Record<TTheme, string> = {
  DEFAULT: "red",
  SECONDARY: "blue",
}

// .html
<div :class="`text-[${colors[DEFAULT]}]`">

However, we can imitate the desired behavior by taking advantage of CSS variables, something Tailwind uses under the hood for lots of its classes. We can set a variable via a class in Tailwind using the following syntax: [--my-variable-key:--my-variable-value]
So how could we update the above code example to use dynamic values?

// .ts
type TTheme = "DEFAULT" | "SECONDARY";

const colors: Record<TTheme, string> = {
  DEFAULT: "[--text-color:red]",
  SECONDARY: "[--text-color:blue]",
}

// .html
<div
  :class="[
    colors[DEFAULT],
    'text-[--text-color]'
  ]">

Tackling the initial problem

Now we understand the limitations of Tailwind, we need to look into ways to solve our initial problem caused by our class maps approach. We can start by simplifying our class maps:

type TTheme = "DEFAULT" | "SECONDARY";
interface IComponentSlot {
  root: string;
  accent: string;
}

const THEME_MAP: Record<TTheme, string> = {
  DEFAULT: "[--backgound:red] [--hover__background:pink] [--text:blue] [--hover__text:green]",
  SECONDARY: "[--backgound:green] [--hover__background:black] [--text:pink] [--hover__text:white]",
}

<div class="bg-[--background] hover:bg-[--hover__background]">
  <div class="text-[--text] hover:text-[--hover__text">/**/</div>
</div>

Unfortunately, this alone doesn't solve our problem, we still can't ensure we've set all of the classes we need to display each variant correctly. So how can we take this a step further? Well, we could begin writing an interface to force us to set specified values:

interface IComponentThemeVariables {
  backgound: string;
  hover__backgound: string;
  text: string;
  hover__text: string;
}

const THEME_MAP: Record<TTheme, IComponentThemeVariables> = {
  DEFAULT: {
    backgound: "[--backgound:red]",
    text: "[--hover__background:pink]",
    hover__background: "[--text:blue]",
    hover__text:"[--hover__text:green]",
  },
  SECONDARY: {
    backgound: "[--backgound:green]",
    text: "[--hover__background:black]",
    hover__background: "[--text:pink]",
    hover__text:"[--hover__text:white]",
  },
}

So this would work, but, there's still a problem, nothing is stopping us from mixing up our string values. For example, we could accidentally set key background to [--text:blue].

So maybe we should type our values as well. We can't type entire classes, that would be a maintenance nightmare, so what if we typed our colors and wrote a helper method to generate our CSS variables:

type TColor = "red" | "pink" | "blue" | "green" | "black" | "white";

interface IComponentThemeVariables {
  backgound: TColor;
  hover__backgound: TColor;
  text: TColor;
  hover__text: TColor;
}

// Example variableMap method at the end of the article

const THEME_MAP: Record<TTheme, string> = {
  DEFAULT: variableMap({
    backgound: "red",
    text: "pink",
    hover__background: "blue",
    hover__text:"green",
  }),
  SECONDARY: variableMap({
    backgound: "green",
    text: "black",
    hover__background: "pink",
    hover__text:"white",
  }),
}

Okay so this is great, we can ensure we are always setting the correct variables for every variant of our component. But wait, we've just run into the initial issue we found with Tailwind, we can't just generate classes, Tailwind won't pick them up. So how are we going to tackle this?

What about CSS in JS?

CSS in JS seemed like the obvious answer here, just generate a class that creates a custom class with correct variables. But there's a snag, the Javascript runs on the client, and this causes a "Flash", where the component initially loads without the variables set before updating to display correctly.

How do CSS in JS libraries deal with this?

Libraries like Emotion deal with this by inserting inline style tags about the components:

<body>
  <div>
    <style data-emotion-css="21cs4">.css-21cs4 { font-size: 12 }</style>
    <div class="css-21cs4">Text</div>
  </div>
</body>

This didn't feel like the right approach to me.

So how do we solve this?

I was working with Vue, this led me down the path of v-bind in CSS, a feature in Vue to bind Javascript as CSS values. I'd only used this feature sparingly in the past and never taken a deep dive into what it's doing. v-bind in CSS simply sets an inline style on the relevant element.

This jogged my memory about a Tweet I saw from the creator of Tailwind CSS, Adam Wathan a couple of months previously:

So how does this help us? Well, while we can't dynamically generate Tailwind classes, we can dynamically generate inline styles and consume those inline styles from our Tailwind classes. So what would that look like?

type TColor = "red" | "pink" | "blue" | "green" | "black" | "white";

interface IComponentThemeVariables {
  backgound: TColor;
  hover__backgound: TColor;
  text: TColor;
  hover__text: TColor;
}

// Example variableMap method at the end of the article

const THEME_MAP: Record<TTheme, string> = {
  DEFAULT: variableMap({
    backgound: "red",
    text: "pink",
    hover__background: "blue",
    hover__text: "green",
  }),
  SECONDARY: variableMap({
    backgound: "green",
    text: "black",
    hover__background: "pink",
    hover__text: "white",
  }),
}

<div
  class="bg-[--background] hover:bg-[--hover__background]"
  :style="THEME_MAP['DEFAULT']"
>
  <div class="text-[--text] hover:text-[--hover__text">/**/</div>
</div>

/*
OUTPUT:
<div
  class="bg-[--background] hover:bg-[--hover__background]"
  style="--background: red; --text: pink; --hover__background: blue; --hover__text: green;"
>
  <div class="text-[--text] hover:text-[--hover__text">...</div>
</div>
*/

Conclusion

By combining the powers of Typescript, CSS variables, and inline styles we were able to ensure that while using Tailwind CSS, each variant of our component would have every option set and with the correct type.

This is an experimental approach on which I'm sure there will be some strong opinions. Am I convinced this is the best approach? At this stage, I'm not sure, but I think it has legs.

If you've found this article interesting or useful, please follow me on Bluesky (I'm most active here), Medium, Dev and/ or Twitter.

Example: variableMap

// variableMap example
export const variableMap = <T extends Record<string, string>>(
  map: T
): string => {
  const styles: string[] = [];
  Object.entries(map).forEach(([key, value]) => {
    const wrappedValue = value.startsWith("--") ? `var(${value})` : value;
    const variableClass = `--${key}: ${wrappedValue};`;
    styles.push(variableClass);
  });
  return styles.join(" ");
};

What are higher order components and how to use them in Vue

Liam Hall — Mon, 30 Jan 2023 19:17:00 +0000

What is a higher order component

Higher order components in Vue offer a convenient solution for code reusability by acting as a wrapper for specific component configurations. By using higher order components, we can eliminate the need for repetitive code and make updates in one central location, rather than multiple places. This makes it much simpler to maintain and update our codebase.

When might we call for higher level component

The most prevalent justification for using higher order components is to eliminate repetitive configurations throughout the application. If you find yourself constantly using the same component configurations, it may be an indication to extract that configuration into a higher order component, streamlining your codebase and making it easier to maintain.

Higher level components by example

Common configurations

Simple card example

To gain a deeper understanding of higher order components, let's examine a practical example. The card component is a staple in UI design and is often utilised to showcase preview information for articles and products, among other things. These cards tend to have many common structural elements. Imagine we have been provided the following designs for an article card (left) and a product card (right) from our design team:

These 2 components are very structurally similar, the only variations, are that the Article Card has a Border and Link, vs the Product card with no Boarder and a Button. Traditionally we'd probably create 2 components with similar structures

These two components share a great deal of structural similarity, with the main distinctions being that the Article Card has a Border and Link, vs the Product card with no Boarder and a Button. In the past, we may have created a Card component and passed it the relevant configurations wherever necessary:

Card

<template>
  <div class="card">
    <div class="card__image-wrapper">
      <img src="/some-image.jpg" :alt="title" />
    </div>
    <div :class="['card__details', borderMap[border]]">
      <h2 class="card__title">
        {{ title }}
      </h2>
      <p class="card__description">
        {{ description }}
      </p>
    </div>
    <div class="card__actions">
      <slot name="actions"></slot>
    </div>
  </div>
</template>

This approach poses a significant issue as it requires passing the same configuration for product and article cards throughout the application. When a change needs to be made, it must be updated in multiple locations, leading to a significant maintenance burden. This makes it difficult to keep the different instances of the cards in sync, and increases the likelihood of inconsistencies.

One alternative approach could be to create two separate components with largely identical structures:

Article Card

<template>
  <div class="card">
    <div class="card__image-wrapper">
      <img src="/some-image.jpg" :alt="title" />
    </div>
    <div class="card__details card__details--border-grey">
      <h2 class="card__title">
        {{ title }}
      </h2>
      <p class="card__description">
        {{ description }}
      </p>
    </div>
    <div class="card__actions">
      <a :href="link">Read more</a>
    </div>
  </div>
</template>

Product Card

<template>
  <div class="card">
    <div class="card__image-wrapper">
      <img src="/some-image.jpg" :alt="title" />
    </div>
    <div class="card__details">
      <h2 class="card__title">
        {{ title }}
      </h2>
      <p class="card__description">
        {{ description }}
      </p>
    </div>
    <div class="card__actions">
      <BuyNowButton :id="id" />
    </div>
  </div>
</template>

While this approach may be functional, it poses a significant maintenance challenge as any future structural modifications must be made in multiple locations. This becomes increasingly cumbersome as more card-style components are added to the application. For example, if our hypothetical team decides to include recipe previews using a recipe card, we would need to make structural changes in three separate locations. This difficulty is further compounded when utilising utility-based classes, as it becomes challenging to ensure consistency across all instances.

We can address many of these challenges by combining both approaches, with the Product Card and Article Card components serving as higher-order components. This approach allows the initial Card component to remain unchanged, while still providing the flexibility to make updates and modifications in a more centralised and efficient manner. This helps to reduce the maintenance overhead and ensures consistency across all instances of the card components throughout the application:

Article Card

<template>
  <Card :image="image" :title="title" :description="description" border="grey">
    <template #actions>
      <a :href="link">Read more</a>
    </template>
  </Card>
</template>

Product Card

<template>
  <Card :image="image" :title="title" :description="description" border="none">
    <template #actions>
      <BuyNowButton :id="id" />
    </template>
  </Card>
</template>

By adopting higher-order components, we have created a centralised hub for managing our card components and significantly reduced the amount of repetitive configuration throughout the application. This results in a more maintainable and organised codebase, streamlining updates and modifications to a single location. This approach not only simplifies management but it also ensures consistency across all instances of the card components throughout the application.

Conclusion

So next time you find yourself repeating component configurations throughout your application, considering using the higher order component approach.
If you’ve found this article useful, please follow me on Medium, Dev and/ or Twitter.

Understanding and Utilising TypeScript, by example

Liam Hall — Mon, 16 Jan 2023 13:36:57 +0000

TypeScript is a powerful, open-source programming language that is a strict superset of JavaScript. Developed and maintained by Microsoft, TypeScript adds optional static typing and other features to JavaScript, making it a popular choice for large-scale, complex projects. However, some developers have criticised TypeScript for its learning curve and added complexity, while others have praised it for improving code quality and catching errors early on.

In this article, we will delve into examples of how to effectively use TypeScript in common scenarios so we can apply these concepts to our future projects. Primarily we'll be focusing on primitives, types, interfaces and enumns.

Primitives, Types, Interfaces and Enums, what are they?

Primitives

In TypeScript, primitive types are the basic data types that form the building blocks of the language. They include:

number: for numeric values (e.g., 1, 3.14, -100)
string: for text values (e.g., "hello", "world")
boolean: for true/false values
null and undefined: for empty or non-existent values
symbol: a new data type introduced in ECMAScript 6, used for creating unique identifiers

These primitive types have corresponding JavaScript literals and can be used to declare variables and constants. For example:

let myName: string = "John";
let myAge: number = 30;
let isStudent: boolean = false;

Also, typeof operator in TypeScript returns the type of a variable, which can be one of these primitive types.

console.log(typeof "hello");  // Output: string
console.log(typeof 100);     // Output: number
console.log(typeof true);    // Output: boolean

In addition, TypeScript provides some special types, like any and unknown.

any: any can be assigned to any variable and it will accept any value and any type,
unknown: unknown is like any, but more restrictive and can be used when you want to be more strict with type checking

Types and Interfaces?

Types

Types in TypeScript are used to specify the expected data type of a variable or function parameter. They can be either primitive types, such as number, string, and boolean, or complex types, such as arrays, objects, and user-defined types. Types can be defined using the type keyword.

Type basics by example

type Brand = "audi" | "ford"; // Value must be "audi" or "ford"

type Car = {
  owner: string;
  milage: number;
  brand: Brand;
}

Interfaces

Interfaces provide a way to describe the structure of an object. They define a contract for the shape of an object, specifying the properties and methods it should have. Interfaces can be defined using the interface keyword.

Interface basics by example

interface ICar = {
  owner: string;
  milage: number;
  brand: Brand;
}

According to the official Typescript documentation:

Almost all features of an interface are available in type, the key distinction is that a type cannot be re-opened to add new properties vs an interface which is always extendable.

You can read more about the differences between types and interfaces in the official typescript documentation

Enums

In TypeScript, an enum is a way to define a set of named values that represent a specific set of constants.

You can define an enum using the enum keyword, followed by a name for the enum and a set of members enclosed in curly braces. Each member has a name and an associated value, which can be either a numeric literal or another enum member. The first member is assigned the value 0 by default, and each subsequent member is assigned the value of the previous member plus 1, unless explicitly specified.

enum EFuel {
  petrol,
  diesel,
}

You can also explicitly set the values of enum members:

enum EColor {
  "red" = "#ff0000",
  "blue" = "#0000ff",
}

Naming conventions

Common conventions

Typescript types, interfaces and enums should be defined using Pascal case. Pascal case, also known as upper camel case, is a naming convention where the first letter of each word in the name is capitalised, and there are no underscores between the words.

Personal conventions

Singluar / Plural

As a personal preference, I prefer for all types, interfaces, and enums to be named in the singular form.

const car: ICar = {/* values */} // Single car
const cars: ICar[] = {/* values */} // Multiple cars

Prefixes

For clarity and ease of identification, it can be beneficial to clearly distinguish between types, interfaces, and enumerations, particularly when importing them. To aid in this differentiation, I have adopted the convention of prefixing interfaces with an "I" and enum's with an "E", while leaving types without a prefix. This allows for quick and easy identification when navigating the codebase.

Different developers have their own conventions and have presented compelling arguments for and against various approaches. Ultimately, it is important to find the approach that works best for you and your team, and to be consistent in its application. This will help to ensure that your code is clear, readable, and maintainable.

interface ICar = {
  owner: string;
  milage: number;
  brand: Brand;
}

enum EColor {
  "red" = "#ff0000",
  "blue" = "#0000ff",
}

Typescript by example

Now that we have a basic understanding, let's dive deeper into Typescript by examining its use in common scenarios, using a fictional car sales application as a practical example.

In our application each car should have 6 properties:

owner
milage
fuel
color
brand
radioCode

We could loosely type our car object with primitives:

export interface ICar {
  owner: string;
  milage: number;
  fuel: string;
  color: string;
  brand: string;
  radioCode: string;
}

While this interface is technically valid, we can enhance its type safety by adding specific types to certain properties, such as fuel and brand. Let's take a closer look at how we can accomplish this. Given that fuel types and brands are limited to a specific set of options, we can improve the type safety by using enums for these properties:

enum EFuel {
  petrol,
  diesel,
}

enum EBrand {
  audi,
  ford,
}

Handling colors can be a bit more complex, as they typically have both a human-readable name and a HEX code. In this case, we can create an enum with key-value pairs to handle this. This allows us to ensure that we are only working with valid color options and also gives us the flexibility to easily reference and display the color name and code.

enum EColor {
  "red" = "#ff0000",
  "blue" = "#0000ff",
}

We can now reference the value of EFuel, EBrand and EColor much like we would an object property:

const fuel = EFuel.petrol; // Or EFuel["petrol"]
const brand = EBrand.audi; // Or EBrand["audi"]
const color = EColor.red; // Or EFuel["red"]

We can also create types from these enums using the keyof and typeof keywords. These types can be used to better define our ICar interface, replacing primitives, ensuring that only valid options are assigned to the relevant properties.:

type Fuel = keyof typeof EFuel; // "petrol" | "diesel"
type Brand = keyof typeof EBrand; // "audi" | "ford"
type Color = keyof typeof EColor; // "red" | "blue"

export interface ICar {
  owner: string;
  milage: number;
  fuel: Fuel;
  color: Color;
  brand: Brand;
  radioCode: string;
}

Similar to enums, we can also create types from look-up tables, let's imagine in our fictional application we have a radio codes look up table:

const radioCodes = {
    sony: "1111",
    pioneer: "2222"
};

Just like enums we can create a type from our radioCodes look-up table using the keyof and typeof keywords:

type RadioCode = keyof typeof radioCodes; // "sony" | "pioneer"

Type RadioCode can be used to better define property radioCodein our ICar interface, replacing string, ensuring that only valid options are assigned:

export interface ICar {
  owner: string;
  milage: number;
  fuel: Fuel;
  color: Color;
  brand: Brand;
  radioCode: RadioCode;
}

It's worth noting that in reality, not all cars are equipped with radios, which would leave the radioCode property undefined for those cars, this would break our application.
To ensure that our application is not broken by the presence of undefined values for radioCode we can make it optional by chaining ? to the end of the key name:

export interface ICar {
  owner: string;
  milage: number;
  fuel: Fuel;
  color: Color;
  brand: Brand;
  radioCode?: RadioCode;
}

Currently, the ICar interface in our application requires a string value for the owner property. However, let's consider the possibility that our application has a predefined array of owners:

const people = ["Liam Hall", "Steve Jobs", "Ozzy Osborne", "Robert De Niro"];

Firstly we can type this array, we know that all the values in the array should be strings, so suffixing the string primitive with [] to to mark it as an array of type, we can ensure the const is strictly typed to an array of strings:

const people: string[] = ["Liam Hall", "Steve Jobs", "Ozzy Osborne", "Robert De Niro"];

With the array of people in place, we can now establish a more specific data type for the owner property on our ICar interface, making it more robust, ensuring only one of our predefined people can be set as a cars owner. To do this we use the typeof keyword:

type Person = typeof people[number];

Which we can now add to our ICar interface:

export interface ICar {
  owner: Person;
  milage: number;
  fuel: Fuel;
  color: Color;
  brand: Brand;
  radioCode?: RadioCode;
}

In reality, the owner property would typically provide additional information. Additionally, it's not uncommon for the owner of a car to be represented as a business entity, such as a garage, rather than an individual. A basic implementation of this concept using interfaces may appear as follows:

export interface IPerson {
  firstName: string;
  lastName: string;
}

export interface IGarage {
  name: string;
  companyNumber: number
}

Utilising these interfaces let's create some two new arrays, people and garages, replacing the previous array of strings:

const people: IPerson[] = [
  {firstName: "Liam", lastName: "Hall"},
  {firstName: "Steve", lastName: "Jobs"},
  {firstName: "Ozzy", lastName: "Osborne"},
  {firstName: "Robert", lastName: "De Niro"}
]

const garages: IGarage[] = [
  {name: "London Garage", companyNumber: 1111},
  {name: "New York Garage", companyNumber: 2222},
  {name: "Tokyo Garage", companyNumber: 3333},
  {name: "Lagos Garage", companyNumber: 4444}
  {name: "Berlin Garage", companyNumber: 5555}
]

Now using the or operator |, we can update our ICar owner property to accept types IPerson and IGarage:

export interface ICar {
  owner: IPerson | IGarage;
  milage: number;
  fuel: Fuel;
  color: Color;
  brand: Brand;
  radioCode?: RadioCode;
}

We can also use the or operator to create mixed type arrays:

const owners: (IPerson | IGarage)[] = [...people, ...garages];

In cases where a combination of different data types will be frequently utilised throughout the application, it can be beneficial to establish a parent type for them. This will provide a more organised and consistent approach for working with the mixed data:

type Owner = IPerson | IGarage;

Which will allow us to update ICar:

export interface ICar {
  owner: Owner;
  milage: number;
  fuel: Fuel;
  color: Color;
  brand: Brand;
  radioCode?: RadioCode;
}

In certain scenarios, it may be necessary to have an array with a fixed structure of data types, for example, where index 0 should be of the type IGarage interface, and index 1 should be of the type IPerson interface. In such situations, we can utilise Tuples to define the specific structure of the array:

const lastSale: [IGarage, IPerson] = [
  {name: "London Garage", companyNumber: 1111},
  {firstName: "Liam", lastName: "Hall"}
];

In the real world, cars can change hands between individuals and businesses, and in some cases, may never have been sold at all. To accommodate this complexity, we can use the Owner type that we previously created, and make use of the or operator along with the primitive undefined:

const lastSale: [(Owner | undefined), Owner] = [
  {name: "London Garage", companyNumber: 1111},
  {firstName: "Liam", lastName: "Hall"}
];

With a robust, strongly typed car interface in place for our fictional application, let's explore additional types that could enhance the functionality of our application.

Imagine that the application's designer has chosen to incorporate brand-specific accent colors. To accomplish this, we must establish a correspondence between brand names and colors. For this we can create a simple look-up table:

const brandAccents = {
  audi: "#000000",
  ford: "#333333"
}

This approach will function as intended, however, it currently lacks any form of type safety. To guarantee that keys are exclusively of the "Brand" type and colors are consistently represented as strings, what measures can we implement? To do this we can make use of the key in keywords:

type BrandAccentMap = {
  [key in Brand]: string;
}

We can now type brandAccents with BrandAccentMap:

const brandAccents: BrandAccentMap = {
  audi: "#000000",
  ford: "333333"
}

To ensure that all keys are of type Brand while allowing for flexibility that some brands may not have accent colors, we can make the brand key-value pair optional by appending ? to the dynamic key, much like we did for radioCode in ICar:

type BrandAccentMap = {
  [key in Brand]?: string;
}

Of course, in the reality, world, most applications need to fetch data from a datasource. Let's consider a hypothetical scenario where our application requires retrieving a specific vehicle from a database, utilising a unique identifier such as an id:

const getCar = (id) => {/* fetch data */}

// OR
// function getCar(id) {/* fetch data */}

Although this function is functional, there are ample opportunities to enhance type safety. It would be beneficial to clearly define the types for both the argment, id, and the output of the function. In the context of our hypothetical application, the id argument should be specified as a string, and the function should return an object of type ICar:

const getCar = (id: string): ICar => {/* fetch data */}

// OR
// function getCar(id: string): ICar {/* fetch data */}

As demonstrated in the example, we can clearly define the types of function arguments by using a argument: type pair, separated by a colon. In the event that we have multiple arguments, we can separate the argument: type pairs with commas.

In actuality, the process of obtaining data in an application is frequently asynchronous. To accurately reflect this in our typing, we can utilize the Promise type in conjunction with the ICar type, and prefix the function with the async keyword. This approach ensures that our function's return type accurately reflects the asynchronous nature of data retrieval:

const getCar = async (id: string): Promise<ICar> => {/* fetch data */}

// OR
// async function getCar(id: string): Promise<ICar> {/* fetch data */}

At times, when retrieving data, particularly from content management systems, we may not have complete control over the returned information. In these cases, the data we desire may be wrapped with additional, yet useful, information provided by the CMS, such as a block UUID. The returned data may look something like this:

{
  _uuid: "123",
  data: { /* primary data */ }
}

In situations such as this, we can utilise generics to wrap our existing types, and specify which property should be typed as the wrapped type. For instance, using the aforementioned example of a _uuid and data key-value pairs, we could create an ICMSResponse interface. This approach allows us to maintain the useful information provided by the CMS while clearly defining the expected data structure of our application:

interface ICMSResponse<T> {
  _uuid: string,
  data: T,
}

The T in ICMSResponse<T> represents a passed type, indicating that the data property will be typed according to the type passed to ICMSResponse. This allows for flexibility and dynamic typing, while maintaining a clear and consistent structure.

If we were expecting an ICMSResponse from our earlier getCar function, we could update the function's types to represent that:

export const getCar = async (id: string): Promise<ICMSResponse<ICar>> => { /* cms data */ }

Conclusion

I hope that this article has assisted you in gaining a deeper understanding of how to effectively utilise TypeScript in various common scenarios. By providing examples and practical explanations, I aim to empower you to confidently incorporate TypeScript in your projects for improved code reliability and readability.

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.

Getting started with Barebones components - A component library without design constraints built for Vue and Nuxt

Liam Hall — Fri, 01 Jul 2022 10:17:32 +0000

1. Backstory

In early May of this year, I lost my job as a Lead Developer at a subscription start-up, along with all my colleagues. When I joined the company they had recently had an investment of £4m (Around $4.8m) and since then we had been beating all of our targets. We’d been beating them to the point that company had managed to agree on a deal for a further £10m investment this year. Unfortunately for those of us that worked there, the current economic climate and threat of another recession in the UK by the end of 2022 led our biggest investors to pull out last minute, this led to other investors following and the deal falling apart. The company went into Administration the next day and we all lost our jobs.

2. The idea behind Barebones

After losing my job so suddenly I decided to take a little bit of time to work on some personal projects, trying to solve some of the issues that I’d come across while working at my last company. This is where the idea for Barebones was born. I wanted to create a component library that allowed developers to build applications fast without design constraints. Have access to all the types of components they’re using in almost every project, with complete design freedom.

3. How does Barebones work?

Put simply, Barebones uses local configuration to map styles to component parts. But, what does that mean exactly? Well, when installing Barebones in a project you must add the local configuration files. The local configuration for each component is made up of 2 files a .parts.ts file and a .props.ts file, which work in unison map styles to component parts, component parts are the elements which make up a component.

3.1. props.ts files

.props.ts files allow developers to set up props, which values can be mapped to styles for each component part. This allows developers and teams to set up their own preferred variables for styling components.

3.2. parts.ts files

.parts.ts files allow developers to define style mapping keys and values for any component part based on a prop defined in .parts.ts in the components .props.ts file.

3.3. Component parts

Each component element is a defined component part and can be referenced in the .parts.ts file and assigned relevant component props and values to map styles.

3.4. By example

Every component is different and has a different use case but by taking a simple component like the Text component we can see how simple for developers and teams to define their own props and style mapping to suit their preferred way of working.

The Text component has a single component part called component. This allows us to easily see the way two teams may approach styling the Text component.

3.4.1. Modular approach

Some developers and teams may choose a more modular approach to mapping styles to components in their projects. For example, the Text component may need to know Size, Color, and Font. To set up these props in the Text.props.ts file they may add the following props:

export const classProps: ClassProps = {
  size: {
    type: String,
    default: "default",
  },
  color: {
    type: String,
    default: "default",
  },
  font: {
    type: String,
    default: "default",
  },
};

The above would make the following props available to the Text component: size, color, and font, and each prop would default to the value default. However, as it stands they would not map any styles.

To map styles for each of these props we would need to open the Text.parts.ts file and add each prop to the relevant component parts with the available keys and their style values. Because the Text component only has one component part, component, each prop key will be a direct child property of component, in more complicated components developers can add props as property keys to only the parts that are affected by that prop. Text.parts.ts in this example may look something like this:

const parts: Parts = {
    component: {
      color: {
        default: ["color-black"],
        blue: ["color-blue"]
      },
      size: {
        default: ["size—default"],
        medium: ["size—medium"],
        large: ["size—large"],
      },
      font: {
        default: ["font-sans"],
        serif: ["font-serif weight-bold"]
      },
    },
  };

With the styles mapped, developers and their teams could now use the Text component in the following manner:

<BonesText font="serif" color="blue" size="large">Hello world</BonesText>

Which would output the following:

<p data-component="BonesText" data-part="component" class="font-serif weight-bold color-blue size-large">Hello world</p>

3.4.2. Broad approach

Alternatively, some developers and teams may choose a more broad approach to mapping styles to the Text component in their projects. For example, they may choose to encompass all the styles within a single prop named textStyle. To set up this prop in the Text.props.ts file they may add the following prop:

export const classProps: ClassProps = {
  textStyle: {
    type: String,
    default: "default",
  }
};

Like the more modular approach, the developers and teams would need to update the Text.parts.ts file to begin mapping styles for the textStyle prop.

To map styles for the textStyle prop we would need to open the Text.parts.ts file and add the prop to the relevant component parts with the available keys and their style values. Because the Text component only has one component part, component, textStyle will be a direct child property of component, in more complicated components developers can add props as property keys to only the parts that are affected by that prop. Text.parts.ts in this example may look something like this:

const parts: Parts = {
    component: {
      textStyle: {
        default: ["color-black size-default font-sans"],
        title: ["color-blue size-large font-serif weight-bold"]
      },
   },
};

With the styles mapped, developers and their teams could now use the Text component in the following manner:

<BonesText textStyle="title">Hello world</BonesText>

Which would output the following:

<p data-component="BonesText" data-part="component" class="font-serif weight-bold color-blue size-large">Hello world</p>

4. Getting started

To get started with Barebones, in a Vue 3 or Nuxt 3 begin by running one of the following commands in the root of your project:

4.1.1. Yarn users

yarn add @wearethreebears/barebones

4.1.2. NPM users

npm install @wearethreebears/barebones

Once Barebones is installed, you will need to configure it for use in your project:

4.2.1. Vue 3 users

Add the aliases to your paths in your tsconfig.json file:

{
    //
    "@barebones/*": [
        "node_modules/@wearethreebears/barebones/src/*"
    ],
    "@barebones-local/*": [
        "barebones/*"
    ],
    //
}

Add the aliases to your aliases in your vite.config.js file:

{
    //
    "@barebones": fileURLToPath(
        new URL(
        "./node_modules/@wearethreebears/barebones/src",
        import.meta.url
        )
    ),
    "@barebones-local": fileURLToPath(
        new URL("./barebones", import.meta.url)
    ),
    //
}

4.2.2. Nuxt 3 users

Add the aliases to your tsconfig.json file:

{
    //
    "compilerOptions": {
        "paths": {
        "@/*": [
            "./*"
        ],
        "@barebones/*": [
            "node_modules/@wearethreebears/barebones/src/*"
        ],
        "@barebones-local/*": [
            "barebones/*"
        ],
        }
    }
    //
}

Add the aliases to your nuxt.config.ts file:

import { resolve } from 'path'

export default defineNuxtConfig({
    {
        //
        alias: {
            "@": fileURLToPath(new URL("./src", import.meta.url)),
            "@barebones": fileURLToPath(new URL("./node_modules/@wearethreebears/barebones/src", import.meta.url)),
            "@barebones-local": fileURLToPath(new URL("./barebones", import.meta.url)),
        },
        //
    },
})

Auto import the components (By default this will prefix all Barebones components with Bones):

export default defineNuxtConfig({
    //
    buildModules: ['@wearethreebears/barebones/nuxt'],
    //
})

4.3. Add local configuration files

Next you will need to add the local configuration files using an NPX command. You can choose a blank canvas configuration, which will just contain the boilerplate for you to start adding your props and classes or you can choose from one of the pre-made theme configurations as a starting point.
To start with a blank canvas run:

npx @wearethreebears/barebones theme blank

To use a pre-made theme you can run a variation of the following command:

npx @wearethreebears/barebones theme <cssLibrary>/<themeName>

Where <cssLibrary> is the name of the library (e.g. Tailwind, Vanilla) and <themeName> is a theme within that library. See all available themes here.

At the time of writing, the only pre-made theme is Tailwind Salient and will require Tailwind JIT to be set up in your application. To set up Tailwind in your application see the Tailwind Documentation.
To add the Tailwind Salient theme, you would run:

npx @wearethreebears/barebones theme tailwind/salient

5. Start building

Now Barebones and its local configuration are installed, you can start building. To view all of the components Barebones makes available to you with their defined parts and examples please refer to the Barebones Documentation. The documentation, while it is still in its first draft, is fairly complete and should provide you with all of the knowledge you need to start using components Barebones quickly.

6. Conclusion

If you’ve found this article useful or the found the project interesting please drop the project a star on Github and please follow me on Medium, Dev.to and/ or Twitter.

Understanding Javascript imports and exports

Liam Hall — Fri, 14 Jan 2022 09:23:02 +0000

Introduction

If you've spent any time working with Javascript over the past 5 or so years, you've probably come across Javascript Imports and Exports. Introduced as part of the ECMAScript 6 (ES6) specification in June 2015 and now supported in all major browsers, Imports and Exports have shaped the way we build modern Javascript applications. In the beginning, Javascript wasn't designed to be modular. However, 2009 saw the release of Node JS, a popular JavaScript runtime environment that runs outside the browser. Node JS soon began supporting modularity through the CommonJS require function and with this developers began searching for solutions to bring modularity to Javascript in the browser.

What is modularity in Javascript

A Javascript module is a file that can export variables, functions, and classes that can be imported anywhere, allowing developers to share code across multiple files or projects.

Exporting from Javascript modules

Exporting variables, functions, and classes is made simple in Javascript with the export keyword, allowing developers to specify which data/functionality they would like accessed outside the module. Take the following example of a Dice module:

const NUMBERS = [1, 2, 3, 4, 5, 6];

function min() {
    return Math.min(...NUMBERS);
}

function max() {
    return Math.max(...NUMBERS);
}

export function roll() {
    return Math.floor((Math.random() * max()) +  min());
}

The Dice module exports a single function, rollDice(), making it the only data/functionality available to be imported elsewhere. In some cases, the developer may decide that more than one piece of data/functionality, or even all data/functionality should be available outside of the Dice module. In this case, the developer could simply prefix each variable and function with the export keyword:

export const NUMBERS = [1, 2, 3, 4, 5, 6];

export function min() {
    return Math.min(...NUMBERS);
}

export function max() {
    return Math.max(...NUMBERS);
}

export function roll() {
    return Math.floor((Math.random() * max()) +  min());
}

Now every variable and function in the Dice module can be imported individually elsewhere. However, in cases where there is lots of data/functionality to be imported, importing everything individually can become frustrating. Thankfully Javascript also provides developers with the default keyword. Using the default keyword, developers can specify a default export. In the Dice module, the developer could create a default export to make all of the module data/functionality available elsewhere with an import-defined prefix:

export default {
    NUMBERS,
    min,
    max,
    roll
}

Importing from Javascript modules

What and how a developer imports data/functionality from a Javascript module depends entirely on what data/functionality the developer would like to make use of and how the module exports that data/functionality. In the Dice module, there is individually exported data/functionality and a default export.

Importing a default export

The syntax for importing default exports in Javascript is simple. If the developer was to import the default export from the Dice module it may look like this:

import Dice from './modules/dice.js';

NOTE: ./modules/dice.js is the path to the file.

The developer could now reference the default export as Dice, giving them access to everything in the default export object as: Dice.NUMBERS, Dice.min(), Dice.max(), Dice.roll().

To prevent potential name clashes, Javascript allows default exports to be imported under any valid name. For example, the Dice module could be imported as Foo:

import Foo from './modules/dice.js';

The developer could now reference the default export as Foo,
giving the them access to everything in the default export object as: Foo.NUMBERS, Foo.min(), Foo.max(), Foo.roll().

Importing an individual data/ functionality

In some cases a module may not provide a default export, the default export may not provide the data/functionality the developer wishes to use, or default export may return lots of redundant data/functionality. For these situations, Javascript allows the developer to import individual data/functionality. To import individual data/functionality, the developer should wrap the desired exported data/functionality in curly brackets. For example, if the developer would like to import the NUMBERS and the roll() data/functionality from the Dice module:

import { NUMBERS, roll } from './modules/dice.js';

This would give the developer access to the NUMBERS and roll() data/functionality as NUMBERS and roll(), exactly the names given to them by the module they were exported from. There are times when it's not suitable to use the names given by the module the developer is importing from are not suitable. When importing from multiple modules, the chances of name clashes become increasingly likely, the given names may not be descriptive enough. For these situations, Javascript provides the as keyword. The as keyword can be used to rename imported individual data/functionality. For example, should the developer want to import the NUMBERS data as DICE_NUMBERS and the roll() functionality as rollDice:

import { NUMBERS as DICE_NUMBERS, roll as rollDice } from './modules/dice.js';

This would give the developer access to the NUMBERS and roll() data/functionality as DICE_NUMBERS and rollDice().

Importing and namespacing all individual data/functionality

In some cases, the developer may wish to import all available individual data/functionality from a module, without listing out every individual export. Not all modules will export all of that data/functionality as a default export. In these cases the developer can import all module exports under a namespace, using the * key. For example, if the developer wished to import all the Dice module data/functionality under the namespace Bar:

import * as Bar from './modules/dice.js';

This would give the developer access to the NUMBERS, min(), max(), and roll() data/functionality as Bar.DICE_NUMBERS, Bar.min(), Bar.max(), and Bar.roll().

Conclusion

Javascript modularity has changed the way developers build web applications. There are several ways to import data/functionality from a module, hopefully, this post provides an insight into when and why to use each import syntax.

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.

Building Shopify themes with Tailwind CSS

Liam Hall — Fri, 09 Oct 2020 11:49:25 +0000

Shopify is one of the largest e-commerce platforms on the planet, with a massive 20% global market share of the top 1 million websites using eCommerce technologies (According to Built with - Correct at the time of writing). This makes Shopify very lucrative for developers, from building bespoke themes for clients and reusable themes for the Theme Store to applications for the Shopify App Store.

With all that said the built-in, browser-based theme editing experience is limited and far from enjoyable. Thankfully Shopify also offers Shopify Theme Kit, Shopify Theme Kit allows us to edit themes locally in our favorite text editor and watch for changes that are automatically pushed to our Shopify store. The advantages of editing our files locally don't just stop at being able to use our favorite text editor though, it also allows us to take advantage of build tools like Webpack, Gulp, etc.

Getting started with Theme Kit

Installation

If you haven't used Theme Kit before you'll need to install it, if you have already installed Theme Kit you can skip ahead to Get API Access

macOS Installation

Use Homebrew to install Theme Kit by running the following commands:

brew tap shopify/shopify
brew install themekit

If brew install theme kit does not work for you, please try brew install shopify/shopify/themekit as pointed out by @dnirns in the comments

Windows Chocolatey Installation

If you have Chocolatey installed install Theme Kit by running the following commands:

choco install themekit

Linux Installation

If you are on a Linux based system, you can use the following installation script to automatically download and install the latest Theme Kit:

curl -s https://shopify.github.io/themekit/scripts/install.py | sudo python

Get API Access

To connect Theme Kit to our store we'll need to create a private app in the stores Shopify Admin. If you've already created a private app you can skip ahead to Create a Theme Kit theme

From the Shopify Admin area, we'll open Apps from the left-hand panel.
Towards the bottom of the page we need to click on Manage private apps
Then we'll click on Create new private app (If there's a notice that reads "Private app development is disabled", then we'll need to click "Enable private app development" first. Note: Only the store owner can enable private app development)
In the App details section, we must fill out the app name and contact email address.
We need to scroll down to the Admin API section and click Show inactive Admin API permissions.
Scroll to the Themes section and select Read and write from the dropdown.
Click Save.
Read the private app confirmation dialog, then click Create app.

Once we've created our app we'll be returned to our app detail page, unique access credentials are visible in the Admin API section. We'll need to copy the password, this will be needed in the next step.

Create a Theme Kit theme

Now we have Theme Kit installed and we have created our private app we are ready to create our new Theme Kit theme. First, we'll open up our chosen themes directory and create a new folder with the name of our theme, for this example, we'll call it tailwind-shopify-theme. Upon creating our tailwind-shopify-theme folder we'll need to navigate there with our terminal and create our Theme Kit theme by running the following command:

theme new --password=[your-password] --store=[your-store.myshopify.com] --name=[theme name]

Where [your-password] is equal to the API password from our private application, [your-store.myshopify.com] is equal to our stores myshopify.com domain, and [theme name] is equal to our theme name (If our theme name has spaces we'll need to wrap this in quote marks).

If we've successfully followed the steps to create our Shopify Theme Kit theme it'll now appear in our Shopify Admin. We can see this by opening Online store from the left-hand panel and clicking Themes below. From the Theme's page, we can scroll down to Theme library which should now list our new Theme.

Watching our Shopify theme for changes

Now that we are connected locally to our online Shopify theme, we can begin watching our local files for changes. To begin watching our theme we need to navigate to our theme folder from our terminal, in the case the example we used previously, tailwind-shopify-theme. Once in the theme folder, we can run the following command to start watching our files for changes:

theme watch

If we would like to see this in action, we can preview our new theme by finding it in the Theme library section of the Themes page and clicking Actions > Preview. Then in our local text editor, edit the index.liquid file from the templates directory and save it. We can then refresh our theme preview and see our changes in Shopify.

Installing Tailwind

Now that we can edit our Shopify themes locally we can get started using Tailwind. The first thing we need to do is create our package.json file by running the following command and working through the steps - defaults are fine for this example:

npm init

Once our package.json file has been created we can install Tailwind using the following command:

npm install tailwindcss

Now that tailwind is installed we can create our tailwind.config.js file using the following command:

npx tailwindcss init

This will create a tailwind.config.js, let's open that tailwind.config.jsfile. First, let's uncomment the key-value pairs in the future object, this will save us from receiving any deprecation warnings later. Now, we need to edit the purge array and replace it with an object that has two keys, content and enabled. enabled will be a Boolean that will tell Tailwind whether we'd like to purge our styles or not, we'll default this to false for now but we'll back to this later. content will be an array telling Tailwind where to look for our styles, we'll set it up to look in the following common Shopify folders.

purge: {
    enabled: false,
    content: [
      './layout/*.liquid',
      './templates/*.liquid',
      './sections/*.liquid',
      './snippets/*.liquid',
    ],
  },

Now Tailwind is installed we need to create our source stylesheet. In the root of our Shopify theme, we can create a directory called src/css and within this folder we'll create a file called application.css. Once we've created our applications.css we need to paste in the following code:

/* purgecss start ignore */
@tailwind base;
@tailwind components;
/* purgecss end ignore */

@tailwind utilities;

Editing the output CSS

By default, our new Theme Kit theme will come with a folder called assets containing a file called application.scss.liquid, we need to edit this file name and change it to application.css.liquid. Once we've changed the name we must open the theme.liquid file from the layout folder and replace the following line:

{{ 'application.scss.css' | asset_url | stylesheet_tag }}

with:

{{ "application.css" | asset_url | stylesheet_tag }}

TailwindCSS in development

When using Tailwind in development we need to ensure we have all of Tailwind's styles at our disposal. Earlier when editing the tailwind.config.js file we set enabled on the purge object to false, this means that our Tailwind build will not remove any of Tailwind's utility classes. Whenever we are developing our theme we will need to ensure that enabled on the purge object in tailwind.config.js is set to false. Now that PurgeCSS is disabled we can run:

npx tailwindcss build src/css/application.css -o assets/application.css.liquid

This will build our application.css.liquid file and include all of Tailwind's utility classes. Now we have access to all of these styles we can deploy the stylesheet using the following command:

theme deploy

Now that the development stylesheet deployed, we can watch our theme and begin building our theme using:

theme watch

TailwindCSS in production

When using Tailwind in production we need to ensure we remove any unused styles. As in Development, PurgeCSS is enabled/disabled in the tailwind.config.js file. Whenever we finish development and want to push our production-ready code we'll want to set enabled on the purge object in tailwind.config.js to true. Now PurgeCSS is enabled we can deploy our stylesheet:

npx tailwindcss build src/css/application.css -o assets/application.css.liquid

This will build our application.css.liquid file and remove any unused Tailwind utility classes.

You may want to set the enabled Boolean via an environment variable

Conclusion

You should now be set to start creating Shopify themes with Tailwind CSS. Happy creating!

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.

Dynamic component styles in Vue (Composition API and TypeScript) using Tailwind CSS and Lookup tables

Liam Hall — Tue, 29 Sep 2020 13:28:59 +0000

This article will assume some knowledge of Vue

You can find the options API version here.

Last week I wrote an article about how I choose to utilize lookup tables when working with dynamic component styles in Nuxt, which you can find here. This week I've been working with Vue 3 and just like when using Nuxt, in Vue I utilize lookup tables when working with dynamic component styles, here's how:

Tailwind and PurgeCSS

PurgeCSS is a fantastic plugin, however, it cannot parse or run JavaScript and in most cases is only used at build time. Because of this, it can lead to unexpected inconsistencies between development and production environments if used incorrectly.

Starting a fresh Vue project with Tailwind CSS

Let's begin by creating a fresh Vue installation by opening your terminal and running the following command:

vue create <your-project-name>

We'll follow the CLI instructions to set up Vue with the "manually select features" option, ensuring to check "Choose Vue version" and "TypeScript" from the features list, the rest can be left as deffault. Once our project has finished setting up, we can navigate to the root directory and install Tailwind CSS with the following command:

npm install tailwindcss

Once Tailwind CSS has successfully installed, we'll need to create our tailwind.config.js using the following command:

npx tailwindcss init

When the tailwind.config.js file has been created we will need to configure it to scan our .vue files for classes. First we'll uncomment the properties in the future object, this will make upgrading easier in future. Next, within the purge array, add the following line:

'src/**/*.vue',

Now we can
create our Tailwind stylesheet. Navigate to the src/assets folder, create a new directory called css and within it create a new file called styles.css and populate it with the Tailwind CSS imports:

@tailwind base;
@tailwind components;
@tailwind utilities;

Now that the stylesheet is set up we can import it into our application by opening the main.js file from within the src directory and adding the following line:

import '@/assets/css/styles.css';

Finally we need to create our PurgeCSS config file, again in the project root, create a new file, this time called postcss.config.js and configure it with the following code:

// postcss.config.js

const autoprefixer = require('autoprefixer');
const tailwindcss = require('tailwindcss');

module.exports = {
    plugins: [
        tailwindcss,
        autoprefixer,
    ],
};

Dynamic component styles in Vue with Tailwind

One of the key features of components in Vue is the ability to pass props. Props are custom attributes passed to a component that can be used to control appearance and function. Let's look at creating a simple button component using Tailwind that accepts two colorways, 'primary' and 'secondary':

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="{ 
            'bg-blue-800 text-white border-blue-800 hover:bg-transparent hover:text-blue-800 hover:border-blue-800' : color == 'primary',
            'bg-transparent text-blue-800 border-blue-800 hover:bg-blue-800 hover:text-white hover:border-blue-800' : color == 'secondary'
        }"
    >
        <slot />
    </button>
</template>

<script lang="ts">
    import { defineComponent, PropType } from 'vue'

    export default defineComponent({
        name: 'component--button',

        props: {
            color: {
                required: false,
                type: String as PropType<string>,
                default: 'primary',
                validator: value => {
                    return ['primary', 'secondary'].includes(value)
                }
            }
        }
    })
</script>

So we have our button component that accepts 2 dynamic colorways, 'primary' and 'secondary', exactly as we'd set out, however even in this simple component it's easy to see how these dynamic styles could spiral out of control in more complex components. We also have a color props validator which we have to manually keep in sync with the dynamic styles in the template.

Extracting styles and keeping validators synced with Lookup tables

If you haven't heard of a lookup table, a lookup table is a simple key-value pair object we can use to match keys to data. We can take advantage of lookup tables to extract the dynamic styles and ensure our validator always stays in sync with those dynamic styles.

For this example, we'll be creating a new folder in the src directory called validators to store our lookup tables, although the same technique could be used to make use of lookup tables within the component file if preferred. Once you've created a new folder called validators, create a new file inside called Button.ts. Inside Button.ts we are going to export a const called ButtonColors, a lookup table which will contain our key-value pairs for our dynamic styles, like so:

export const ButtonColors = {
    'primary': 'bg-blue-800 text-white border-blue-800 hover:bg-transparent hover:text-blue-800 hover:border-blue-800',
    'secondary': 'bg-transparent text-blue-800 border-blue-800 hover:bg-blue-800 hover:text-white hover:border-blue-800'
}

Now we have extracted our dynamic styles to a lookup table we need to make a couple of changes to our component, firstly, beneath the opening script tag we need to import our ButtonColors const:

<script lang="ts">
/**/
import { ButtonColors } from '../validators/Button'

export default defineComponent({/**/})
</script>

Next in our color prop we need to let TypesScript know that the string should be equal to one of the keys of our ButtonColors lookup table and replace the array current array of strings with an array of keys from the ButtonColors lookup table:

<script lang="ts">
    export default defineComponent({
        /**/
        props: {
            color: {
                required: false,
                type: String as PropType<keyof typeof ButtonColors>,
                default: 'primary',
                validator: (value : string ) => {
                    return Object.keys(ButtonColors).includes(value)
                }
            }
        }
        /**/
    })
</script>

Now we can create a computed property to handle the dynamic classes in the component template, first we need to import computed from vue, in the same way we have with defineComponent and PropType:

<script>
    import { defineComponent, PropType, computed } from 'vue'
    /**/
</script>

Now we can use the setup method and pass it props as a parameter to allow us to set up a computed buttonColor property like so:

<script>
/**/
export default defineComponent({
    /**/
    setup(props) {
        const buttonColor = computed(() : string  => {
            return ButtonColors[props.color]
        })

        return {
            buttonColor
        }
    }
})
</script>

We can then replace all of the dynamic classes in the template with our new computed property:

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="[buttonColor]"
    >
        <slot />
    </button>
</template>

Altogether that should give us a component template that looks like this:

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="[buttonColor]"
    >
        <slot />
    </button>
</template>

<script lang="ts">
    import { defineComponent, PropType, computed } from 'vue'

    import { ButtonColors } from '../validators/Button'

    export default defineComponent({
        name: 'component--button',

        props: {
            color: {
                required: false,
                type: String as PropType<keyof typeof ButtonColors>,
                default: 'primary',
                validator: (value : string ) => {
                    return Object.keys(ButtonColors).includes(value)
                }
            }
        },

        setup(props) {
            const buttonColor = computed(() : string  => {
                return ButtonColors[props.color]
            })

            return {
                buttonColor
            }
        }
    })
</script>

Everything is looking great, our dynamic styles are extracted and our validators will automatically stay in sync with any new dynamic styles we add, however unfortunately at the moment our component will still not be styled as expected in production. Thankfully, there's a very simple fix, open up tailwind.config.js from the root of the project and within the purge array, add 'src/validators/*.js', this will tell PurgeCSS to check for styles in our validators folder, our final purge object should look something like this:

module.exports = {
/**/
    purge: [
        'src/**/*.vue',
        'src/validators/*.ts'
    ]
/**/
}

Testing

If you'd like to test your lookup tables are working correctly in production you can test your project in production locally. Begin by installing the Node.js static file server:

npm install -g serve

Once installed, navigate to the root of your project and run:

serve -s dist

Conclusion

Hopefully, you've found this a useful exercise in cleaning up your dynamic classes in Vue options API, Tailwind, and PurgeCSS.

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.

Dynamic component styles in Vue (Options API) using Tailwind CSS and Lookup tables

Liam Hall — Tue, 29 Sep 2020 10:22:34 +0000

This article will assume some knowledge of Vue

You can find the Composition API with TypeScript version here.

Tailwind and PurgeCSS

Starting a fresh Vue project with Tailwind CSS

Let's begin by creating a fresh Vue installation by opening your terminal and running the following command:

vue create <your-project-name>

We'll follow the CLI instructions to set up a default Vue 3 project. Once our project has finished setting up, we can navigate to the root directory and install Tailwind CSS with the following command:

npm install tailwindcss

Once Tailwind CSS has successfully installed, we'll need to create our tailwind.config.js using the following command:

npx tailwindcss init

'src/**/*.vue',

@tailwind base;
@tailwind components;
@tailwind utilities;

Now that the stylesheet is set up we can import it into our application by opening the main.js file from within the src directory and adding the following line:

import '@/assets/css/styles.css';

Finally we need to create our PurgeCSS config file, again in the project root, create a new file, this time called postcss.config.js and configure it with the following code:

// postcss.config.js

const autoprefixer = require('autoprefixer');
const tailwindcss = require('tailwindcss');

module.exports = {
    plugins: [
        tailwindcss,
        autoprefixer,
    ],
};

Dynamic component styles in Vue with Tailwind

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="{ 
            'bg-blue-800 text-white border-blue-800 hover:bg-transparent hover:text-blue-800 hover:border-blue-800' : color == 'primary',
            'bg-transparent text-blue-800 border-blue-800 hover:bg-blue-800 hover:text-white hover:border-blue-800' : color == 'secondary'
        }"
    >
        <slot />
    </button>
</template>

<script>
    export default {
        name: 'component--button',

        props: {
            color: {
                required: false,
                type: String,
                default: 'primary',
                validator: value => {
                    return ['primary', 'secondary'].includes(value)
                }
            }
        }
    }
</script>

Extracting styles and keeping validators synced with Lookup tables

For this example, we'll be creating a new folder in the src directory called validators to store our lookup tables, although the same technique could be used to make use of lookup tables within the component file if preferred. Once you've created a new folder called validators, create a new file inside called Button.js. Inside Button.js we are going to export a const called ButtonColors, a lookup table which will contain our key-value pairs for our dynamic styles, like so:

export const ButtonColors = {
    'primary': 'bg-blue-800 text-white border-blue-800 hover:bg-transparent hover:text-blue-800 hover:border-blue-800',
    'secondary': 'bg-transparent text-blue-800 border-blue-800 hover:bg-blue-800 hover:text-white hover:border-blue-800'
}

Now we have extracted our dynamic styles to a lookup table we need to make a couple of changes to our component, firstly, beneath the opening script tag we need to import our ButtonColors const:

<script>
import { ButtonColors } from '@/validators/Button'

export default {/**/}
</script>

Next in our color props validator, replace the array with an array of keys from the ButtonColors lookup table:

/**/
validator: (value) => {
    return Object.keys(ButtonColors).includes(value)
},
/**/

Now we can create a computed property to handle the dynamic classes in the component template:

<script>
/**/
export default {
    /**/
    computed: {
        buttonColor() {
            return ButtonColors[this.color]
        },
    }
}
</script>

We can then replace all of the dynamic classes in the template with our new computed property:

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="[buttonColor]"
    >
        <slot />
    </button>
</template>

Altogether that should give us a component template that looks like this:

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="[buttonColor]"
    >
        <slot />
    </button>
</template>

<script>
    import { ButtonColors } from '@/validators/Button'

    export default {
        name: 'component--button',

        props: {
            color: {
                required: false,
                type: String,
                default: 'primary',
                validator: value => {
                    return Object.keys(ButtonColors).includes(value)
                }
            }
        },

        computed: {
            buttonColor() {
                return ButtonColors[this.color]
            },
        }
    }
</script>

module.exports = {
/**/
    purge: [
        'src/**/*.vue',
        'src/validators/*.js'
    ]
/**/
}

Testing

If you'd like to test your lookup tables are working correctly in production you can test your project in production locally. Begin by installing the Node.js static file server:

npm install -g serve

Once installed, navigate to the root of your project and run:

serve -s dist

Conclusion

Hopefully, you've found this a useful exercise in cleaning up your dynamic classes in Vue options API, Tailwind, and PurgeCSS.

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.

Dynamic component styles in Nuxt using Tailwind CSS and Lookup tables

Liam Hall — Fri, 25 Sep 2020 08:19:06 +0000

This article will assume some knowledge of Nuxt / Vue

Tailwind, Nuxt, and PurgeCSS

Tailwind CSS is one of the hottest topics in frontend development right now. A utility first CSS framework, created by Adam Wathan, which over the past few years has grown from side project to successful business. If you've ever used Tailwind, you may be aware that it utilizes PurgeCSS at build time to prune unused styles and create a slimline stylesheet made up of only the classes used in your web application. Many frameworks now make use of PurgeCSS to remove unnecessary bulk from production stylesheets at build time and you can use it in Nuxt too. When creating a new project in Nuxt and selecting the Tailwind preset, PurgeCSS will be installed automatically, although you can utilize it in any project using the nuxt-purgecss build module.

Starting a fresh Nuxt project with Tailwind CSS

Let's begin by creating a fresh Nuxt installation by opening your terminal and running the following command:

npx create-nuxt-app <your-project-name>

To keep things simple we'll use the default settings other than ensuring we select Tailwind CSS from the UI framework.

Dynamic component styles in Nuxt with Tailwind

One of the key features of components in Nuxt (Vue) is the ability to pass props. Props are custom attributes passed to a component that can be used to control appearance and function. Let's look at creating a simple button component using Tailwind that accepts two colorways, 'primary' and 'secondary':

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="{ 
            'bg-blue-800 text-white border-blue-800 hover:bg-transparent hover:text-blue-800 hover:border-blue-800' : color == 'primary',
            'bg-transparent text-blue-800 border-blue-800 hover:bg-blue-800 hover:text-white hover:border-blue-800' : color == 'secondary'
        }"
    >
        <slot />
    </button>
</template>

<script>
    export default {
        name: 'component--button',

        props: {
            color: {
                required: false,
                type: String,
                default: 'primary',
                validator: value => {
                    return ['primary', 'secondary'].includes(value)
                }
            }
        }
    }
</script>

Extracting styles and keeping validators synced with Lookup tables

For this example, we'll be creating a new folder in the root of our project called validators to store our lookup tables, although the same technique could be used to make use of lookup tables within the component file if preferred. Once you've created a new folder called validators, create a new file inside called Button.js. Inside Button.js we are going to export a const called ButtonColors, a lookup table which will contain our key-value pairs for our dynamic styles, like so:

export const ButtonColors = {
    'primary': 'bg-blue-800 text-white border-blue-800 hover:bg-transparent hover:text-blue-800 hover:border-blue-800',
    'secondary': 'bg-transparent text-blue-800 border-blue-800 hover:bg-blue-800 hover:text-white hover:border-blue-800'
}

Now we have extracted our dynamic styles to a lookup table we need to make a couple of changes to our component, firstly, beneath the opening script tag we need to import our ButtonColors const:

<script>
import { ButtonColors } from '~/validators/Button'

export default {/**/}
</script>

Next in our color props validator, replace the array with an array of keys from the ButtonColors lookup table:

/**/
validator: (value) => {
    return Object.keys(ButtonColors).includes(value)
},
/**/

Now we can create a computed property to handle the dynamic classes in the component template:

<script>
/**/
export default {
    /**/
    computed: {
        buttonColor() {
            return ButtonColors[this.color]
        },
    }
}
</script>

We can then replace all of the dynamic classes in the template with our new computed property:

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="[buttonColor]"
    >
        <slot />
    </button>
</template>

Altogether that should give us a component template that looks like this:

<template>
    <button 
        class="px-4 py-2 text-center transition-colors duration-300 ease-in-out border border-solid rounded shadow-md"
        :class="[buttonColor]"
    >
        <slot />
    </button>
</template>

<script>
    import { ButtonColors } from '~/validators/Button'

    export default {
        name: 'component--button',

        props: {
            color: {
                required: false,
                type: String,
                default: 'primary',
                validator: value => {
                    return Object.keys(ButtonColors).includes(value)
                }
            }
        },

        computed: {
            buttonColor() {
                return ButtonColors[this.color]
            },
        }
    }
</script>

Everything is looking great, our dynamic styles are extracted and our validators will automatically stay in sync with any new dynamic styles we add, however unfortunately at the moment our component will still not be styled as expected in production. Thankfully, there's a very simple fix, open up tailwind.config.js from the root of the project and within the purge object, find the content array and add 'validators/*.js', this will tell PurgeCSS to check for styles in our validators folder, our final purge object should look something like this:

purge: {
    // Learn more on https://tailwindcss.com/docs/controlling-file-size/#removing-unused-css
    enabled: process.env.NODE_ENV === 'production',
    content: [
        'components/**/*.vue',
        'layouts/**/*.vue',
        'pages/**/*.vue',
        'plugins/**/*.js',
        'validators/*.js',
        'nuxt.config.js'
    ]
}

Conclusion

Hopefully, you've found this a useful exercise in cleaning up your dynamic classes in Nuxt, Tailwind, and PurgeCSS.

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.

5 simple changes that will make you a better JavaScript developer

Liam Hall — Wed, 17 Jun 2020 16:37:40 +0000

Introduction

One of the beautiful things about programming is that there are hundreds of different roads to the same destination. Everyone has their own style and everyone has their own preferences. Whatever your style or preference though, there are some simple techniques you can adopt to make your life, and the life collaborators (including your future self) easier.

Use descriptive names

Using descriptive names is one of the most straight forward changes you can make to your workflow. By using descriptive names for functions and variables, your code can become almost entirely self documenting, although I would still suggest adding comments to complex functionality. We've all been there, you open an old project or a project you've inherited from another developer and it's full of generic names which mean nothing. Take the following example, the code is fetching some items from which it's creating a new Array, Alt items, before setting the icon property to 'star'. In this instance you as the developer, have no idea what those items that are being fetched and manipulated are:

   let items = fetchItems()
   let altItems = items.filter(item => item.featured == true)

   altItems.forEach(item => {
       item.icon = 'star'
   })

You can easily make this code snippet more understandable with descriptive names. For arguments sake, let's say your fetch function is returning an array of articles. Now see the following example for how you may choose to rewrite your previous code snippet with more descriptive names:

   let articles = fetchArticles()
   let featuredArticles = articles.filter(article => article.featured == true)

   featuredArticles.forEach(featuredArticle => {
       featuredArticle.icon = 'star'
   })

Extract common functions

It's not uncommon when writing in any programming language to want perform repetitive tasks within functions and loops. Of course you can repeat yourself each time, however your code will soon become hard to maintain. Take the following example, there are 2 loops, one for articles and one for projects, for each article / project the code will add a standardised formatted date:

articles.forEach(article => {
    let date = new Date(article.createdAt),
        day = date.getDate(),
        month = date.getMonth()+1,
        year = date.getFullYear()

    article.formattedDate = `${day}/${month}/{year}`
})

projects.forEach(project => {
    let date = new Date(project.createdAt),
        day = date.getDate(),
        month = date.getMonth()+1,
        year = date.getFullYear()

    project.formattedDate = `${day}/${month}/{year}`
})

Imagine now you wanted to change the date format, you now have 2 places you need to update your formatting, the articles loop and the projects loop. However by extracting the date functionality from each of the loops and creating a new function, you can reuse the same code in each. Then, should you wish to change your date format, you only need to do it in one place, even if you have hundreds of instances. Now see the following example for how you might choose to refactor your previous snippet and extract the date formatting functionality.

const formatDate = (rawDate) => {
    let date = new Date(rawDate),
        day = date.getDate(),
        month = date.getMonth()+1,
        year = date.getFullYear()

    return `${day}/${month}/{year}`
}

articles.forEach(article => {
    article.formattedDate = formatDate(article.createdAt)
})

projects.forEach(project => {
    project.formattedDate = formatDate(project.createdAt)
})

In situations like this, you could argue that defining variables inside your extracted function offers very little in the way of extra clarity. In that case use the date values directly:

const formatDate = (rawDate) => {
    let date = new Date(rawDate)

    return `${date.getDate()}/${date.getMonth()+1}/{date.getFullYear()}`
}

Avoid nested conditional statements and return early

Conditional statements are common place in almost every Web Application, determining whether statement is true or false and returning or setting the relevant data. The problem with conditionals is that they can very quickly become unsightly and unreadable. Take the following example, the getShopTradingStatement function returns a string based on whether the shop is currently trading and if it is, whether the shop has had its opening day:

const getShopTradingStatement = (shop) => {
    if (shop.isTrading) {
        if (shop.openFrom < Date.now()) {
            return `This shop is currently trading!`
        }
        else {
            return `This shop will open it's doors from ${shop.openFrom}`
        }
    }
    else {
       return `This shop is no longer trading.`
    }
}

Nesting statements in this way, while perfectly valid, already feels cluttered. By switching up your statements and taking advantage of early returns you can make this very same functionality much tidier. Now see the following example for how you might choose to refactor your previous snippet by returning the output of your primary else statement early:

const getShopTradingStatement = (shop) => {
    if (!shop.isTrading) return `This shop is no longer trading.`
    if (shop.openFrom < Date.now()) return `This shop is currently trading!`

    return `This shop will open it's doors from ${shop.openFrom}`
}

Use look up tables

Look up tables are a fantastic way of cleaning up messy, repetitive if statements. Take the following example, you have a userHasAccessPermissionsForTask function which accepts the users role and the task they'd like to perform. The function checks against 3 possible user roles and associated permissions for each. If the user role has permissions to perform the task, the function will return true else it will return false:

const userHasAccessPermissionsForTask = (userRole, task) => {
    if (userRole == 'admin' && ['write', 'edit', 'read'].includes(task)) {
        return true
    }
    if (userRole == 'editor' && ['edit', 'read'].includes(task)) {
        return true
    }
    if (userRole == 'subscriber' && ['read'].includes(task)) {
        return true
    }
    return false
}

The previous code snippet is perfectly valid but it's not particularly clear. You're also repeating your includes function on each if statement, if in future you wanted to test against that data in a different way you'd need to ensure you did it in 3 places. You could make the argument for extracting that functionality as it's own function but creating a function to return a built in function seems a little odd, right? Luckily with look up tables you can avoid all that. Now see the following example for how you might choose to refactor your previous snippet using a look up table. The look up table is an object that, in this case, uses the user roles as keys and permissions as values. You can now return a single includes function which references the permissions object property with the key equal to the given userRole:

const userHasAccessPermissionsForTask = (userRole, task) => {
    const permissions = {
        admin: ['write', 'edit', 'read'],
        editor: ['edit', 'read'],
        subscriber: ['read']
    }
    return permissions[userRole].includes(task)
}

Start sharing your code

I think sharing your code is possibly one of the most valuable things you can do if you want to continue to grow and learn as a developer. Things change fast in tech and it's very easy to be left behind, particularly when you're busy. Sharing your code, whether via code reviews, pair programming*, even through blogging and social media platforms like Twitter allows people to question your approach. That can seem scary at first, but being questioned on your approach does not mean you're wrong, but it allows you to open your mind to new and/or different ways in which you might approach issues in future. In turn, your answers may help serve those questioning you in their future projects.

*If you'd like to pair program while maintaining social distancing or while working remotely you can try pair programming software like Tuple or the VS code Liveshare extention.

Conclusion

Making small changes to the way you approach tasks when programming can make a monumental difference to readability and maintainability, both for yourself and others. Habits can be hard to break but your future self and your colleagues will probably thank you for it.

If you’ve found this article useful, please follow me on Medium, Dev.to and/ or Twitter.

DEV Community: Liam Hall

Exploring Typesafe design tokens in Tailwind 4

Changes in Tailwind 4

The move to a CSS config

What does this mean for Typesafety

What is the @property CSS rule

What are design tokens

Structuring component design tokens with Tailwind

Creating the tokens

Tailwind 4 config

System tokens

Component tokens

Using design tokens in components

Updating the Button component

Conclusion

Bluesky - Dev community

A different approach to writing component variants with Tailwind CSS

The problem

The limitations of Tailwind

Tackling the initial problem

What about CSS in JS?

How do CSS in JS libraries deal with this?

So how do we solve this?

Conclusion

Example: variableMap

What are higher order components and how to use them in Vue

What is a higher order component

When might we call for higher level component

Higher level components by example

Common configurations

Simple card example

Card

Article Card

Product Card

Article Card

Product Card

Conclusion

Understanding and Utilising TypeScript, by example

Primitives, Types, Interfaces and Enums, what are they?

Primitives

Types and Interfaces?

Types

Type basics by example

Interfaces

Interface basics by example

Enums

Naming conventions

Common conventions

Personal conventions

Singluar / Plural

Prefixes

Typescript by example

Conclusion

Getting started with Barebones components - A component library without design constraints built for Vue and Nuxt

Contents:

1. Backstory

2. The idea behind Barebones

3. How does Barebones work?

3.1. props.ts files

3.2. parts.ts files

3.3. Component parts

3.4. By example

3.4.1. Modular approach

3.4.2. Broad approach

4. Getting started

4.1.1. Yarn users

4.1.2. NPM users

4.2.1. Vue 3 users

4.2.2. Nuxt 3 users

4.3. Add local configuration files

5. Start building

6. Conclusion

Understanding Javascript imports and exports

Introduction

What is modularity in Javascript

Exporting from Javascript modules

Importing from Javascript modules

Importing a default export

Importing an individual data/ functionality

Importing and namespacing all individual data/functionality