Forem: MapleLeaf

TailwindCSS vs. UnoCSS

MapleLeaf — Mon, 01 May 2023 06:36:04 +0000

I’m a long time TailwindCSS user and a huge fan of utility CSS in general. I’ve rarely felt a strong need to switch, but UnoCSS has been on my mind for a bit. I got around to using it properly, so I thought it’d be fun to write up my thoughts on both in detail.

This article includes a lot of small nitpicky stuff that may not matter to others, but for me, the more I can reduce microfriction, the better.

Features

Tailwind has class names for pretty much every CSS feature you could think of, including some useful ones you may not know about, like isolation. Even for what’s missing, with arbitrary values, variants, and properties, most apps can be styled head-to-toe without a custom CSS file or plugins.

Uno supports all of Tailwind, plus some extras of the box that I really appreciate, like variant groups, fluid columns with CSS grid, and a lot more animations.

Uno also has an opt-in "attributify" transform, but I personally prefer my class names to stay in a single attribute separate from props. It's a neat idea though.

The Language

Tailwind has a reasonably well-defined language for class names:

Every style is a kebab-cased name, e.g. bg-blue-500, p-4
Classes can be prefixed with a variant, like md:, hover:
Arbitrary stuff is in [brackets] , with well-documented differences depending on the context

There's no spec per se, but I've found it's a very "guessable" system. Based on how other class names work, you try stuff like grid-cols-[4rem,1fr,auto] and it Just Works™️.

By contrast, Uno's default preset is regex all the way down. There’s no real “language” per-se, and there’s no standardization, e.g. m4 and m-4 both do the same thing.

This is intentional on Uno's part; Uno is all about flexibility. But I still prefer Tailwind's guardrails and opinionated methodology.

This point is somewhat moot since one would really just use Tailwind's language with Uno. That, and Uno probably works better as a framework to implement your own language on top of it. Regardless, this is my evaluation if I'm looking at it and its default preset as a userland tool for styling apps.

Documentation

Both docs sites are beautiful, well-written, and highly usable. But I want to give a special shoutout to Uno's interactive docs, and the accent color shifting is brilliant. Might steal that 🤭

Custom Styles

Here’s an example of a custom plugin in Tailwind:

// adds s-* utilities to apply both width and height
plugin(function size(api) {
  api.matchUtilities(
    { s: (value) => ({ width: value, height: value }) },
    { values: api.theme("width") },
  )
}),

Here’s (almost) the same in Uno:

// `s-*` classes to set width and height
[
  /^s-(\d+)$/,
  ([, size]) => ({
    width: `${Number(size) / 4}rem`,
    height: `${Number(size) / 4}rem`,
  }),
  { autocomplete: "s-<num>" },
],

For both of these, the class s-4 will give the styles width: 1rem; height: 1rem.

Tailwind’s plugin API has gotten a lot nicer over the years. Simple utilities are easy to add, and even more complex ones like in this example aren’t that bad either.

Uno makes heavy use of regex for dynamic utilities, which feels error-prone. Uno encourages defining utilities that can take whatever value you give it, which reduces the need for the [] arbitrary value syntax. But I still prefer how Tailwind limits you to a specific set of values.

Aside: Tailwind’s arbitrary value syntax also lets you use any value. But the docs, plus the syntax required to use it, discourages them from being used. I like the clear, enforced sentinel of “this does not exist in the design system”.
By contrast, Uno more or less encourages users to use whatever value they want. Although you technically could build a more constrained design system within Uno, that's more leaps than what you get with Tailwind.

Editor Support

Tailwind’s editor support works pretty well, but has some gaps:

No awareness of custom classes in CSS files
- It'll autocomplete classes in CSS with @apply, but it won't autocomplete custom classes from CSS in HTML
Does not autocomplete class names when using @apply in plugins
You need to configure an “experimental” option with custom regex to get completion contexts elsewhere, and you need to dig through issues and discussions to find the recipe you want. Which still may not work in all cases, because... y'know, Regex 🫠

These issues make it tedious to reuse styles, via @apply or with class name strings in JS.

Tailwind authors recommend against using @apply altogether, but I still find it useful for small atomic elements, like buttons, inputs, and links.

Uno highlights class names and gives color hints everywhere, which is nice if you’re sharing class names in standalone strings, but it is funny to see it highlight “transition” in const transition = useTransition().

By extension, Uno's editor support also works in uno.config.ts, which is very nice for adding custom reused class names.

Caveat: you have to add // @unocss-include at the top of the config file to get it to complete class names in it. This works fine with Remix and PostCSS, but it may break in other setups. TBH the plugin should support this OOTB

However, Uno’s autocomplete is finicky in some ways:

Often you don’t get options for autocomplete until you type a full utility and -
Shortcuts don’t always get autocompleted, and it’s not really clear why
Autocomplete inside a variant group e.g. hover:(|) doesn’t work unless you put a space in it, like hover:(| )

That aside, I've found Uno's overall editor experience more frictionless than with tailwind.

Tailwind and Uno have their strengths and weaknesses. I highly appreciate Tailwind’s constraints and clearer authoring language, but if you value flexibility and extra features, you’ll probably like Uno. Uno also has an overall nicer editor experience as of writing, but maybe that’ll change! I’ll be watching both of them closely. 👀

Honorable mentions:

MasterCSS: Didn't really draw me in. Doesn't seem to have a big focus on constraints at all, and its language doesn't feel very ergonomic
Twind: The editor plugin still isn't updated to work with the latest version
TypeWind (and similar): I greatly appreciate the effort to have good DX without an extra editor plugin, but TS-based class names are very unergonomic 😅

Trouble with useEffect running every render? `useEffectRef` to the rescue!

MapleLeaf — Thu, 21 Jan 2021 06:49:05 +0000

The problem

Here's the standard contrived Counter component, except I've added an onChange prop, so that the parent component can listen to when the count is updated.

function Counter({ onChange }) {
    const [count, setCount] = useState(0)

    useEffect(() => {
        onChange(count)
    }, [count, onChange])

    return (
        <>
            <p>{count}</p>
            <button onClick={() => setCount((c) => c + 1)}>+</button>
        </>
    )
}

If you use the react-hooks eslint rule, which is built into Create React App, you'll see that it tells you to add onChange and count to the dependency array.

Usually, the eslint rule is right, and abiding by it will help prevent bugs. But in practice, this can cause the effect to run on every render.

// every render, this callback function is a new, fresh value
// if a state update happens here, or higher up,
// the effect in `Counter` will run,
// and this alert gets called
// ...every update
<Counter onChange={(newCount) => alert(`new count: ${newCount}`)} />

No good! We only want to listen to changes, not all updates! 🙃

The solution

Before I continue, consider this a last resort. If you use this for lots of values, then your effects will miss some important updates, and you'll end up with a stale UI. Reserve this for things that change every render, which are usually callback props. For objects, this might work a lot better.

Anyway, here's my preferred solution, which I feel aligns well with the intended mindset of hooks.

import { useState, useEffect, useRef } from "react"

function Counter({ onChange }) {
    const [count, setCount] = useState(0)

    const onChangeRef = useRef(onChange)
    useEffect(() => {
        onChangeRef.current = onChange
    })

    useEffect(() => {
        onChangeRef.current(count)
    }, [count, onChangeRef])

    return (
        <>
            <p>{count}</p>
            <button onClick={() => setCount((c) => c + 1)}>+</button>
        </>
    )
}

This works because refs have free floating, mutable values. They can be changed without causing re-renders, and aren't a part of the reactive flow, like state and props are.

Effects run from top to bottom in the component. The first effect runs and updates onChangeRef.current to whatever callback we've been passed down. Then the second effect runs, and calls it.

You can package the above in a custom hook for reuse. It comes in handy, especially for callback props.

import { useState, useEffect, useRef } from "react"

function Counter({ onChange }) {
    const [count, setCount] = useState(0)

    const onChangeRef = useEffectRef(onChange)
    useEffect(() => {
        onChangeRef.current(count)
    }, [count, onChangeRef])

    return (
        <>
            <p>{count}</p>
            <button onClick={() => setCount((c) => c + 1)}>+</button>
        </>
    )
}

function useEffectRef(value) {
    const ref = useRef(value)
    useEffect(() => {
        ref.current = value
    })
    return ref
}

Note: the ESLint rule will tell you to add onChangeRef to the effect dependencies. Any component-scoped value used in an effect should be a dependency. Adding it isn't a problem in practice; it doesn't change, so it won't trigger re-renders.

Alternatives

Call the callback prop while updating the value

function Counter({ onChange }) {
    const [count, setCount] = useState(0)

    const handleClick = () => {
        setCount((c) => c + 1)
        onChange(c + 1)
    }

    return (
        <>
            <p>{count}</p>
            <button onClick={handleClick}>+</button>
        </>
    )
}

This works well in this contrived example, and this may even be better for your case!

However, let's say we add a minus button to this component. Then we have to remember to call the callback when that's clicked as well, and for any other potential case it updates. That, and notice we have to put the update logic twice (c + 1), due to the use of the callback prop. This is somewhat error-prone.

I find an effect is more future proof, and more clearly conveys the intent of "call onChange whenever count changes".

However, this path does let you avoid mucking around with refs, so it still makes for a good alternative. Just giving one more potential tool in the toolbox 🛠

`useCallback` on the parent

const handleChange = useCallback((count) => {
  alert(count)
}, [])

<Counter onChange={handleChange} />

This works, and is probably the "most correct" solution, but having to useCallback every time you want to pass a callback prop is unergonomic, and easy to forget.

`// eslint-disable-line`

This could cause future bugs if you need to add a new dependency and forget to. The rule is rarely wrong in practice, only ever if you're doing something weird, like a custom dependency array.

Indexing objects in TypeScript

MapleLeaf — Wed, 31 Jan 2018 01:22:36 +0000

This is a topic that comes up every now and again, so I figured it'd be useful to write a post about it.

Imagine you have code like this:

// an object defining how to display specific user statuses in the UI
const statusDisplays = {
  online: 'Online',
  offline: 'Offline',
  busy: 'Busy',
  dnd: 'Do Not Disturb',
}

// fetch the status of a user by their ID
const userStatus = getUserStatus(myUserID)

// get the displayed status text
const displayedStatus = statusDisplays[userStatus]

However, with strict mode enabled, the last line gives an interesting-looking error:

Element implicitly has an 'any' type because type '{ online: string; offline: string; busy: string; dnd: string; }' has no index signature.

...which looks like complete nonsense if you don't really know what's going on. So let's try to break it down.

Index Signatures

In TypeScript, in order to get an index off of an object, that object's type has to include an index signature on it. Index signatures are often used to define objects used as dictionaries, like the one we have here. An index signature type looks like this:

type Dictionary = { [index: string]: string }

Our object is inferred as the type { online: string; offline: string; busy: string; dnd: string; } and does not have an index signature included.

The reason for this is behavior to prevent runtime errors that come from indexing an object by unknown keys. Imagine the API we're using added a new status 'idle'. statusDisplays['idle'] would return undefined and error when we try to use it. Or worse, fail silently.

A straight-forward-ish solution

To solve that problem in JS, it's enough to check first if the key is valid, and TypeScript usually accomodates for these kinds of checks.

if (userStatus in statusDisplays) {
  statusDisplays[userStatus]
}

Unfortunately, this still produces the same error message, for reasons discussed here and in other similar issues.

Here's a way of getting around that using a helper function:

// `PropertyKey` is short for "string | number | symbol"
// since an object key can be any of those types, our key can too
// in TS 3.0+, putting just "string" raises an error
function hasKey<O>(obj: O, key: PropertyKey): key is keyof O {
  return key in obj
}

if (hasKey(statusDisplays, userStatus)) {
  statusDisplays[userStatus] // works fine!
}

This uses a few of interesting features you might not be aware of. Namely generics, keyof, and user-defined type guards.

We use a generic to infer the shape of the object being passed in, to use it in the return type. Here, the O parameter of hasKey is inferred as { online: string; offline: string; busy: string; dnd: string; }.

keyof is a keyword in TypeScript which accepts a given object type and returns a union type of its keys. These are equivalent:

type StatusKey = keyof { online: string; offline: string; busy: string; dnd: string; }
type StatusKey = 'online' | 'offline' | 'busy' | 'dnd'

Lastly, we use a type guard here to say that, if this function returns true, any further usage of key will be of the specified type. Otherwise, it's still just a string.

All of this works because TypeScript allows us to index any object as long as the index's type is a union of all the possible keys, so it knows that the key is valid. Maybe in the future, using key in obj will work on its own, but until then, the helper function works well enough.

If you have any questions or comments, specifically if I left anything out or if anything's unclear, feel free to leave them down below. Thanks for reading!

ES Modules: Default imports are not namespace imports!

MapleLeaf — Sun, 05 Nov 2017 09:24:54 +0000

Here we have two import statements:

import React from 'react'
import * as React from 'react'

I see both of them in a lot of written code, the former more often than the latter. They seem to accomplish the same result, but depending on a lot of factors, they can end up doing entirely different things. I wrote this to hopefully clear up the difference between the two, especially for those who might not be aware that there even is a difference.

Namespace imports

Namespace imports import all of the exported variables from a file under one name. For example:

// my-module.js
export const foo = 123
export const bar = 456

// main.js
import * as stuff from './my-module'

// stuff is: { foo: 123, bar: 456 }

Pretty simple, right? Not much more to explain here.

Default imports

On the other hand, default imports import a specific default export from another module. That is, the variable exported as export default in the imported module.

// my-module.js
export default {
  foo: 123,
  bar: 456,
}

// main.js
import stuff from './my-module'

// stuff is: { foo: 123, bar: 456 }

The purpose of default exports is to give an attractive interface for importing a single unit of functionality from another module: a single class, a single utility function, and so on. The default export is meant to promote the practice of single-responsibility modules.

A variable exported normally is tagged under its variable name. export const foo = 123 is exported under the name foo, and can be imported as foo.

The default export of a module is tagged literally under the name default. With that in mind, we could rewrite the previous example like this to achieve the same result:

// my-module.js
export const default = {
  foo: 123,
  bar: 456,
}

// main.js
import { default as stuff } from './my-module'

// stuff is: { foo: 123, bar: 456 }

Conclusion: defaults aren't a value magically hidden alongside the normal exports of a module. Defaults are just syntactic sugar built over what's already possible with normal exports.

However...

Default imports are not namespace imports

...and should not be treated as such. Example:

// my-module.js
export const foo = 123
export const bar = 456

// main.js
import stuff from './my-module'

The import statement is looking for a default export to use as stuff, but the module does not have anything exported as default. The script will fail, complaining that default could not be found in my-module.js.

...Except, if you've ever worked with babel, webpack, or other bundlers/transpilers, you'll know that it actually does work sometimes. Why?

Most modules are written in CommonJS, and because of this, transpilers and bundlers use various strategies to resolve the differences so you can seamlessly use different module systems together. The most common strategy is to take the module.exports object from the CommonJS module and treat that as the default export.

In short, in most build pipelines today, the previous example would work as you expect if my-module.js were written as a CommonJS module.

Addtitionally, transpilers add a special __esModule property to the module.exports object when transpiling from ES modules to CommonJS. This tells module loaders that the original module is written as an ES module, and is meant to be used as an ES module. So the module.exports to default strategy described only applies when the library is originally authored in CommonJS.

So then, how do I import React?

From the React repo:

export default React;

A lot of code in the wild uses a default export, so that appears to be what they went with here. I personally would've gone with a namespaced export myself given the structure of things, but it is what it is. Â¯\_(ãƒ„)_/Â¯

Conclusion

Know your modules' exports, know which module system it uses, and know whether there is or isn't a default export. Here's a good article on ES modules if you want to learn more.

If there's anything I missed, got wrong, or made unclear, feel free to leave a comment. This is my first article here, so feedback is greatly appreciated. Thanks.

Hi, I'm Darius

MapleLeaf — Tue, 13 Jun 2017 20:03:08 +0000

...a.k.a "just nobody", a.k.a left-pad

I'm 21, and have been coding for about eight years.

I live in Reynoldsburg, OH, and am unemployed (for now).

I mostly work with and am fluent in JavaScript (preferably TypeScript), Lua, and Dart.

I am currently learning more about everything in the frontend world, along with other languages and tech that catch my eye every now and again.

You can find me on Twitter as @kingdaro_

Nice to meet all of you wonderful people.