Forem: Kenneth G. Franqueiro

Type-Safe Eleventy Data Cascade Access with TSX and Preact Hooks

Kenneth G. Franqueiro — Sun, 19 May 2024 17:32:12 +0000

This post continues where Making Eleventy Data Traceable with TSX and Zod leaves off; it will be easier to follow after completing the steps in that post first.

My previous post culminated in having fully-typed (and validated) data available to top-level templates in TSX; from there, it is possible to build an entire component hierarchy, passing both Eleventy-supplied and custom data throughout.

This can turn out to be more cumbersome the more you componentize, as you may end up needing to pass properties down repeatedly, even in the case of Eleventy-supplied data.

What if we could access and validate data needed directly within each component rather than all-at-once at the top level? This would be more in line with how Eleventy templates are typically written, but with the same typing and validation assurances of the previous approach.

Since we've already started down the path of TSX, this sounds like something that context could address...

Replacing jsx-async-runtime with Preact

jsx-async-runtime doesn't know anything about the concept of context, as that is a feature specific to React and Preact. We'll use the latter, since it's far more lightweight. Bear in mind that we're only using this within the Eleventy build process itself; it will not add any client-side JavaScript.

First, let's update dependencies:

npm rm jsx-async-runtime
npm i preact preact-render-to-string
# (or yarn add/remove, etc. as desired in place of npm)

Update tsconfig.json to reference the correct JSX runtime:

"jsxImportSource": "preact",

Then update the tsx transform in eleventy.config.ts:

import type { VNode } from "preact";
import { renderToString } from "preact-render-to-string";

// ...

eleventyConfig.addTransform("tsx", (content: VNode) =>
  renderToString(content)
);

The content property we defined in EleventyProps in the previous post also needs updating:

import type { ComponentChildren } from "preact";

// ...

export interface EleventyProps {
  content: ComponentChildren;
  eleventy: EleventyMeta;
  page: EleventyPage;
}

Handling TSX vs. non-TSX Content

In the previous post, I mentioned that content from both TSX and non-TSX templates would Just Work with jsx-async-runtime because it doesn't escape HTML in JavaScript by default.

Preact does escape by default, which means that while TSX template content (received as JSX children) can be handled as before...

  <body>{content}</body>

...non-TSX template content (received as strings) needs to remain unescaped, since it is expected to contain markup:

<body dangerouslySetInnerHTML={{ __html: content }} />

One layout can support both TSX and non-TSX templates by checking whether content is a string:

typeof content === "string" ? (
  <body dangerouslySetInnerHTML={{ __html: content }} />
) : (
  <body>{content}</body>
)

If you find you need to support both formats across many layouts, you can create a helper function like this:

import { type ComponentChildren } from "preact";

export const resolveContent = (content: ComponentChildren) =>
  typeof content === "string"
    ? { dangerouslySetInnerHTML: { __html: content } }
    : { children: content };

// Example usage:
// <body {...resolveContent(content)} />

If you're also planning to use both TSX and non-TSX layouts, you'll find that the tsx transform needs to be made more robust than it was in the original JetBrains series, to avoid running renderToString on non-TSX layouts (because, like above, content will already be a string):

eleventyConfig.addTransform("tsx", (content: string | VNode) =>
  typeof content === "string" ? content : renderToString(content)
);

Creating the Context Object

Creating a context requires setting up a default value for it. Rather than write a bunch of lines for a value that should never be used, we're going to take an intentional shortcut here:

const DataContext =
  createContext(null as unknown as EleventyProps);

This cast ensures that the type returned when consuming the context is always EleventyProps; meanwhile, the default null value will cause immediate and loud failures in the build process if we ever forget to hook up the provider.

Provider Setup

We can save ourselves some work - and make it as easy as possible to remember to hook up the provider - by creating a helper for TSX templates' render functions:

import { type ComponentType } from "preact";

// ...

export const createRender =
  <T extends EleventyProps>(Component: ComponentType) =>
  (props: T) =>
    (
      <DataContext.Provider value={props}>
        <Component />
      </DataContext.Provider>
    );

The helper function takes care of passing data from Eleventy to the provider; all we need to do is call it with our layout component:

const Layout = () => ...;

export const render = createRender(Layout);

I intentionally skipped over the layout component here; we'll get to that next.

Consuming the Context

Let's set up a hook to consume the data cascade from the context, and validate any custom data we're expecting. (This takes the place of createEleventyComponent in the previous post.)

import { useContext } from "preact/hooks";
import type { output } from "zod";

export const useData = <T extends ZodTypeAny>(schema: T) => {
  const data = useContext(DataContext);
  const parsed = schema.parse(data) as output<T>;
  return {
    ...data,
    ...parsed,
  };
};

For convenience, we can also expose a simpler hook for cases where only Eleventy's own data (which we previously defined in EleventyProps) is needed:

export const useEleventyData = () => useContext(DataContext);

With the provider hooked up and the hooks in place, we can now consume Eleventy data without needing to think about props:

const Layout = () => {
  const { content, title } = useData(
    z.object({
      title: z.string().min(1),
    })
  );

  return (
    <html>
      <head>
        <title>{title}</title>
      </head>
      <body {...resolveContent(content)} />
    </html>
  );
};

export const render = createRender(Layout);

As with the previous approach, we only need to validate custom data, while Eleventy-supplied data is assumed from our typings.

Further Demonstration

We have effectively moved our schema usage to within individual components, instead of wrapped around the entire layout's invocation. The value of this approach is that each component can validate the specific data it needs in exactly the same way as seen above, with no need to pass props around.

To better illustrate this, let's reorganize the layout into smaller components with more focused responsibilities.

`Meta`

This component will handle adding metadata to the document head, using title and optionally description from custom data.

const Meta = () => {
  const { description, title } = useData(
    z.object({
      description: z.string().optional(),
      title: z.string().min(1),
    })
  );
  return (
    <>
      <title>{title}</title>
      <meta name="og:title" content={title} />
      {!!description && (
        <>
          <meta name="description" content={description} />
          <meta name="og:description" content={description} />
        </>
      )}
    </>
  );
};

`Header`

This component renders a (oversimplified) site header with navigation links. It relies on page.url supplied by Eleventy to determine whether to set aria-current on each link. This can use the simpler useEleventyData hook, since it doesn't need custom data and therefore has nothing to validate.

const Header = () => {
  const { page } = useEleventyData();
  return (
    <header>
      <nav aria-label="Site">
        <ul>
          <li>
            <a href="/" aria-current={page.url === "/" ? "page" : undefined}>Home</a>
          </li>
          <li>
            <a href="/about/" aria-current={page.url === "/about/" ? "page" : undefined}>About</a>
          </li>
        </ul>
      </nav>
    </header>
  );
};

`Layout`

Finally, this is what the Layout component looks like, using the two other components defined above:

const Layout = () => {
  const { content } = useEleventyData();
  return (
    <html>
      <head>
        <Meta />
      </head>
      <Header />
      <body {...resolveContent(content)} />
    </html>
  );
};

Similar to the Header component, the layout only needs access to Eleventy-supplied data.

Meta is the only component out of the three that references custom data, so it's the only one that calls useData and specifies a schema. In more realistic scenarios, it's quite possible that multiple components will depend on the same properties in custom data, in which case it may make sense to centralize schemas for reusable subsets, and/or centralize a superset and make use of pick or omit.

Conclusion

This definitely started out as an experiment, and I imagine it will seem like overkill for some projects. I think it's a nice option to have in contrast to needing to pass down props all the time. Either way, I'm glad to have options for making Eleventy projects more maintainable going forward.

Making Eleventy Data Traceable with TSX and Zod

Kenneth G. Franqueiro — Tue, 14 May 2024 19:04:34 +0000

Eleventy is a fast and versatile static site generator (SSG). Out of the box, it is most likely to appeal to developers used to earlier Python- or Ruby-based web frameworks and SSGs (e.g. Django, Flask, or Jekyll).

I've used Eleventy for a personal project in the past, but eventually switched to Astro. One of the reasons I switched was because I find having typings and explicit imports to be far more maintainable. In Eleventy, there is no paper trail for IDEs to follow between templates/includes and the data cascade, so determining where a variable name seen in an include is actually defined can involve digging through half a dozen different files. Changing data is also a risky and onerous process, as it's far too easy for something to slip through the cracks.

When I saw Paul Everitt's 11tyConf talk and related tutorial series which incorporate TypeScript and TSX into an Eleventy 3.x project, I was immediately excited at the prospect of being able to make Eleventy projects more maintainable. One thing Paul teased but didn't cover in detail was input data validation. My thoughts immediately turned to Astro, and its ability to hook up Zod schemas to content collections to validate front matter. Maybe I could accomplish something similar on top of Paul's TSX setup for Eleventy layouts?

Starting Point

This post will assume you've followed the first 3 parts of the JetBrains tutorial:

At this point, you will have a setup which relies on tsx to understand TypeScript, and jsx-async-runtime to understand JSX/TSX templates.

Adding Types for Eleventy-Supplied Data

As far as I could tell, neither Eleventy itself nor DefinitelyTyped have typings for Eleventy. Let's start with some typings for data that Eleventy exposes that could be useful:

interface EleventyPage {
  date: Date;
  filePathStem: string;
  fileSlug: string;
  inputPath: string;
  outputFileExtension: string;
  outputPath: string;
  rawInput: string;
  templateSyntax: string;
  url: string;
}

interface EleventyMeta {
  directories: {
    data: string;
    includes: string;
    input: string;
    layouts?: string;
    output: string;
  };
  env: {
    config: string;
    root: string;
    runMode: "build" | "serve" | "watch";
    source: "cli" | "script";
  };
  generator: string;
  version: string;
}

export interface EleventyProps {
  content: JSX.Children | string;
  eleventy: EleventyMeta;
  page: EleventyPage;
}

The content property is how an Eleventy layout accesses each child template's output. There are a few things worth noting about this property in the context of TSX:

The JSX namespace referenced above is declared globally by jsx-async-runtime; no import is required
When the child template is Markdown (and presumably others as well), content is a string
When the child template is also JSX/TSX, content itself is JSX

As we'll see below, both the string and JSX content cases work easily with jsx-async-runtime, because it does not escape HTML in JavaScript values by default. This is opposite to more common JSX runtimes; keep this in mind depending on where your data originates.

Incorporating Zod

Zod is a validation library which will easily produce TypeScript typings for defined schemas.

Let's create a centralized helper to take care of most of the work, so that we won't have much boilerplate to repeat in TSX layouts. The helper does the following:

Receives a Zod schema and a functional component
Returns a new functional component that does the following:
- Attempts to parse the props it receives using the schema
- Spreads the parsed output on top of the original data (in order to include all properties from the cascade, even ones not included in the schema, e.g. Eleventy's own provided data)

import type { EleventyProps } from "types";
import type { input, output, ZodTypeAny } from "zod";

export function createEleventyComponent<T extends ZodTypeAny>(
  schema: T,
  FC: (props: EleventyProps & output<T>) => JSX.Element
) {
  return (props: EleventyProps & input<T>) =>
    FC({
      ...props,
      ...schema.parse(props),
    });
}

Using this function in a .11ty.tsx layout would look something like this:

export const render = createEleventyComponent(
  z.object({
    title: z.string().min(1), // require non-empty
  }),
  ({ content, title }) => (
    <html>
      <head>
        <title>{title}</title>
      </head>
      <body>{content}</body>
    </html>
  )
);

In this example, title comes from the Zod schema, and content comes from Eleventy-supplied data (see notes in the previous section). We get IntelliSense for both, thanks to the typings in createEleventyComponent.

Meanwhile, schema.parse will fail loudly if someone forgets to provide title in the front matter data of any template (TSX or otherwise) that uses this layout:

[11ty] 1. Having trouble writing to "./_site/index.html" from "./index.md" (via EleventyTemplateError)
[11ty] 2. Transform `tsx` encountered an error when transforming ./index.md. (via EleventyTransformError)
[11ty] 3. [
[11ty]   {
[11ty]     "code": "invalid_type",
[11ty]     "expected": "string",
[11ty]     "received": "undefined",
[11ty]     "path": [
[11ty]       "title"
[11ty]     ],
[11ty]     "message": "Required"
[11ty]   }
[11ty] ] (via ZodError)

Thus, we get the benefits of TypeScript on one side, along with the assurance that we will receive the data we expect from the other.

Further Advantages

The createEleventyComponent function spreads the parsed output over the original props, so we can benefit from coercion and transforms in the Zod schema.

Coercion can be particularly useful in the event you are computing template strings in front matter. As a contrived example, let's modify the schema from the previous example to include a number field:

  z.object({
    n: z.coerce.number(),
    title: z.string().min(1), // require non-empty
  }),

The use of z.coerce means you will always get a number value, even if it is populated through a computed template string (which ordinarily results in a string):

---
eleventyComputed:
  n: "{{ 42 }}"
title: "Hello world"
---

Conclusion

The approach explained in this post is primarily useful for defining TSX layouts. You're free to componentize however you like from that point onward, e.g. defining a component that helps lay out meta tags, or reusable header/footer components that are instantiated differently across distinct layouts. Since you now have fully typed and validated props at the layout level, passing them to child components works as it would in any other TSX codebase, making it far easier to see what data each layout and component expects at a glance.

I'm experimenting with another idea to take this approach one step further; I'm hoping to have another post about that coming up soon.

Comments from Mastodon

The Eleventy team informed me that there is an eleventyDataSchema feature since 3.0.0-alpha.7 that can effectively support data validation (Zach even includes a Zod example). This is great if validation is all you're after, and you can obtain typings from your schema using Zod's infer, output, or TypeOf (they're all synonymous). However, there's no way to benefit from coercion or transforms as discussed above, since the validation pass can't override the data.

Nuxt 3 First Impressions from a Next.js User

Kenneth G. Franqueiro — Fri, 11 Aug 2023 17:07:13 +0000

I'd been curious to check out Vue and Nuxt for a while. Last month, I finally had a chance to start reading up on it, and experiment with rebuilding a couple of sites that I had originally built with Next.js 12 and Preact.

From my initial experience, there are certainly a few things I really like, but there are also a few things I'm wary of.

Built-in CSS module typings

In a previous post, I explained how to generate specific typings for CSS module classes in Next.js. With Vue SFCs (both with or without Nuxt), you don't have to perform any special setup for this beyond installing the Volar extension for Visual Studio Code and setting it up in your workspace - it immediately works out-of-the-box.

Built-in API endpoint typings (and simpler API routes)

Something that quickly stood out to me about Nuxt, coming from Next.js, was that it uses Nitro which provides a very "make simple things easy and hard things possible" approach to API routes. Not only is it extremely easy to define API endpoints that return JSON; when you do so, you also automatically get typings for their responses when using Nuxt's data fetching APIs.

Any defineEventHandler callback that returns a value results in an API route that returns the equivalent JSON:



export default defineEventHandler((event) => {
  return { hello: "world" };
});

When you use useFetch or $fetch within a Vue component for an API route defined in this way, you'll immediately get autocomplete and typings:

Note: Your dev server must be running in order to generate these typings.

This is a huge developer experience boost, saving you from redundantly specifying API response types on both server and client (or dealing with any implicitly on the client).

useFetch as a replacement for getServerSideProps

It took me a moment to realize that everything in Vue SFCs will run both server- and client-side by default, much like the default-exported component in a Next.js page module. There isn't really a direct equivalent to getServerSideProps, but we can make use of API routes and Nuxt's isomorphic useFetch API for that purpose.

When useFetch runs server-side, it directly calls the underlying API function with no extra network request. Additionally, it will automatically refresh client-side when any reactive references involved in the URL change (e.g. changing query parameters based on form inputs). You can explicitly instruct useFetch to watch other reactive references as well.

The absence of a more tangible boundary a la getServerSideProps means you don't need to explicitly pass along data from server-side methods to component props. Once you store the result of a useFetch call within <script setup>, it's available for use in the component template. This might also save you some effort exporting explicit typings, since you have no need to declare typings for component props for data received from the server - the types can flow directly through.

Note: In addition to tucking server-side logic into API routes, the process object available in components includes boolean server and client values, which can be used to conditionalize component logic to run during SSR or CSR but not both.

Example: Hooking up a search API to a query parameter

Let's say you have a web application with a search form that updates a list of results within the page, and reflects the current query via a GET parameter. This use case involves some unique considerations, since the same component instance remains mounted when only URL parameters change but the route remains the same.

(Bonus: If you set your form's action to the URL path of your search route, and your input's name matches the query parameter used, the approach outlined in this example should work both with and without JavaScript enabled.)

First, you'd want to initialize two refs based on the query parameter: one for the currently active query, and another to synchronize with the form's input via v-model:



const q = ref(useRoute().query.q);
const inputQuery = ref(q.value);

When the form is submitted, you'll want to update this value via a function hooked up to the form via @submit.prevent:



const onSubmit = () => {
  q.value = inputQuery.value;
};

Meanwhile, to populate your results, you'll want to call your API using the currently active query:



const { data, error } = await useFetch("/api/search", {
  query: { q },
  onResponse() {
    if (process.client)
      // Sync browser URL when client-side request completes.
      // (navigateTo can't be called directly within onResponse)
      nextTick(() => {
        const query = q.value ? { q: q.value } : {};
        navigateTo({
          path: "/",
          query,
        });
      });
  },
});

Notice that we pass the q ref - not its unwrapped value - directly to query. By doing this, Nuxt is aware that it should re-fetch any time q changes - i.e. when we submit the search form.

Finally, to keep state in sync upon browser history state changes:



onBeforeRouteUpdate(async (to) => {
  q.value = inputQuery.value = to.query.q || "";
});

Module resolution surprises

For some reason, in each app I experimented with porting, part of Nuxt's stack seemed to disagree with lodash's module format.

In a project that uses lodash only server-side, everything worked in dev, but broke when I tried running the production server. I resolved this by adding lodash to the transpile build option in nuxt.config.ts:



export default defineNuxtConfig({
  // ...
  build: {
    transpile: ["lodash"]
  },
  // ...
});

In another project that uses lodash both server- and client-side, I additionally ran into an issue where referencing default exports from lodash's individual modules (e.g. import uniq from "lodash/uniq") didn't seem to work, even with esModuleInterop: true included in my TypeScript compileOptions. I was able to resolve this issue by switching to lodash-es.

I'm quite puzzled by these issues, since lodash is an exceedingly common dependency, and I did not encounter similar issues with any other dependencies. I really want to think I overlooked something...

Cryptic errors

When I encountered the aforementioned lodash issues, as well as a few others that cropped up, I often found that Nuxt's errors were not terribly helpful. The stack trace would be buried within Nuxt's own lifecycle without reflecting where the error originated in my own code. Sometimes there would be no stack trace at all. Perhaps I was just unlucky with the types of errors I encountered?

Documentation runs deep

Nuxt incorporates and builds upon several libraries, which means there's a lot of ground to cover when looking for documentation:

Nuxt
Vue (for components and composables)
Vue router (which Nuxt's routing is based upon)
Nitro (for the server directory, e.g. API routes)
h3 (for helpers available in API routes)
ofetch (for data fetching APIs)

You won't necessarily need to know everything about every single piece of the puzzle, but keep in mind that sometimes particular details you're looking for may originate in one of the more-specific libraries, rather than in Nuxt's own docs. (Fortunately, they cross-link in some of the most relevant places.)

Conclusion

I was pretty excited by the developer experience benefits that I discovered and outlined in this post. That being said, I'm wary of committing to using Nuxt on larger-scale apps given how much head-scratching ensued from some of the errors and snags I encountered. There's also the matter of everything under components being available as auto-imports by default; I'd probably want to fine-tune that behavior for a larger project, lest it pollute autocomplete with a bunch of stuff that's irrelevant most of the time.

I've also more recently started experimenting with Qwik, now that I realized it also has a meta-framework in the form of Qwik City. I've already experimented with porting one of my projects to it and it seems promising; I might write up thoughts on that separately after trying it on both projects I tested with Nuxt.

Given some questionable articles I've seen lately, I feel compelled to point out that I'm not simply chasing these frameworks in the name of "ooh shiny"; I firmly believe that an existing framework being "old" is not nearly sufficient reason to bail on it. However, I've seen enough folks hinting that React has been late to the party with some useful features, and I've also been wary of the complex direction Next 13 is headed in, so I've wanted to see what benefits are unique to other frameworks. That being said, Next 12 had some great features and the best developer experience I had encountered at that point, and I imagine that React will continue to have critical mass for a while.

Supercharging CSS modules with TypeScript

Kenneth G. Franqueiro — Mon, 17 Apr 2023 14:55:23 +0000

CSS modules are a means of organizing styles that allows structuring them parallel to component modules. Several modern frameworks such as Next.js, Vue/Nuxt, and Astro even include built-in support. In this post, we'll be looking at how we can make CSS modules into an even more powerful tool in conjunction with more accurate TypeScript typings.

CSS Module Usage Basics

If you haven't seen CSS modules before, the main premise is that they allow you to define code in CSS files with the .module.css extension. Each module will be compiled into uniquely-prefixed class names to provide isolation from other CSS resources.

.myClass {
  /* Styles here */
}

The resulting prefixed class names can then be referenced by importing the CSS module within JavaScript or TypeScript:

import styles from "./Foo.css";

export const Foo = () => (
  <div className={styles.myClass}>Hello world</div>
);

Note: Camel-case class names are recommended in order to reference them easily within JS/TS.

Many frameworks also optionally support Sass, allowing you to define modules in .module.scss files as well. Note that CSS modules and Sass' own module system are independent from one another, and you can take advantage of both simultaneously.

Here are some resources with more information about CSS modules:

CSS Modules and TypeScript

Unfortunately, in my experience with Next.js at the time of writing, CSS modules come with a vague { readonly [key: string]: string } type out of the box. This is enough to make them workable in TypeScript, but doesn't provide any particular benefits.

If we were able to get more specific typings based on the contents of our CSS modules, we could catch typos and get autocomplete when consuming them in JS/TS modules, and perhaps even do far more powerful things with them...

Fortunately, there are a few projects that may help with this:

typings-for-css-modules-loader (webpack loader)
typed-css-modules (CLI)
typed-scss-modules (CLI for SCSS, inspired by typed-css-modules)

There are undoubtedly multiple ways to get this working; I opted for typed-scss-modules, since I was planning to take advantage of some Sass features such as mixins, and I'm using Next.js which already configures CSS modules itself by default.

Running `typed-scss-modules` with Next's Dev Server

I used an approach akin to webpack-shell-plugin-next to run typed-scss-modules along with next dev, by adding the following to my next.config.js:

// Prevent running typed-scss-modules more than once
let isTapped = false;
class TypedScssModulesPlugin {
  apply(compiler) {
    if (isTapped) return;
    compiler.hooks.afterPlugins.tap("TypedScssModulesPlugin", () => {
      require("child_process").spawn(
        "npm", ["run", "tsm:watch"], { stdio: "inherit" }
      );
    });
    isTapped = true;
  }
}

const nextConfig = {
  // ...
  webpack(config, { dev, webpack }) {
    if (dev) {
      config.plugins.push(
        new TypedScssModulesPlugin(),
        new webpack.WatchIgnorePlugin({
          paths: [/scss\.d\.ts$/]
        })
      );
    }
    // ...
    return config;
  },
};

module.exports = nextConfig;

The above config relies on a scripts entry in package.json with the following definition:

"tsm:watch": "typed-scss-modules components --includePaths styles --exportType default --watch"

In the above arguments, components is the folder where all of my .module.scss files reside, and styles is where I have common Sass modules that I want to be able to @use without specifying a path.

Now when you run next dev, you should see messages about .module.scss file changes being detected and .module.scss.d.ts files being generated. After they've been generated, you should see improvements to intellisense for CSS module imports - namely, it should show you exactly what class names are available, and report nonexistent class name references as errors.

Building Component Props from CSS Module Typings

Working autocomplete and typo prevention are a great start, but the use case that sent me down this path was more ambitious. I was working on building up a UI library to replace a runtime CSS-in-JS solution to reduce overhead, but wanted to replicate some of its concepts, such as color schemes, sizes, and variants (different styles of the same component, e.g. solid vs. outlined).

I wondered, could I get to the point where typings for each separate prop are generated based on the SCSS with no manual repetition required across TS and SCSS files? Could I maybe even define this all within a single CSS module, in order to guarantee that each "dimension" out-specifies base styles?

Fortunately, with some digging and experimenting, the answer was yes!

The Component Design

Let's say we want to design a button component that allows simultaneously specifying the following:

Color scheme, either blue or red
Size, either small or medium
Variant, either solid or outline

The SCSS

We'll start with the following class names. Note that all dimensions' styles are nested to guarantee they out-specify base styles - in my experience with Next.js at least, this can end up being necessary because builds can scramble CSS selector declaration order.

.button {
  /* Base styles */

  &.variantSolid {
    /* Common styles for variant */

    &.colorBlue {
      /* Color-scheme-specific styles for variant */
    }

    &.colorRed {
      /* Color-scheme-specific styles for variant */
    }
  }

  &.variantOutline {
    /* Repeat the same structure as above */
  }

  &.sizeSm {
    /* Styles for small size */
  }
  &.sizeMd {
    /* Styles for medium size */
  }
}

The Prop Typings

With these styles in place and their typings generated, we want to define props for each dimension. Ideally, we want to build their types based on the generated CSS module typings, in such a way that we don't have to manually keep them in sync across TypeScript and SCSS.

Notice that I used a common prefix for all of the class names for each dimension. This will enable TypeScript to do all the work of picking out the appropriate values for us, by combining a few very useful but possibly-obscure features:

String template literal type inference
infer within extends for template string types (the most specific docs for this I could find are from one of TypeScript's "What's New" articles, not a handbook page, unfortunately)
The Uncapitalize utility type

The following type allows us to pass it an entire styles type and get back a string union type with only the keys having a particular prefix, with the prefix removed and the first letter of the remaining string changed to lowercase:

export type PrefixedKeys<Map extends {}, Prefix extends string> =
  Extract<
    keyof Map,
    `${Prefix}${string}`
  > extends `${Prefix}${infer S}`
    ? Uncapitalize<S>
    : never;

This allows us to define our dimensions as follows:

import styles from "./Button.module.scss";

type ButtonColorScheme =
  PrefixedKeys<typeof styles, "color">;
type ButtonSize =
  PrefixedKeys<typeof styles, "size">;
type ButtonVariant =
  PrefixedKeys<typeof styles, "variant">;

export interface ButtonProps {
  colorScheme?: ButtonColorScheme;
  size?: ButtonSize;
  variant?: ButtonVariant;
}

export const Button = ({
  colorScheme = "blue",
  size = "md",
  variant = "solid"
}) => (...);

This will allow us to optionally specify these dimensions when creating instances of the component:

<Button colorScheme="red" variant="outline">
  Remove
</Button>

The Implementation

Hopefully this seems pretty exciting already, but there's one remaining hurdle: due to how specific the typings in styles are, if you attempt to casually reattach the provided string to the prefix, you're likely to get TypeScript errors. How do we implement the actual bindings of these values to members of styles in a type-safe way?

Fortunately, we can define another function to help reconstruct the typings for this:

export const prefixValue =
  <P extends string, S extends string>(prefix: P, value: S) =>
    `${prefix}${value[0].toUpperCase()}${value.slice(1)}` as `${P}${Capitalize<S>}`;

When we pass the prefix and value to this function, it explains to TypeScript that the result is the specified prefix followed by the specified string with its first letter capitalized, effectively accomplishing the reverse of how we picked the class names out of styles to create our dimensions' typings before.

We can use this function to implement our component's className prop as follows (for simplicity's sake, this assumes usage of the classnames package):

return (
  <button
    className={classNames(
      styles.button,
      styles[prefixValue("color", props.colorScheme)],
      styles[prefixValue("size", props.size)],
      styles[prefixValue("variant", props.variant)],
      props.className // Allow passing through more classes
    )}
  >
    {children}
  </button>
);

Conclusion

In this post, I aimed to demonstrate how with the right tools, CSS modules and TypeScript can be used as a basis for configurable core UI components, with no runtime CSS-in-JS required. With developers becoming increasingly-conscious of the performance penalties incurred by runtime CSS-in-JS, this is one potential alternative worth considering.

Using TypeScript 4.9 with Next.js 12

Kenneth G. Franqueiro — Fri, 10 Feb 2023 23:24:35 +0000

I regularly work in a codebase running on Next.js 12, and recently updated its TypeScript dependency to 4.9, looking forward to being able to take advantage of useful new features such as the satisfies operator.

Unfortunately, the moment I tried to use anything 4.9-specific, things went sideways rather quickly, as the dev server and build command didn't recognize the feature, due to their use of SWC. Since Next.js 12 hasn't had new releases for a while, the accompanying version of SWC is now significantly out-of-date.

This wouldn't be an issue if the codebase were on Next.js 13, but we haven't made the jump yet for a variety of reasons. Fortunately, I was able to overcome this obstacle while remaining on Next.js 12; if you find yourself in a similar situation, hopefully this process can work for you as well.

Version-Pinning SWC

Both npm and yarn provide a way to override installed versions of packages in package.json: npm through the overrides property (only in npm 8 or higher), and yarn through the resolutions property.

Unfortunately, as I found out, yarn's resolutions property has a long history of not playing well with optionalDependencies: anything placed into resolutions is treated as required and will abruptly fail to install if it is, for example, a platform-specific package appropriate for your deploy environment but not your dev environment or vice versa, as is the case here.

Since this particular codebase also relied on yarn, this warranted an impromptu switch to npm to see how overrides would fare. Fortunately, synp exists to migrate between package lockfile formats. (npm also evidently supports yarn.lock files directly, which I only found out after converting, so I didn't put that to the test.)

npm's overrides had no issue working, with the following configuration:

"overrides": {
  "next": {
    "@next/swc-darwin-x64": "13.1.6",
    "@next/swc-linux-x64-gnu": "13.1.6",
    "@swc/helpers": "0.4.14"
  }
}

By forcing the version of relevant platform-specific @next/swc-* packages (in this particular case, OS X for dev and Linux for CI/deployment) to their latest v13 counterparts, and updating @swc/helpers to match the dependency listed in v13, we can get support for TypeScript's new features while still running Next.js 12, and there don't seem to be any adverse side effects.

Other Potential Gotchas

We've tackled the dev server and build process itself above, but other parts of your toolchain may also require updating to support TypeScript 4.9 if they haven't been in a while. Make sure to test all aspects of local development (including your code editor and its extensions), and of course keep an eye on CI processes when merging the update.

I encountered a couple more hiccups:

Jest

The codebase relied on Jest 27, using babel-jest and babel-loader. This similarly ran into issues failing to parse TypeScript 4.9 features. I ended up doing a few things on the way to resolving this:

Upgraded to Jest 29
Updated a couple of packages (isbot and uuid) to incorporate fixes that resolved errors that would come up in newer versions of Jest
Switched from babel-jest and babel-loader to ts-jest (note that this requires a custom tsconfig.json with "jsx": "react", as opposed to Next requiring "jsx": "preserve")

Prettier

In my case, Prettier was still on a rather old version, so I needed to update it to 2.8 in order for next lint to pass, since the codebase uses eslint-plugin-prettier.

Forem: Kenneth G. Franqueiro

Type-Safe Eleventy Data Cascade Access with TSX and Preact Hooks

Replacing jsx-async-runtime with Preact

Handling TSX vs. non-TSX Content

Creating the Context Object

Provider Setup

Consuming the Context

Further Demonstration

Meta

Header

Layout

Conclusion

Making Eleventy Data Traceable with TSX and Zod

Starting Point

Adding Types for Eleventy-Supplied Data

Incorporating Zod

Further Advantages

Conclusion

Comments from Mastodon

Nuxt 3 First Impressions from a Next.js User

Built-in CSS module typings

Built-in API endpoint typings (and simpler API routes)

useFetch as a replacement for getServerSideProps

Example: Hooking up a search API to a query parameter

Module resolution surprises

Cryptic errors

Documentation runs deep

Conclusion

Supercharging CSS modules with TypeScript

CSS Module Usage Basics

CSS Modules and TypeScript

Running typed-scss-modules with Next's Dev Server

Building Component Props from CSS Module Typings

The Component Design

The SCSS

The Prop Typings

The Implementation

Conclusion

Using TypeScript 4.9 with Next.js 12

Version-Pinning SWC

Other Potential Gotchas

Jest

Prettier

`Meta`

`Header`

`Layout`

Running `typed-scss-modules` with Next's Dev Server