I was setting up this blog at the beginning of 2021 and excitedly told a few developer friends about the plan. The discussion naturally revolved around blogging platforms and tech choices, until one of them asked:

It's a great question. I wasn't sure about it, so I set up a rule for myself: write three complete posts before publishing the blog. It was a good decision, because it took almost a year to reach three blog posts. So, what took so long?

Turns out I wanted to code a bit more — at least in the beginning. I spent way too much time building an over-engineered React site, considering the goal was to write content. But so what? A hobby project should be inspiring and free of rules, not a KPI-driven piece of work. Unless that's your thing of course. For me, implementing the site from scratch felt like a necessary fuel for my writing inspiration. I didn't want to code everything just for the sake of it though. I'll try to explain.

For years, I've gone back and forth with different blogging platforms. Medium for a few testing-related posts, Blogger for macOS configuration posts, WordPress for a business website, Github repo with .md files, and many open-source solutions like Jekyll, Ghost, Hugo, and Hexo.

Let's talk about the hosted platforms first.

The goal of this blog is to share my thoughts and ideally help other people. To achieve that, there's no need to ask for users' locations, ask if they want to receive notifications via service workers, or anything like that. There's just the content in a minimal digital frame.

Talking about content — it should be accessible, searchable, open, and permanent. Not many hosted services share these ideologies. That's completely understandable because they have a business model to sustain.

What about open source solutions?

Self-hosted open source blogging tools are very polished and felt tempting, but I had a feeling that hacking existing solutions wasn't interesting enough.

The content I want to share is tightly related to code and my vision is to make the posts interactive, visual, and understandable. I'm thinking:

If I start a blog, the platform shouldn't come in the way of expressing ideas.

In addition to the subjective arguments and feelings, I gathered a list of other requirements:

• Custom domain
• Permanent URLs for posts (10+ years)
• Technically flexible for possible crazy ideas in the future: code highlighting, SVG animations, interactive charts, and any custom components that help understanding concepts
• Content should be readable without JavaScript

I wanted to write, but also see what kind of page I can put together. So DIY it was. It felt like the most interesting and fun approach. Since the posts would have dynamic components and visualisations, I chose React and MDX. They were familiar tools.

If you've agreed with my decisions until this point, that's nice! However, reinventing the wheel is only about to start.

Lately, I've been obsessed with web performance. It's starting to get normal for a website to download 15 MB of uncompressed files to display simple information. I wanted to make this site as minimal in size as possible (sidenote: perf score suffers from tiny CI instances) while considering the vision of interactive and dynamic content.

After a lot of initial hesitation between do-it-yourself or npm i gatsby, I started implementing a Gatsby-like static site generator. It sounded like a huge time sink but I wanted to know how minimal it can get. The benefits of a custom static site generator compared to Gatsby would be most probably microscopical, but why not? This project was supposed to be an inspiring and fun project after all!

While crossing the implementation finish line, I realised that the content isn't just the last 10% — it's the last 95%. The realisation killed my writing motivation for a while. There weren't any CSS transitions to tweak anymore, just the half-written blog posts waiting. But when days go by, more and more thoughts are bubbling up. Now I finally have the domain, tech stack, repository, and existing .mdx files craving to get some juicy content.

This is Part I of a series where we'll look into how kimmo.blog works. Part I covers SSR and static site basics. If you are familiar with the topic, feel free to jump into Part II: Module bundling.

Motivation has been covered in Writing, or coding.

Disclaimers

Gatsby is a production-ready tool that has everything you need: customisable data sources accessed via GraphQL, optimised build pipeline, functionality via plugins, and a huge community.

The build system that we'll go through on the other hand is experimental and doesn't even have frontend routing. Building a better Gatsby is not the point. Instead, we want to understand how it works and possibly make the site's bundle footprint even smaller.

That out of the way, let's jump into building the thing.

Static site rendering

The high-level idea is pretty straightforward: convert a bunch of source files and content to a static site in output/ directory.

We "simply" need to implement the Build pipeline box in the middle.

One way to start figuring out a system is from the user's perspective. Let's imagine there's a file server that serves everything under output/ directory.

When a user loads /posts/ path in their browser, the server responds with the contents of output/posts/index.html file. The contents have been created with Node.js using React:

import ReactDOMServer from "react-dom/server";
import { AllPostsPage } from "./pages/AllPosts";

ReactDOMServer.renderToString(<AllPostsPage />);

This type of React usage is often called server-side rendering – regardless of where the rendering technically took place. renderToString() might've been called on your local machine, Netlify's build servers, or per request on a Node.js server.

Why do we even need this step? React apps work just fine even if the backend sends an empty <div id="react-root"></div> container.

That's true. Server-side rendering is not mandatory, but it has some benefits. It'll make the content load faster, more SEO friendly, and accessible even when JS has been disabled.

That covers the read-only content, but for richer interaction, we need to generate a JS bundle that kicks off the dynamism browser-side. The traditional way would be to render HTML directly from e.g. Markdown, and JS would refer to the existing DOM elements via query selectors:

const elements = document.querySelectorAll('.chart');
initCharts(elements);

There are many benefits to the traditional model, no doubt about it. However, it's missing some of the ergonomics we get from React — for example, component separation and state handling. Anyways, arguing about whether using React in this context makes sense is not the topic of this post.

Building on top of the previous example, let's add a JS bundle called hydrate.js to the page. It uses ReactDOM.hydrate() to continue where the server-side rendered React left off:

import React from "react";
import ReactDOM from "react-dom";
import { AllPostsPage } from "./pages/AllPosts";

window.addEventListener("load", () => {
  ReactDOM.hydrate(
    <AllPostsPage />,
    document.getElementById('react-root')
  );
});

The DOM stays untouched (<h1>All posts</h1>, etc), but React starts event listeners to allow user interaction on the page.

That's how server-side rendering works. Backend returns a frozen snapshot of a React component and frontend brings it back to life.

There are benefits, but definitely some downsides too. First of all, the rendering flow is very complex compared to a single page app. Another annoyance is that most component code paths will be run on Node.js too. Many frontend libraries throw ReferenceError: window is not defined because they weren't designed to be run in a windowless environment. That means you'll have one more scenario to test.

SPA vs static site

In single page apps, the server is usually configured to send the same index.html with an empty <div id="react-root" /> container for any request path. JavaScript would then read window.location and decide which page content to render based on the frontend routing. But we don't want that, because it will inevitably be at least a little bit slower than the server-side rendered content at page load.

In static sites, each page needs to be able to independently bootstrap the JavaScript UI. In other words, static sites can have multiple entrypoints into the application.

I wouldn't say there's a clear winner, just different approaches with varying pros and cons. Also, I'm going to conveniently just skip the fact that the custom build system doesn't support frontend routing. That will make navigation after the initial page load slightly slower than in SPAs. It was a shortcut that I took to make the setup less complex. Hats off to Gatsby for actually managing the complexity.

That's static site rendering basics. There's a ton of details that still need to be solved though. In Part II, we'll look into code specifics and module bundling with Rollup.

This is Part II of a series where we'll look into how kimmo.blog works. Part II focuses on how Rollup, custom glue code, and templates are used to convert source files into pages that work in all browsers.

Motivation has been covered in Writing, or coding.

Module bundler

We need a way to convert .tsx source files into JS bundles. TypeScript compiler does the job in simple cases, but we want a full-blown module bundler. Why? Because module bundler is able to handle also other tasks required to build a fast production site: tree shaking, bundle splitting, import aliases, process.env replacements, etc.

I looked into Webpack, Snowpack, Parcel, Rollup, and Babel. They all have slightly different abstraction levels and philosophies, but Rollup was my choice for the task. Its configuration format is simple and the core is very minimal. Rollup allows precise low-level control over the bundling process.

More control usually equals more work. Rollup is no exception. Most tasks that Webpack and other bundlers do by default, need a plugin in Rollup. The explicit configuration and minimal core force you to think about details though.

If a dependency uses Node.js core library such as crypto, do you want to polyfill it?

It sounds tedious, but on the other hand it makes you very aware of what's happening under the hood. The payoff is increased understanding of the build process and most probably a smaller bundle size.

This is how the simplified rollup.config.js for this blog looks like:

export default {
  // Use tmp dir as a workaround. Ideally the output dir
  // would be modified in-place, but that didn't work with
  // Rollup for some reason.
  input: ["output-tmp-rollup/**/*.tsx", "output-tmp-rollup/**/*.ts"],
  output: {
    dir: "output",
    format: "esm",  // Use ES6 modules
  },
  plugins: [
    multiInput({
      // Keeps the output directory structure same as input
      relative: "output-tmp-rollup/",
    }),
    nodeResolve(),  // Allow importing under node_modules
    commonjs(),     // Required for dependencies using commonjs
    json(),         // Allow import data from './data.json'
    typescript(),
  ],
};

Task runner

Rollup solves many complicated problems for us, but we also need a task runner to combine different tools together. There's no clear line between a module bundler and a task runner though. Grunt or Gulp used to be the de-facto task runners, but Webpack has taken over that territory too in many projects.

For this project though, I'm going to stick with my favorite approach: CLI tools and bash commands. For example HTML validation can be done with:

find ./output/ -name '*.html' html-validate {} +

The ultimate feature of the approach is that build commands can be copy-pasted to your terminal and easily debugged in steps. The commands tend to get very long, but I don't see that as a huge issue in reality. Long commands can be refactored into separate script files if needed and they focus on doing a single thing well. Bash commands usually operate with regular files, so that's the abstraction you'll mostly need to deal with.

It might get tricky if PowerShell or cmd.exe support is required, but there are tools that make it possible. I created concurrently and chokidar-cli to help with the cross-platform setup. There are also other great tools such as npm-run-all, dotenv, and onchange.

This is the stripped-down version of package.json scripts:

{
  // ... in package.json
  "scripts": {
    "build": "npm run render && npm run rollup",
    "rollup": "rollup -c rollup.config.js",
    "render": "ts-node src/generator/render.tsx",
    // ... many more, such as PostCSS, linter, etc
  }
}

Custom code & templates

We've chosen Rollup for module bundling, and npm run scripts to combine tools together. Next, we'll need custom code that iterates through all React pages and generates their static HTML counterparts. Many details such as rendering MDX pages will be omitted to stick with the topic of Part II.

Everything starts from src/generator/render.tsx. Rendering has many steps, but these are the relevant ones:

• Find all entrypoints (i.e. the site pages)
• Iterate through entrypoints and render the page templates
• Save metadata for entrypoints in site-data.json

Let's break the steps down.

1. Find entrypoints

The entrypoints for React page components and their metadata are defined in src/pages/_exports.ts. Here's a simplified version of it:

import { getData as getIndexData, default as Index } from "./Index";
import { getData as getPostsData, default as Posts } from "./Posts";

export const pages = [
  {
    // Async function in case a page needs to
    // fetch external data.
    // Each page has to return title, path, description, etc.
    getData: getIndexData,
    Component: Index,
    // Referred in pageHydrate.tsx:
    // import PageComponent from "src/pages/{{{ fileName }}}";
    fileName: "Index",
  },
  {
    getData: getPostsData,
    Component: Posts,
    fileName: "Posts",
  },
];

The list contains all React pages, and which path to serve them from. React page means that the source is a regular React component contrary to e.g. .mdx blog post pages.

2. Iterate all pages

For each page in the entrypoints, do the following operations:

Call renderToString() to render the React page component as HTML.

const html = ReactDOMServer.renderToString(
  <page.Component pageData={pageData} siteData={siteData} />
);

Render page.html.template with page components's HTML and other metadata. Again, simplified:

<html>
  <head>
    <title>{{{ title }}}</title>
    <meta name="description" content="{{{ description }}}"/>
    <meta name="keywords" content="{{{ keywords }}}"/>

    <link defer rel="stylesheet" href="{{{ relativePathToRoot }}}styles.css"/>
  </head>
  <body>
    <div id="react-root">{{{ html }}}</div>
    <script type="module" src="{{{ hydrateScriptPath }}}"></script>
  </body>
</html>

Render the page-specific hydrate.tsx using pageHydrate.tsx.template. The templates are Mustache-like templates, but with triple braces to avoid conflicts with objectProp={{ key: "val" }} React props.

import React from "react";
import ReactDOM from "react-dom";
import siteData from "site-data.json";
// Will be replaced with e.g. "src/components/pages/Posts"
import PageComponent from "{{{ pageImportPath }}}";

// Will be replaced with e.g. "/posts/"
const pagePath = "{{{ pagePath }}}";
// Not the best data structure..
// good thing I don't have 10k blog posts
const page = siteData.pages.find((page) => page.data.path === pagePath);

window.addEventListener("load", () => {
  ReactDOM.hydrate(
    <PageComponent pageData={page.data} siteData={siteData} />,
    document.getElementById("react-root")
  );
});

The hydration script will be first saved as a TypeScript file to output-tmp-rollup/<page>/hydrate.tsx. The render script keeps the directory structure correct, so it matches the paths defined in pages' metadata. The output-tmp-rollup/**/*.tsx will finally be passed to Rollup, which outputs corresponding output/**/*.js files.

3. Save metadata to site-data.json

As seen in pageHydrate.tsx.template, site-wide data is imported from site-data.json. The data is used to for example render a list of all posts. The JSON data is saved in a single file, that can be cached and shared by all pages in the site.

import fs from "fs";
import { pages } from "src/pages/_exports";

const siteData = await mapAsync(pages, (page) => page.getData());
await fs.promises.writeFile(JSON.stringify(siteData), "site-data.json", {
  encoding: "utf-8"
});

Putting everything together

With these building blocks, we are able to convert React pages into static HTML counterparts. To recap, npm run build will:

1. Render all pages with src/generator/render.tsx
2. Run Rollup to transpile output-tmp-rollup/**/*.tsx files into output/**/*.js
3. Execute other build steps (copy static files, PostCSS, etc)

The build flow is simple in theory, but there are a huge amount of details that end up making the process complicated.

This is Part III of a series where we'll look into how kimmo.blog works. Part III covers MDX rendering.

Motivation has been covered in Writing, or coding.

What is MDX

MDX is an amazing markup format. It allows familiar authoring experience using markdown syntax – with the capability of adding custom React components along with the text.

For example this source

**Here's** an _example_ of a [toast](https://ux.stackexchange.com/questions/11998/what-is-a-toast-notification):

<ButtonLink onClick={() => info('This is amazing!')}>Spawn a toast</ButtonLink>

would render:

Here's an example of a toast:

All this could be achieved with good old React components, but it's just not as smooth of a writing experience. Paragraphs would need to be wrapped in <p> elements, links would become cumbersome to type, and blah.

Writing blog posts in React would make the site generator simpler, but we're already on the over-engineering train so let's continue.

How MDX works

While MDX is an incredible authoring experience, it comes at the price of complexity when done right. By right, I mean with good performance.

It is possible to greatly simplify the rendering, if performance is not a concern. MDX text could be sent as a raw string to the browser and it would do the heavy rendering with e.g. @mdx-js/runtime. It would make the build pipeline simpler, but other aspects worse:

"warning: this is not the preferred way to use MDX since it introduces a substantial amount of overhead and dramatically increases bundle sizes. It must not be used with user input that isn’t sandboxed."

This blog uses next-mdx-remote library to deal with MDX rendering. It's been designed for Next.js, but it also works well for our use case.

To speed things up in the browser, next-mdx-remote compiles the MDX to minified JavaScript server-side. The serialize method does this using @mdx-js/mdx and esbuild under the hood.

This is how the previous example would be serialized:

import { serialize } from "next-mdx-remote/serialize";

const content = `
**Here's** an _example_ of a [toast](https://ux.stackexchange.com/questions/11998/what-is-a-toast-notification):

<ButtonLink onClick={() => info('This is amazing!')}>Spawn a toast</ButtonLink>
`;

const { compiledSource } = await serialize(content);

The compiledSource is a string that contains the compiled JavaScript. Here's the code unminified and simplified:

function MDXContent(n) {
  var e = n,
    {
      components: o
    } = e,
    t = m(e, ["components"]);
  return mdx(MDXLayout, c(a(a({}, layoutProps), t), {
    components: o,
    mdxType: "MDXLayout"
  }), mdx("p", null, mdx("strong", {
    parentName: "p"
  }, "Here's"), " an ", mdx("em", {
    parentName: "p"
  }, "example"), " of a ", mdx("a", a({
    parentName: "p"
  }, {
    href: "https://ux.stackexchange.com/questions/11998/what-is-a-toast-notification"
  }), "a toast"), ":"), mdx(ButtonLink, {
    onClick: () => info("This is amazing!"),
    mdxType: "ButtonLink"
  }, "Spawn a toast"))
}

In the browser, next-mdx-remote evals the code with Reflect.construct(), and renders the MDXContent:

<MDX.MDXProvider components={components}>
  <MDXContent />
</MDX.MDXProvider>

How the blog renders posts

The high-level flow of rendering .mdx pages is similar to React pages, but has more steps:

• Find all .mdx blog posts
• For each blog post:
  • Parse metadata from front matter
  • Render PostPage.tsx.template
  • Render pageHydrate.tsx.template
  • Render page.html.template with the HTML generated from MDX and other metadata
  • Save a compiledSource.txt file which contains the MDX content as minified JavaScript.

We'll soon understand why .txt extension is used. Let's go through the templates one by one.

PostPage.tsx.template

The template looks like this:

import { PostLayout } from "src/components/PostLayout";
import { MDXRemote } from "src/components/MDXRemote";
// Will be replaced with "./compiledSource.txt"
import compiledSource from "{{{ compiledSourcePath }}}";

export default function PageComponent(props) {
  return (
    <PostLayout siteData={props.siteData} data={props.pageData}>
      <MDXRemote compiledSource={compiledSource} />
    </PostLayout>
  );
}

The purpose of the rendered file is to represent the React component for a blog post page. The template will be rendered to a verbosely named file: output/posts/<slug>/<slug>-post.tsx.

It's easier to debug the build process when unique names are used instead of tens of "post.tsx" files.

pageHydrate.tsx.template

The same template that we used to render React pages in Part II. In React pages, the import refers to a page component in the source code.

import PageComponent from "src/pages/NotFound404";

With MDX pages on the other hand, the PageComponent is imported from the dynamically rendered post page file:

import PageComponent from "./1-writing-or-coding-post";

The template is saved to output/posts/<slug>/<slug>-post-hydrate.tsx.

page.html.template

Again, the same template as for React pages. The MDX content will be rendered as HTML in <body>. Blog post title, description, and tags from the front matter are rendered into <head>:

<html>
  <head>
    <title>Writing, or coding - kimmo.blog</title>
    <meta name="description" content="Do I want to write content, or do I want to code a blog?" />
    <meta name="keywords" content="meta,blog,content creation" />
  </head>
  <body>
    <div id="react-root"><!-- MDX blog page as HTML --></div>
    <script type="module" src="./1-writing-or-coding-post-hydrate.js"></script>
  </body>
</html>

compiledSource.txt

As mentioned, this file contains the MDX as minified JavaScript.

Why does it have a .txt extension then?

We need to be able to transfer the code exactly as-is to the browser, so that it can be passed as a string to MDXRemote. A good way to do this is using a rollup string plugin. The plugin has been configured so that a TypeScript code can import any .txt file, and the exact contents will be assigned to a variable.

This functionality used to be just a simple text replacement directly into code, but that broke with special characters and line breaks.

To recap

Each .mdx blog post file ends up creating quite some files in the output directory. First TypeScript files and compileSource.txt are rendered, then Rollup transpiles the source code into JS bundles, and finally static assets are copied.

This is Part IV of a series where we'll look into how kimmo.blog works. Part IV focuses on the pros and cons of the DIY build system.

Motivation has been covered in Writing, or coding.

DIY vs Gatsby

The disclaimers in Part I briefly mentioned this already, but it's worth recapping. Gatsby is a production-ready tool and in this series we built only a part of it.

Let's look at a classic feature comparison table.

The DIY solution has a similar core functionality, but lacks in some areas. Nevertheless, the tool works and successfully builds this blog in a similar way Gatsby would. The solutions are similar, but it's not a direct comparison.

Let's go through the good and the bad.

Good #1: Technical simplicity

My thoughts are inevitably biased because I've incrementally gathered knowledge of the system while developing the blog. Knowing that I'd still claim that the build system is pretty simple considering how much it does.

The simplicity has been achieved by keeping the number of abstraction levels to a minimum. A few examples:

• Build steps operate on directories and files
• Each build step is a narrowly scoped CLI command
• ES6 modules are leveraged to keep bundling simple

Part of the minimalism can be attributed to the lack of varying use cases. Gatsby supports thousands of use cases, while the custom-tailored tooling caters just this blog.

Something to keep in mind is that simple doesn't equal easy. While the tooling is simple, it doesn't automatically mean a better choice for a new website. The lack of documentation and community around the tooling would likely total to a net negative in comparison to widely used tools like Gatsby or react-static.

Good #2: No GraphQL in simple workflows

Some simple tasks are overly complicated to achieve in Gatsby. The reason for that in my opinion is the GraphQL layer. It's applicable when fetching more complex data from a content management system but not so much for retrieving local .mdx files.

The documentation for using MDX content in Gatsby starts with configuring the gatsby-source-filesystem plugin. After that, you'll spend time reading the documentation for accessing the file system via GraphQL queries. It's not a very common pattern after all.

With the DIY system, you access the files as you'd normally do:

const files = await glob("posts/*.mdx");
const promises = files.map((name) =>
  fs.promises.readFile(name, {
    encoding: 'utf8'
  })
);
const contents = await Promise.all(promises);

The argument might not be a fair one, since it's completely understandable why Gatsby does this. They rely on GraphQL as the single tech for accessing data. It's a smart choice for the average use case — accessing data from varying sources.

Good #3: Skipping an abstraction layer

Gatsby has over 2500 plugins. Many of them are tremendous and greatly simplify otherwise complicated workflows. For example gatsby-plugin-image adds responsive images automatically on your website.

The downside of plugins is that they introduce an unnecessary Gatsby-specific abstraction on top of the original problem. For example, markdown processing is already complicated enough with remark and unified, but Gatsby makes it even more complicated with its own set of plugins.

Even in a Gatsby project, I prefer to solve some problems natively instead of using a plugin. For example, it might be simpler to just add a favicon.svg in the static directory, instead of using a plugin for that.

In the DIY setup, we skip an abstraction layer. The code directly uses rss, remark, and other libraries. There's no plugin API or configuration format in the middle to learn.

Good #4: Rollup bundling

By leveraging Rollup and ES6 modules, the bundling becomes intuitive. Instead of a single large bundle.js, source code and its dependencies are bundled into separate cacheable files.

ES6 modules are used in the development environment as well as in the production site. Because this is a developer-focused blog, I can just ignore the browsers that don't support ESM.

The screenshots below show which JS files are loaded for kimmo.blog in comparison to Gatsby starter blog.

kimmo.blog

Gatsby starter blog

Although the starter blog doesn't have many components, Gatsby uses Webpack to bundle components into a few different bundles. This process leads to fewer individual JS files but makes the bundles quite cryptic. Gatsby's documentation explains how bundles are formed in great detail.

The DIY version on the other hand has a predictable mapping from source code to built version of the site:

• PostSummary.tsx
  →
  /PostSummary.js
• Button.tsx
  →
  /Button.js
• import _ from "lodash"
  →
  /node_modules/lodash.js

Simple and intuitive.

The bundling is achieved with Rollup's manual bundle chunking. The /node_modules/ directory is not a valid npm-usable directory, but just a regular directory that groups bundles of external dependencies under a familiar name.

Bundling modules in the described way has an awesome side-effect: the network panel can be directly used as to see which dependencies weigh the most. No need for an external bundle analyzer tool.

It would be fair to question whether this actually matters. Production bundles are anyways going to be minified and optimizing software distributables should be a higher priority than developer convenience in the production environment. I'd have to agree. But still, if it's possible to get equal performance with a simpler solution, I'll take it!

One big reason is that ES6 modules are a fairly new standard: initial browser support landed in 2017. Fortunately, the tools are improving every day. Snowpack uses ESM exclusively and many frontend libraries in npm are shipping only the ESM bundles for their latest versions.

Another reason may be that the approach used to be a performance killer in HTTP/1.1. However, nowadays doing multiple requests is just fine! Multiplexing in HTTP/2 solved the network bottleneck.

There's one more possible reason that will be covered in "Bad #5: Chaining requests at page load".

Bad #1: Messy architectural boundaries

Gatsby as a framework provides boundaries and a well-defined API. There's a strict border between your application code and the framework code.

The same cannot be said from the DIY approach. As much as I tried to keep the boundaries clear, the blog code knows too much about the supposedly generic site generator and vice-versa.

Bad #2: Onboarding experience

Let's say you'd have to onboard a new developer into a website project. Would you rather guide them to read Gatsby's documentation or spend days explaining how a custom system works?

I think we both know the answer. There's even a good chance that a new developer would already have experience with Gatsby.

Bad #3: Everything consumes time

While writing a script that generates an RSS feed is fairly straightforward, it takes development time. Small tasks add up. A bunch of time is wasted building mundane supporting functionality, instead of the actual website.

In the do-it-yourself approach, you'll gain a deep understanding of each little part of the build tool. It's likely to be useful knowledge even in the following projects, but unfortunately, it doesn't remove the maintenance burden later. The DIY solution has no public issue discussion, let alone contributors opening PRs that help the whole community.

Bad #4: Slow iteration

The downside of simplicity is slowness. Many other build systems leverage caching, in-memory data structures, and complex abstractions to improve performance. Since the DIY approach opted for simpler abstractions, the cost is sluggish iteration during development.

The file-based build pipeline could be improved in the future, but at the time of writing, it took around 8 seconds from a code change to seeing it in the browser. That's a tad too much.

Bad #5: Chaining requests at page load

While the Rollup ESM setup is a pleasant development experience, there's a downside. Using imports causes request chaining in the critical render path. The browser needs to do multiple request-response round trips to fetch all relevant files in the module tree. For example:

Browser loads index.html (1) which refers to a JS module.

<script type="module" src="./hydrate.js"></script>

Browser requests hydrate.js (2) from the server and parses the file. There's a new import inside.

import App from "./app.js"

Browser requests app.js (3) from the server. There's yet another import.

import PostsPage from "./pages/Posts.js"  // (4)

This continues until we've reached the final leaf module in the import tree.

The example had 4 round-trips between the browser and the server. The process is slow and web performance tools often complain about chaining requests for a reason. I'm not sure what the real fix would be but maybe import maps will help in the future.

If you know of a solution, I'd be curious to hear about it!

Conclusion

Let's summarize the arguments above.

Good:

• Technical simplicity
• No GraphQL for simple workflows
• Skipping an abstraction layer
• Rollup bundling

Bad:

• Messy architectural boundaries
• Onboarding experience
• Everything consumes time
• Slow iteration during development
• Chaining requests at page load

The final site builds ended up being quite similar in size. Gatsby wins in end-user performance by a small margin since it supports frontend routing. The routing allows faster page changes after the initial load.

So, what were the key takeaways?

For me, building a site generator was definitely worth it. I learned about ES6 modules, Gatsby, web performance, and much more. It also supported my goals for the blog and proved to be an enjoyable coding exercise.

For a professional project, I'd definitely recommend adopting more widely used tools like Gatsby or react-static.

Sometimes the goal itself is to walk the unbeaten path. I'll let you decide if that's the case or not.

This post is about implementing utilities for the ultimate Tailwind-React ergonomics and typings for it.

In the process, we'll learn about most of the advanced TypeScript features including complex conditionals, template literals, and recursive types. The typings are demonstrated via React components, but the final solution would work in any TypeScript project.

To get an idea what we're building, you can check out the final monstrous typings in a Replit project:

• Typings and classnames utility
• Example usage in components

You need to fork the repl if you want to enable TypeScript IntelliSense. Note that the typing hints appear slower in the online environment compared to a local setup.

Quick intro to Tailwind

Tailwind's website has an accurate pitch that describes its purpose well:

A utility-first CSS framework packed with classes like flex, pt-4, text-center and rotate-90 that can be composed to build any design, directly in your markup.

If you're sceptical about Tailwind in general, I suggest reading CSS Utility Classes and "Separation of Concerns" by Adam Wathan. Anyways, Tailwind produces plain CSS, everything is customisable via the config file, and its public API is the class names.

Constraints

There are a few constraints that affect the shape of our solution. The first constraint is about string concatenation. Using Tailwind in dynamic components, such as in React, has one vital rule.

It is important to avoid dynamically creating class strings in your templates with string concatenation, otherwise PurgeCSS won't know to preserve those classes.

In other words, don't do this:

<p className={`text-${color}`}>Hello!</p>

When doing string concatenation, Tailwind doesn't know which specific text- color classes to include in the CSS build. It uses a regex to find complete strings from the source code to detect which Tailwind classes are actually used in the project. Using the information, Tailwind can purge unnecessary CSS.

You can configure a static list of regex class name patterns that Tailwind will leave to the final build, but it easily leads to bloated CSS.

Purging is important, because there are a huge amount of possible class names. It might be a bit surprising, but there are actually tens of thousands of class names in Tailwind by default. Unpurged output.css from Tailwind can weigh even 8MB (unminified, uncompressed).

It sounds scary, but in reality your application will use only a fraction of them. Maybe a few thousands at maximum, which totals to some 10kB.

The second constraint is that Tailwind class names have equal specificity. You can't override previously written class names as you might intuitively expect:

<button className="rounded p-4 flex p-0">Ok</button>

In the above example p-0 does not override p-4. Whichever class is defined first in Tailwind's output.css wins. That's how CSS works in general. Another example for a real use case:

// Doesn't work. Background color and hover effect
// can't be changed by appending new classes to the end.
const baseCls = "rounded p-4 bg-primary hover:cursor-pointer"
const disabledCls = "bg-gray-200 hover:cursor-not-allowed"

const finalCls = `
  ${baseCls}
  ${props.disabled ? disabledCls : ''}
`;


// Do this instead.
const baseCls = "rounded p-4"
const primaryCls = "bg-primary hover:cursor-pointer"
const disabledCls = "bg-gray-200 hover:cursor-not-allowed"

const finalCls = `
  ${baseCls}
  ${props.disabled
    ? disabledCls
    : primaryCls
   }
`;

Here's a GitHub issue discussion about this commonly appearing topic.

Now that we know these limitations, the following decisions make more sense.

The desired result

It sounds like a trivial task: simply add Tailwind class names to className prop. Well, it actually is if you are happy with the ergonomics, but we are aiming pretty high here (read: over engineering). Achieving a great developer experience with a clean, readable, and type-safe solution with all the above constraints in mind does require some thinking.

There are multiple ways to dynamically format className strings, but to me classnames provides the perfect balance of readability and convenience. It's great as is, but there's nothing guarding you from typos or using Tailwind class names that were purged for some reason.

What we want is classnames, but with strict typings. Let's call this new more strict function cn.

import classnames from 'classnames'

// TODO: Implement typings
const cn = (...args: Todo) => classnames(...args)

After implementing the types, we should be able to catch all the incorrect calls at type-level. The API of classnames is flexible, let's look at the different possibilities we need to be able to handle.

Regular class name string.

const Hello = () => {
  // typo in regular string
  return <p className={cn(`text-grau-100 bg-white`)}>
    Hello!
  </p>
}

An array of class name strings.

type Props = { disabled?: boolean }

const Hello2 = ({ disabled }: Props) => {
  return <p className={cn([
    'flex my-5',
    // typo in a string in the array format
    `text-grau-800 bg-white`,
    disabled ? 'bg-gray-300 cursor-not-allowed' : ''
  ])}>
    Hello!
  </p>
}

An object where each key is a string of class names.

type Props = { dense?: boolean }

const Hello3 = ({ dense = false }: ) => {
  return <p className={cn(`text-gray-800 bg-white`, {
    // typo in object key format
    'px-asd2 py-1 my-2': dense,
    // try this:
    // 'px-2 py-1 my-2': dense,
    'px-3 py-2 my-3': !dense,
  })}>
    Hello!
  </p>
}

A combination of multi-line class name string and object format.

type Props = { dense?: boolean }

const Hello4 = ({ dense = false }: Props) => {
  return <p
    // long class name definition with a typo.
    // note the leading and trailing spaces
    // on each line
    className={cn(`
      flexxx
      text-gray-800 bg-white
      hover:text-gray-900
      hover:border-b-2
    `, {
      'px-1 py-3 my-4': dense,
      'px-2 py-4 my-6': !dense
    })}
  >
    Hello!
  </p>
}

If we were able to raise type errors for all the cases, that'd be the holy grail. Sleeves up!

Implementation

It might look just moderately complex to type the classnames API, but it gets tough. Chewing the complexity into smaller pieces helps. The individual pieces we need for the typings are:

1. Type containing all valid Tailwind class names. For example type ClassName = 'p-1' | 'p-2' | 'etc'.
2. Type that trims leading and trailing whitespace of strings.
3. Error message type that shows which is the offending token. For example 'flexxx' is not a valid Tailwind class.
4. A way to split the whole className string into word tokens and validate them against ClassName.
5. Support for a class name string
6. Support for the object format
7. Support for the array format

Let's cover them one by one, and tie it all together in the end.

1. Tailwind class names

There's a few different routes for generating a union type out of all class names. One solution would be to use the ability to expand template literal type unions:

type ColorName = 'red' | 'purple' | 'blue' | 'green'
type Luminance = 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
type Color = `${ColorName}-${Luminance}`
type Layout = 'block' | 'flex' | 'grid' | 'inline-block'

// Expands to all possible class names
type ClassName = Layout | `text-${Color}` | `bg-${Color}`

But it's a lot of work and the typings would need to be generated based on tailwind.config.js. In addition, it would lead to a huge union type with more than 60 000 unique string literals.

Instead of template literal expansion, I found that postcss-ts-classnames works well. It parses the output of PostCSS, exctracts all class names, and writes the union type of them to a d.ts file.

The result is a robust typing, that doesn't care about Tailwind's configuration or purging. It accurately captures all the class names your project has.

A downside is that we introduce a small lag to the development cycle:

• A new valid Tailwind class name is taken into use
• For a short while, IDE complains about the class not being valid
• PostCSS build is ran, which re-generates the d.ts types
• IDE does a TypeScript refresh, and the error is gone

That said, the lag isn't a big issue in reality. The union type performs well enough even if your project happens to use a few thousand unique class names.

Now we have tailwindClassNames.d.ts which contains a union type of all valid class names:

type ClassName =
  | 'block'
  | 'inline-block'
  | 'flex'
  | 'grid'
  | 'bg-gray-100'
  | 'p-1'
  // ... a thousand more

2. Trimming whitespace

For this trick, we'll use inference with template literals, conditional types, and type recursion. To get started, here's the generously commented TrimStart utility that deals with the leading whitespace.

// Newlines occur in multiline strings with backtick quotes
type Whitespace = ' ' | '\n'

// `extends string` validates that the
// type argument `T` is a string
type TrimStart<T extends string> =
  // Is `T` in format: ` ${Tail}` or `\n${Tail}`?
  T extends `${Whitespace}${infer Tail}`
    // Yes. Recursively call this utility again,
    // because Tail might contain new leading
    // whitespace.
    ? TrimStart<Tail>
    // No. Stop recursion.
    : T

TrimStart loops recursively until it has "eaten" all the whitespace characters from the beginning. You could think it as a while-loop, but done with recursion.

while (str.startsWith(' ') || str.startsWith('\n')) {
  str = str.substring(1)
}

In each iteration of the recursive loop, only one whitespace character is consumed at a time. This happens because in the conditional, the type argument T needs to exactly match the template `${Whitespace}${infer Tail}`. Since Whitespace can only be 1 character long (' ' or '\n'), it consumes a single whitespace character at a time.

Here's a few example results (TypeScript playground).

// type Result1 = "A"
type Result1 = TrimStart<'  \n A'>
// type Result2 = "A  "
type Result2 = TrimStart<'   A  '>

It's a neat trick, but there is a maximum type instantiation depth limit in TypeScript which limits the recursion depth. It is possible to hit the limit when trying to trim a string with very long leading whitespace.

Fortunately, there's an optimization trick. You can pre-define a few different lengths of whitespaces to minimize the amount of recursion depth required:

type InstantiationDepthReducingWhitespace =
  // This will match first, consuming 3 leading spaces at once
  | '   '
  | '  '
  | ' '
  | '\n'

Clever! Now let's implement TrimEnd and combine them together:

type InstantiationDepthReducingWhitespace =
  | '   '
  | '  '
  | ' '
  | '\n'

type TrimStart<T extends string> =
  T extends `${InstantiationDepthReducingWhitespace}${infer Tail}`
    ? TrimStart<Tail>
    : T

type TrimEnd<T extends string> =
  T extends `${infer Prefix}${InstantiationDepthReducingWhitespace}`
    ? TrimEnd<Prefix>
    : T

type Trim<T extends string> = TrimEnd<TrimStart<T>>

The end result:

// type Result = "abc"
type Result = Trim<'\n\n  abc   '>

// The need for trimming long whitespace appears
// in deeply nested (more indentation) multi-line strings:
function doSomething() {
  if (condition) {
    if (another) {
      cn(`
        block
        p-1
        hover:bg-blue
      `)
    }
  }
}

For the curious minds: the type instantiation depth was first increased to 500 but later reduced back to a 100, which isn't a huge amount for template literal processing.

The same pull request, which lowered the type instantiation depth limit to 100, also implemented tail recursive evaluation of conditional types. The description has examples of how the Trim utility could be even further improved.

3. Error messages

The built-in way to indicate a type error is to use never. It works because never is not assignable to any other type.

In complex conditional types you might have multiple instances of never type, but for separate issues. This makes the code hard to read and type errors less descriptive. Unfortunately, TypeScript doesn't natively support anything like throw.

However, there is a hack that achieves almost the same result. Instead of returning never, you can return the error message as a literal string:

type IsValid<T extends string> =
  T extends ClassName
    ? T
    : `Error: '${T}' is not a valid Tailwind class`

The literal string error message works in a similar way as never. Types aren't assignable to it in practice. It's easiest to understand via an example (TypeScript playground):

function cn<T extends string>(singleClassName: IsValid<T>) {
  return singleClassName;
}

// Argument of type '"invalid"' is not assignable to parameter of type
// '"Error: 'invalid' is not a valid Tailwind class"'.
cn('invalid')

The passed parameter typed as literal 'invalid' is not assignable to the error message that is also a literal string type. This pattern can be extracted as a utility type to make the intention more clear:

// Utility type to provide nicer error messages
type Err<Message extends string> = `Error: ${Message}`

4. Split to tokens and validate

This is going to be a tough piece.

To ease the token processing, let's make a utility that converts className string into an array of tokens. Working with an array is easier than for example a string with space separated values.

The new utility called SplitToTailwindClassNames should do the following conversions:

We'll start with the familiar template literal inference. This time instead of consuming whitespace characters, we want to consume Tailwind class names.

type SplitToTailwindClassNames<T extends string> =
  // Does `T` start with a Tailwind class name?
  T extends `${ClassName}${infer Tail}`
    // Yes. Continue consuming ClassName tokens with
    // next recursion iteration.
    ? [ClassName, ...SplitToTailwindClassNames<Tail>]
    // No. Stop recursion.
    : []

We can see that the utility now knows how to consume Tailwind class name tokens (TypeScript playground).

// type Debug1 = []
type Debug1 = SplitToTailwindClassNames<' '>

// type Debug2 = [ClassName]
type Debug2 = SplitToTailwindClassNames<'block'>

// type Debug3 = [ClassName, ClassName]
type Debug3 = SplitToTailwindClassNames<'blockp-1'>

// Note: whitespace is not correctly handled yet!

// type Debug4 = [ClassName]
type Debug4 = SplitToTailwindClassNames<'block p-1'>

That's great but the array items are of type ClassName, which is the union type itself. What we really need is the actual tokens found, for example ['block', 'p-1'].

There's no way in TypeScript to make a template literal match a token and assign it to a type variable at the same time. If TypeScript supported the feature, it could look something like this:

T extends `${infer C extends ClassName}${infer Tail}`
// `C` would refer to the actual token

But it doesn't.

I couldn't find a solution anywhere online, which lead me to ask the question in Stack Overflow. It took a while to marinate, but finally a solution clicked in my head.

To get access to the first token, you can inverse the inference with a second template literal inference:

type GetTokenTrick<T extends string> =
  T extends `${ClassName}${infer Tail}`
    ? T extends `${infer C}${Tail}`
      ? C
      // This shouldn't be possible to reach, as
      // we just inversed the matching
      : never
    : never

Now the utility captures the first token (TypeScript playground)!

// type Debug = "block"
type Debug = GetTokenTrick<'block<whatever>'>

Let's combine the knowledge so far and also deal with the whitespace by using Trim<Tail>.

type SplitToTailwindClassNames<T extends string> =
  // Does `T` start with a Tailwind class name?
  T extends `${ClassName}${infer Tail}`
    ? T extends `${infer C}${Tail}`
      // Continue consuming ClassName tokens with
      // next recursion iteration.
      ? [C, ...SplitToTailwindClassNames<Trim<Tail>>]

      // This shouldn't be possible to reach, as
      // we just inversed the matching
      : never

    // Stop recursion.
    : []

Many cases are now dealt correctly, but there's still a few issues (TypeScript playground).

// type Debug1 = ["block"]
type Debug1 = SplitToTailwindClassNames<'block'>
// type Debug2 = ["block", "p-1"]
type Debug2 = SplitToTailwindClassNames<'block p-1'>
// type Debug3 = ["block", "p-1"]
type Debug3 = SplitToTailwindClassNames<'block\n\np-1   '>

// Still not working:

// Whitespace at the beginning
type Debug4 = SplitToTailwindClassNames<' block'>  // []

// Errors are not dealt correctly,
// should be [never]
type Debug5 = SplitToTailwindClassNames<'invalid'>  // []

The easiest way to fix the leading whitespace issue is to make a wrapper utility that calls Trim:

type SplitToTailwindClassNames<T extends string> = SplitToTailwindClassNamesInner<Trim<T>>

The error handling can be improved by using the Err type and separating the "invalid T" and "end recursion" cases (TypeScript playground):

type SplitToTailwindClassNamesInner<T extends string> =
  T extends `${ClassName}${infer Tail}`
    ? T extends `${infer C}${Tail}`
      ? [C, ...SplitToTailwindClassNames<Trim<Tail>>]
      : Err<'Should not happen'>

    // Added error handling
    // Handles cases where `T` does not match
    // ${ClassName}${Tail}. For example
    // 'block', '', '\n\n', 'invalid', or 'invalid  block'
    //
    // Note: `Tail` has already been trimmed from whitespace
    : T extends `${infer Tail}`
      ? Tail extends ClassName
        // `Tail` equals a valid Tailwind class.
        // End recursion succesfully.
        ? [Tail]
        : Trim<Tail> extends ''
          // `Tail` has only whitespace left.
          // End recursion succesfully.
          ? []
          // Something else was found.
          // Raise an error
          : [Err<`'${Tail}' is not a valid Tailwind class`>]

      // Should never happen as `T` is a string.
      : [Err<'Should not happen'>]

Finally we got to a version that handles all the cases as expected.

5. String type

Let's turn the pieces above into a utility which validates that a string contains only valid Tailwind classes. The utility type only works if the string is a literal type such as "p-1 block". A generic string type won't suffice, because template literals operate on string constants.

As the first step, let's validate that the input indeed is a literal string type.

type IsValidTailwindClassString<T extends string> =
  string extends T
    ? Err<'Unexpected generic string'>
    // Make sure each item is a valid `ClassName`
    : SplitToTailwindClassNames<T> extends ClassName[]
      // If yes, success and return the type `T` itself
      ? T
      // If no, raise an error
      : Err<'Invalid Tailwind class string'>

Now when the utility is invoked with a generic string, we get an error:

// INCORRECT
const str: string = 'generic string'

// type Debug = "Error: Unexpected generic string"
type Debug = IsValidTailwindClassString<typeof str>

// CORRECT
const str2 = 'p-1'

type Debug2 = IsValidTailwindClassString<typeof str2>
// type Debug2 = "p-1"

Also, we correctly get an error in case there's an invalid class name:

// type Debug = "Error: Invalid Tailwind class string"
type Debug = IsValidTailwindClassString<`
  block
  bg-green-10c
`>

That's already awesome, but let's change it to show which tokens where invalid for a better developer experience. We could for example return the actual array that contains the correct Tailwind classes and the error (TypeScript playground).

 type IsValidTailwindClassString<T extends string> =
   string extends T
     ? Err<'Unexpected generic string'>
     // Make sure each item is a valid `ClassName`
     : SplitToTailwindClassNames<T> extends ClassName[]
       // If yes, success and return the type `T` itself
       ? T
       // If no, raise an error
-      : Err<'Invalid Tailwind class string'>
+      : SplitToTailwindClassNames<T>

It would work, but the array format can contain valid class names which would make the actual error message harder to spot.

// type Debug5 = ["block", "p-1", "Error: 'invalid' is not a valid Tailwind class"]
type Debug5 = IsValidTailwindClassString<'block p-1 invalid'>

To fix that, we can get the first error from the array. Fortunately we're dealing with just a flat array!

// Gets the first string of an array that starts with 'Error: '
// Must be used only when `T` actually includes an error item
type GetFirstError<T extends unknown[]> =
  T extends [infer Head, ...infer Tail]
    ? Head extends `Error: ${infer Message}`
      // Match found, return
      ? Head
      // Continue searching for an error string
      : GetFirstError<Tail>
    : never

Let's add it to the string-validating utility and call it done (TypeScript playground).

 type IsValidTailwindClassString<T extends string> =
   string extends T
     ? Err<'Unexpected generic string'>
     // Make sure each item is a valid `ClassName`
     : SplitToTailwindClassNames<T> extends ClassName[]
       // If yes, success and return the type `T` itself
       ? T
       // If no, raise an error
-      : Err<'Invalid Tailwind class string'>
+      : GetFirstError<SplitToTailwindClassNames<T>>

After the change, the error looks as expected.

// type Debug5 = "Error: 'invalid' is not a valid Tailwind class"
type Debug5 = IsValidTailwindClassString<'block p-1 invalid'>

Everything we've built so far has been now combined into a single utility type called IsValidTailwindClassString. That was a lot of work, but we still have a few other formats to cover.

6. Object type

In the object format, each key is a string of class name(s) and the value is a truthy or falsy value indicating if the class names should be included in the final class name.

const dense = true
const classNames = cn({
  'p-1 m-1': dense,
  'p-3': !dense
})
// classNames = "p-1 m-1"

We need to iterate through each key-value pair in the object, and validate that the key consists of valid Tailwind classes. "Iterating" objects in TypeScript can be done with mapped types. Let's look at a simpler example where we convert a given input object type values to nullables.

type MakeNullable<T> = {
  // "For each key (K) in object (T)"
  [K in keyof T]: T[K] | null
}

Now we can use MakeNullable to make all object's values nullable (TypeScript playground).

type Input = { a: number, b: boolean }

// type Result = {
//   a: number | null;
//   b: boolean | null;
// }
type Result = MakeNullable<Input>

Using the knowledge, it's not a huge leap to validating Tailwind class names in keys. We already have IsValidTailwindClassString utility type which checks if a given string consists of valid Tailwind classes or not.

// Use `any` because classnames uses truthiness check,
// and does not require booleans
type TailwindClassNamesObject<T extends { [key: string]: any }> = {
  [K in keyof T]: K extends IsValidTailwindClassString<K>
    ? T[K]
    // If invalid class found, return the error
    : IsValidTailwindClassString<K>
}

It's that simple! Well, almost.. If you look at the type in TypeScript playground, you can see the following error.

Type 'K' does not satisfy the constraint 'string'.
  Type 'keyof T' is not assignable to type 'string'.
    Type 'string | number | symbol' is not assignable to type 'string'.
      Type 'number' is not assignable to type 'string'.(2344)

Even when we explicitly defined that the input object can have only string keys, TypeScript will complain about it. The workaround provided in this PR comment is to use & string to filter out all non-string named properties.

Fortunately the trick works like a charm (TypeScript playground).

// Use `any` because classnames uses truthiness check,
// and does not require just booleans
type TailwindClassNamesObject<T extends { [key: string]: any }> = {
  [K in keyof T & string]: K extends IsValidTailwindClassString<K>
    ? T[K]
    // If invalid class found, return the error
    : IsValidTailwindClassString<K>
}

The errors are correctly reported as we can see from the example.

// type Result1 = {
//   "p-1": true;
//   flexx: "Error: 'x' is not a valid Tailwind class";
// }
type Result1 = TailwindClassNamesObject<{
  'p-1': true,
  'flexx': false,
}>

7. Array type

Finally we have the array format. Each item in the array is a string of class names that we need to validate.

const classNames = cn(['block', 'p-1 m-1'])
// classNames = "block p-1 m-1"

Turns out, you can manipulate the type of each individual array item using the same mapped type syntax as for objects. Let's use the same MakeNullable we used as an example in the object format to demonstrate (TypeScript playground).

type MakeNullable<T> = {
  // "For each index (K) in array (T)"
  [K in keyof T]: T[K] | null
}

// type Result = [number | null, boolean | null]
type Result = MakeNullable<[number, boolean]>

Sometimes TypeScript is just magnificent. The syntax looks a bit odd, but one could argue that arrays do have object-like properties in JavaScript.

The final array type looks very similar to the object one, but with a few minor differences (TypeScript playground).

type TailwindClassNamesArray<T> = {
  [K in keyof T]: K extends IsValidTailwindClassString<T[K] & string>
    ? T[K]
    // If invalid class found, return the error
    : IsValidTailwindClassString<T[K] & string>
}

Instead of validating just K (the key in objects), we validate T[K] which refers to the array item itself. You could think the array as an object where the keys (usually referred as indices) are numeric starting from 0.

The & string trick is required, but in a bit different context. The array item needs to "casted" into a string type, so that TypeScript is happy. Again, having T extends string[] constraint does not help here.

Combining everything

With the individual pieces solved, it's time to put everything together.

Each parameter of the classnames function can be a string, object, or an array. To allow the same flexibility with strict types, we need a type utility that validates the input based on its shape. Conditional type it is.

type TailwindClassParameterValue<S> = S extends string
  ? IsValidTailwindClassString<S>
  : S extends any[]
    ? TailwindClassNamesArray<S>
    : S extends { [key: string]: any }
      ? TailwindClassNamesObject<S>
      : // Format not supported
        never;

As you can see, nested ternaries are not that pleasant to read. Unfortunately it's all we got at type level.

Now, the last part. Typings for the cn function. Prepare to see a bit of an ugly trick..

export function cn<S1, S2, S3, S4, S5>(
  c1?: TailwindClassParameterValue<S1>,
  c2?: TailwindClassParameterValue<S2>,
  c3?: TailwindClassParameterValue<S3>,
  c4?: TailwindClassParameterValue<S4>,
  c5?: TailwindClassParameterValue<S5>,
  // If more than 5 class parameters are required, simply add new ones
): string {
  return classnames(c1, c2, c3, c4, c5)
}

Voila! It's not pretty, but having the copy-pasted type parameters allows TypeScript to infer and validate the arguments individually.

That's the solution! I hope this was educational. Links to the final results:

• Full working React project in replit.com
• TypeScript playground

Credits & further reading

The final types took quite a while to finish, and I couldn't have done it without help. Credits to @ahejlsberg, @virtualkirill, and @jcalz for terrific online resources.

• Make your CSS safer by type checking Tailwind CSS classes
• How to type check if object keys conform a conditional recursive template type?
• Pull request that introduced template literal types
• awesome-template-literal-types — Collection of even more resources
• Type Gymnastics — Collection of wonderful TypeScript type gymnastics code snippets
• ts-sql — SQL "database" implemented purely in TypeScript.
• XML parser in TypeScript
• ts-metacode — TypeScript metaprogramming

Utilities

We ended up implementing numerous advanced TypeScript tricks from scratch. It might make sense to use an existing library instead. There are lodash-like utility packages for TypeScript types too:

• type-fest — A collection of essential TypeScript types
• ts-toolbelt — TypeScript's largest utility library
• ts-essentials — All basic TypeScript types in one place
• utility-types — Think "lodash" for static types

Call to action here. Just kidding, I'm doing this for fun. For now..

This post describes the build-process. You can find more about the software in the GitHub repo.

The final build

We almost always want to know today's weather before leaving the apartment. Often the whole event is quite a hassle: getting our daughter dressed, finding all our personal outwear, plus trying to find your phone to check the weather. To make the experience 1% better, the solution obviously needs engineering.

I decided to build a DIY battery powered e-ink weather display for our home. After researching a while, I ended up with a few goals for the build:

• Easily glanceable weather forecast at the heart of our home. Ideally eliminates one more reason to pick up the phone.
• Looks like a "real product". The housing should look professional.
• Fully battery-powered. We didn't want a visible cable, and drilling the cable inside wall wasn't an option.
• Always visible and doesn't light up the hallway during evening / night. This leads to e-ink display.
• Primarily for our use case, but with reusability in mind. For example custom location and timezone. The end result is somewhat tied to Finland due to using the API of Finnish meteorological institute, but nevertheless the design goal was kept in mind.

The goals come with a few challenges:

• Battery life obviously. Fortunately e-ink displays have an interesting property: the rendered image stays visible as is even if all cables are disconnected. It doesn't require any power to keep the image.
• Low refresh speed due to battery life constraint. My plan was to refresh the screen only once or twice a day. That brings interesting design challenges. How do you indicate that the data is not real time? What should we show as the day's temperature: average or maximum for the day?
• Physical constraints by the frame. Ideally it would be flush to the wall behind.

The plan

The device should wake up early in the morning, fetch the latest weather forecast information, update the information to the e-ink display, and go back to deep sleep until tomorrow.

That way, we would have a fresh weather forecast for the day while consuming minimal amount of battery.

Then comes the execution.

Execution

First I designed the weather UI in Figma. This took around 2 days (i.e. evenings after work).

The designs were intended for the Waveshare 7.5" e-ink display. After ordering one, I started looking into good fonts to display in a 1-bit (black and white) screen. It was surprisingly hard to find real 1-bit-screen fonts, so I tested a few sample renders using regular web fonts with and without post-processing:

I wasn't super satisfied.. the product would be in a central place in our apartment, so it should look nice.

So... after thinking a bit, I ordered the 10.3" 16-gray-scale (4 bits) display in addition, since it allows text to be anti-aliased. The end result is way smoother. It would've been possible to just live with the 1-bit display constraint, but I decided to use that screen for something else in the future.

On the same day, I also ordered a bunch of other hardware I was expecting to use: SD card, PiJuice chip and battery, standoff screws, GPIO cables and adapters. Fortunately a friend of mine had a spare Raspberry Pi Zero lying around which I could use.

After the Figma designs were ready enough, I started creating the HTML page which is used to render the UI. Many existing projects used lower level libraries such as the Python Imaging Library, but I opted for HTML and CSS. Development is fast when you can edit the HTML and immediately see the result without rendering a raster image after each iteration.

UI development took rougly 1-2 weeks when coding in the evenings and weekends. Having the flu delayed the build a bit unfortunately.

The software vs hardware timing realised like a perfect Gantt chart. As soon as I was done fine-tuning the UI, the hardware arrived in Finland. Nice.

Even though the development was done with the 1872x1404 display resolution in mind, I could finally see how it actually looked. The Raspberry Pi installation and setup took quite some time, but it paid off. It was absolutely amazing to see the UI appear the first time on the e-ink display.

Past bedtime

Everything was surprisingly smooth sailing to this point. But then I assembled all the parts together and realized how small the frame actually is.

I didn't want to build a larger visible casing to the back, so it was time to go back to the drawing board. I tried to fit everything in the frame by testing all kinds of combinations. This monstrous GPIO cable + 1-to-2 adapter setup almost did the job:

But even after cutting all extra plastic pieces from the cables, it wasn't possible to mount the frame flush to the wall.

Then I realised that the Waveshare demo page featured a Windows app that connected to the controller via the micro-USB interface. Would it be possible to use that to control the display? There weren't any examples of doing that in a Linux box though.

Fortunately for me, some great minds had already thought the same. I connected the controller using USB cables, built the C code in the Raspberry Pi, and tried to clear the display as a test. It worked! What a relief. USB cables are so much smaller than the 40-pin GPIO cables and headers.

Now that I was confident about the USB-strategy, I needed to get rid of the GPIO header of the IT851 controller. The chip was still too tall for the frame with it attached. Fortunately, Helsinki has an amazing library (more like a library, hacker space, gaming cafe, and a public hangout place combined) where I could go and desolder the header for free.

The picture is from the library's electronics room which has cool gear such as laser cutter, 3D printer, and much more.

It's mind-boggling how cool Oodi is architecturally but also functionally.

Unfortunately, my soldering skills weren't as mind-boggling. The estimate that I gave to my wife was that the job would take around 20 minutes. But even after 1.5 hours of desoldering and googling how to desolder components, I wasn't able to rip the header off the chip. My time was up in the soldering lab.

Next strategy was brute force. I took my side cutters and just chopped half of the header off. All I could hope for was that the chip would work after the treatment. With the GPIO header chopped in half, all parts finally fit the IKEA frame nicely!

The unknowns in the software had been solved, and the final assembly could begin. I mounted everything to the IKEA frame using screws and hot glue. The display is super thin, so I avoided placing any screws on the back cover directly behind the display. The back cover bends slightly so the screws could end up damaging the panel while moving the product for charging.

Tada! Components were able to fit almost perfectly within the 2.9cm thick IKEA Frame. Out of the 2.9cm of thickness, approximately 2cm was left for the actual components.

I was super worried about component damage after the desoldering amateur hour, but fortunately everything still worked.

Finally, I tested a few error cases.

Those done, it was time to mount the frame on our wall.

I really like the end result. The IKEA frame has a white cardboard border, which we ended up cutting to fit the screen. To not have mismatching aspect ratios of the white cardboard border and the frame itself, I sacrificed a few vertical pixels of the e-ink display. The white cover board opening is vertically shorter than what the e-ink display is capable of, leaving some Y-pixels unused. A bit of a shame, but the overall look is most important!

One option I considered was to saw the frame to be a perfect fit for the screen. However, it could've lead to a messy end result and it was much easier to mount everything to the back cover with the extra space.

The project took 3 weeks in calendar time. I was positively surprised about the quick turnaround time. It didn't happen by chance though. I purposely chose familiar hardware and software to make the development easier. The idea was to actually finish the project, even though lower-level tinkering would've been educational and beneficial.

That's everything, it was fun!

Hardware list for reference

• Raspberry Pi Zero W
• PiJuice Zero
• PiJuice 12000mAh battery. As large as possible to avoid having to charge the device often.
• Waveshare 10.3" 1872x1404 e-ink display with Raspberry Pi HAT. Supports 16 shades of black and white.
• Geekworm Raspberry Pi Installation Tool 132 Pcs. For a set of spacers and screws that fit Raspberry Pi projects nicely.
• Micro-usb to USB adapter
• USB to micro-usb cable
• IKEA Hovsta Frame
• Misc building items: hot glue, hair band to hold the battery, wall mounting hooks, small plastic box cut to pieces to support the battery from below, and of course duct tape.

Hardware bought but not needed in the end:

• GeeekPi Micro Connectors Raspberry Pi 40-pin GPIO 1 to 2 Expansion Board. To connect PiJuice and e-ink display nicely.
• GPIO Cable for Raspberry Pi 40 Pin. To allow a bit more flexibility inside the build.

I had a refactoring problem. My increasingly large codebase had widespread database entity model code that used the following signature:

await User.findMany({ name: 'Lisa' })

Which isn't bad per se, but the property names of a model are sharing the same object key namespace with other relevant parameters I was introducing. Relevant parameters such as orderBy and connection object:

await User.findMany({
  name: 'Lisa',
  orderBy: ['createdAt', 'desc'],
  connection: transaction,
})

I lived with the original approach until it bothered me enough to make a move. Let's go through the process together.

The plan was to refactor all calls to the following form:

await User.findMany({ where: { name: 'Lisa' } })

More verbose but also more explicit. In the new format, the unknown property names of models would be clearly isolated from the pre-defined parameters within a where wrapper. Anyways, we're not here to judge my refactoring decisions but to learn how to undo the bad ones quickly using automation.

The problem was that there were 119 call sites. Not that many – but enough to consider if spending an evening for a manual search & replace operation is worth the trouble. Of course not!

I also wanted to level up my AST-based tooling skills so this would be a great opportunity.

The pieces

I decided to use ts-morph. It provides a convenient API to access, traverse, and modify TypeScript code via AST operations. The basic refactoring formula goes like this:

import { Project, SyntaxKind } from 'ts-morph'

const project = new Project({})
project.addSourceFilesAtPaths('src/**/*.ts')

const sourceFiles = project.getSourceFiles()
for (const file of sourceFiles) {
  // TODO: traverse and modify file AST as needed

  await file.save() // Save file changes to disk
}

Next we need to find our database model call syntax nodes and learn how to modify their code.

To get started, I usually copy paste a minimal example code to https://ts-ast-viewer.com/. This makes it easier to understand what to look for. For example a simple await User.findMany({ name: 'Lisa' }) becomes:

SourceFile
  ExpressionStatement
    AwaitExpression
      CallExpression
        PropertyAccessExpression
          Identifier
          Identifier
        ObjectLiteralExpression
          PropertyAssignment
            Identifier
            StringLiteral
  EndOfFileToken

Pasting too much code makes the tree difficult to understand as the AST is so verbose.

Once you have an understanding of the nodes types to look for, jump back to the editor. We can use the file.getDescendantsOfKind() method and simply log everything we find. Let's start with AwaitExpressions.

for (const file of sourceFiles) {
  const awaitExpressions = file.getDescendantsOfKind(SyntaxKind.AwaitExpression)
  for (const awaitExpression of awaitExpressions) {
    console.log(awaitExpression.getText())
  }
}

This should print out all of them. However we're only interested of the database entity methods, so let's narrow it down further by checking if a descendant PropertyAccessExpression can be found with a specific name.

function shouldRefactor(awaitExpression: AwaitExpression) {
  const paExpression = awaitExpression.getFirstDescendantByKind(
    SyntaxKind.PropertyAccessExpression
  )
  if (!paExpression || paExpression.wasForgotten()) {
    // In certain cases ts-morph stops tracking nodes for performance
    // optimisation reasons. If the node was forgotten, accessing it throws.
    return false
  }

  const name = paExpression.getName()
  const entityMethods = ['find', 'maybeFind', 'findMany']
  return entityMethods.includes(name!)
}

Finally we need to modify the await expression as required. Luckily for me none of the call sites used any other parameters than the object property names. That allows us to simply just wrap the original object parameter with a new one: { where: <original> }.

To do that we can use the getText() method of ObjectLiteralExpression node to get the original { name: 'Lisa' } parameter as text and replace it with the new format using replaceWithText().

function refactor(awaitExpression: AwaitExpression) {
  const param = awaitExpression.getFirstDescendantByKind(
    SyntaxKind.ObjectLiteralExpression
  )
  if (!param) {
    throw new Error(`SyntaxKind.ObjectLiteralExpression not found`)
  }

  const paramAsTxt = param.getText() // e.g. "{ name: 'Lisa' }"
  param.replaceWithText(`{ where: ${paramAsTxt} }`)
}

That's all the pieces we need! The approach will mess up indentation in source code, but fortunately there's eslint --fix! After the refactor operation, all formatting trouble should be possible to fix with a single eslint command.

The result

Everything in a ready-to-go TS script.

import chalk from 'chalk'
import path from 'path'
import { AwaitExpression, Project, SyntaxKind } from 'ts-morph'

void main()

async function main() {
  console.log('Refactoring ..\n')

  const project = new Project({})
  project.addSourceFilesAtPaths('src/**/*.ts')

  const sourceFiles = project.getSourceFiles()
  // To debug typescript code AST: https://ts-ast-viewer.com/
  for (const file of sourceFiles) {
    const filePath = path.relative(process.cwd(), file.getFilePath())

    console.log()
    console.log(chalk.bold(filePath))

    const awaits = file.getDescendantsOfKind(SyntaxKind.AwaitExpression)
    for (const awaitExpression of awaits) {
      if (!shouldRefactor(awaitExpression)) {
        continue
      }
      refactor(awaitExpression)
    }

    await file.save()
  }
}

function shouldRefactor(awaitExpression: AwaitExpression) {
  const paExpression = awaitExpression.getFirstDescendantByKind(
    SyntaxKind.PropertyAccessExpression
  )
  if (!paExpression || paExpression.wasForgotten()) {
    // In certain cases ts-morph stops tracking nodes for performance
    //  optimisation reasons. If the node was forgotten, accessing it throws.
    return false
  }

  const name = paExpression.getName()
  const entityMethods = ['find', 'maybeFind', 'findMany']
  return entityMethods.includes(name!)
}

function refactor(awaitExpression: AwaitExpression) {
  const param = awaitExpression.getFirstDescendantByKind(
    SyntaxKind.ObjectLiteralExpression
  )
  if (!param) {
    throw new Error(`SyntaxKind.ObjectLiteralExpression not found`)
  }

  const paramAsTxt = param.getText() // e.g. "{ name: 'Lisa' }"
  param.replaceWithText(`{ where: ${paramAsTxt} }`)
}

Mass refactoring TypeScript is surprisingly convenient using ts-morph. You wouldn't want to do this for every small change, but it's worth considering for larger refactoring piles.

This time the automated approach took me more than the manual would've. But next time...

Prior art

• Write an auto-fixable ESLint rule and apply
• jscodeshift