Forem: Hector Sosa

Caching Shiki for Faster Build Times

Hector Sosa — Mon, 25 Sep 2023 14:32:27 +0000

Introduction

Shiki is arguably the most popular syntax highlighter out there. It uses the TextMate grammar system with the VS Code Oniguruma library to tokenize strings which then can be stylized using VS Code themes or CSS variables. Shiki is the way to go if you want your code to look exactly like that in VS Code.

Using Shiki is practical because as your favorite languages and themes evolve, your syntax highlighting will evolve as well.

If you're here for the faster build times, go to faster build times. If you've never heard of or used Shiki before, here's a great introduction:

How does it work?

Although Shiki has a lot of customization options (themes, languages, and custom renderers), at its core, Shiki's highlighter is incredibly easy to work with:

Call getHighlighter with the theme and languages you need to create a highlighter instance, and then
Use the highlighter methods, such as codeToHtml, to take a string of code and transform it to syntax-highlighted HTML.

Of course, there are more details, so make sure to check out Shiki's configuration and options. However, if you want to keep things simple, here's how you'd get started:

import { getHighlighter } from "shiki";

// Create a highlighter instance
const highlighter = await getHighlighter({
  theme: "nord",
  langs: ["ts"],
});

const code = `console.log("Here is your code.");`;

// Call a highlighter method to get syntax-highlighted HTML
const output = highlighter.codeToHtml(code, { lang: "ts" });

What are the easiest customizations you can use?

Using CSS variables for theming

One of the biggest things missing in Shiki is the lack of support for light/dark or dual-theming. While there are several solutions and alternatives out there, none are directly addressed by the library. If you're not restricted to using VS Code themes, you can use CSS variables for theming.

import { getHighlighter } from "shiki";

// Create a highlighter instance
const highlighter = await getHighlighter({
  // ✅ Use CSS variables for theming
  theme: "css-variables",
  langs: ["ts"],
});

Then use CSS to style your code and create the theming implementation of your choice. Here's a safe starting point for this:

:root {
  --shiki-color-text: #24292f;
  --shiki-color-background: #ffffff;
  --shiki-token-constant: #0550ae;
  --shiki-token-string: #24292f;
  --shiki-token-comment: #6e7781;
  --shiki-token-keyword: #cf222e;
  --shiki-token-parameter: #24292f;
  --shiki-token-function: #8250df;
  --shiki-token-string-expression: #0a3069;
  --shiki-token-punctuation: #24292f;
  --shiki-token-link: #000012;
}

:root .dark-theme {
  --shiki-color-text: #c9d1d9;
  --shiki-color-background: #0d1117;
  --shiki-token-constant: #79c0ff;
  --shiki-token-string: #a5d6ff;
  --shiki-token-comment: #8b949e;
  --shiki-token-keyword: #ff7b72;
  --shiki-token-parameter: #c9d1d9;
  --shiki-token-function: #d2a8ff;
  --shiki-token-string-expression: #a5d6ff;
  --shiki-token-punctuation: #c9d1d9;
  --shiki-token-link: #000012;
}

Note: If you prefer to stick with VS Code Themes you might want to check out Anthony Fu's Shikiji, which is an ESM-focused rewrite of Shiki.

Using custom renderers and CSS counters for line numbers

Custom renderers allow you to define your own custom rendering rules per each element type. The easiest way to understand how custom renderers work is by creating a renderer for line numbers. Instead of using codeToHtml, you can use codeToThemedTokens from your highlighter instance to obtain an array of tokens and then call renderToHTML, passing your tokens and your custom renderer.

import { getHighlighter, renderToHTML } from "shiki";

// Create a highlighter instance
const highlighter = await getHighlighter({
  // ✅ Use CSS variables for theming
  theme: "css-variables",
  langs: ["ts"],
});

const code = `console.log("Here is your code.");`;

// ✅ Tokenize your code to apply your custom renderer
const tokens = highlighter.codeToThemedTokens(code, "ts");

// ✅ Use your custom renderer to get syntax-highlighted HTML
const output = renderToHTML(tokens, {
  elements: {
    line({ children, className, index }) {
      return `<span data-line=${index}
        class=${className}>${children}</span>`;
    },
  },
});

You can combine renderers with CSS to create any implementation you might need. Here is an example using CSS Counters (with a touch of TailwindCSS) for this purpose:

.shiki code {
  @apply grid p-5 font-mono text-sm leading-normal;
}

code {
  counter-reset: line;
}

code > [data-line]::before {
  counter-increment: line;
  content: counter(line);
  @apply mr-6 inline-block w-4 text-right text-gray-500/50;
}

code[data-line-numbers-max-digits="2"] > [data-line]::before {
  @apply w-8;
}

code[data-line-numbers-max-digits="3"] > [data-line]::before {
  @apply w-12;
}

A font pairing that I've enjoyed recently is Schibsted Grotesk with IBM Plex Mono. Alright, now let's get to what we're here for How to get faster build times using Shiki?

Faster build times

Regardless of how you use Shiki, the more code you highlight, the more likely it is that you will run into performance issues. After testing, our team concluded that (a) creating Highlighter instances, (b) loading languages, and (c) generating token explanations are Shiki's most resource-intensive operations.

You should make sure that the Highlighter instance is only created once, and that it is bootstrapped asynchronously before calling any of the exposed functions

Shiki provides you with the flexibility to create the implementations you need to meet your syntax highlighting requirements, but you should exercise caution when using this flexibility. There's no built-in caching system or checks to make sure that the Highlighter instance is only created once, so you'll need to create your own.

Creating a caching system doesn't have to be overly complicated. By leveraging Map and abstracting the getHighlighter method, you can achieve this.

import shiki, { type Highlighter, type Theme, type Lang } from "shiki";

// ✅ Use Map to store Highlighter instance promises
const highlighterCache = new Map<string, Promise<Highlighter>>();

export async function getHighlighter({
  theme,
  langs,
}: {
  theme: Theme;
  langs: Lang[];
}) {
  // ✅ Generate identifiers for your instances, check and return if found
  const key = [theme, ...langs].join("-");
  const highlighter = highlighterCache.get(key);
  if (highlighter) return await highlighter;

  // ✅ If an instance hasn't been created, store it and return it
  const highlighterPromise = shiki.getHighlighter({ theme, langs });

  highlighterCache.set(key, highlighterPromise);
  return await highlighterPromise;
}

A word on Shiki's explanations

Shiki's explanations are the biggest hidden bottleneck, though. Understanding Shiki's explanations is key to optimizing performance. Explanations are set to false if you're using codeToHtml, but with codeToThemedTokens you'll find the option: includeExplanation, which annotates this option and describes explanations as:

Whether to include an explanation of each token's matching scopes and why it's given its color. It defaults to false to reduce output verbosity.

Interestingly enough, explanations are considered and included in the source code for both methods. They are exposed to the developer only with codeToThemedTokens and documented with a default value of false. However, it turns out that the default value for this option is set to true, so if performance is your concern and you do not need to make use of explanations, set this option to false.

import { getHighlighter } from "@lib/shiki"; // Shiki Cache Abstraction
import { renderToHTML, type Theme, type Lang } from "shiki";

/** ✅ Config */
const theme: Theme = "css-variables";
const lang: Lang = "ts";

const highlighter = await getHighlighter({
  theme,
  langs: [lang],
});

const code = `console.log("Here is your code.");`;

// ✅ Avoid getting explanations if you do not need them
const tokens = highlighter.codeToThemedTokens(code, lang, theme, {
  includeExplanation: false,
});

const output = renderToHTML(tokens, {
  elements: {
    line({ children, className, index }) {
      return `<span data-line=${index}
        class=${className}>${children}</span>`;
    },
  },
});

Final thoughts

If you're using any flavor of markdown and do not need control over Shiki, plugins like Rehype Pretty Code, which integrate custom renders and caching systems, are excellent choices that align with the concepts explored in this article.

This simple caching and setup solution made our build times a remarkable 80% faster. We tried various other suggestions, but none worked as effectively as creating a caching system for Shiki Highlighter instances. By implementing these strategies, you can ensure a smoother and faster syntax highlighting experience for your projects.

Here are a couple of things to keep in mind:

The keys used to identify instances are prone to duplicates if Highlighter instances are created using different aliases, i.e. typescript and ts. Check Shiki's language aliases and make sure your team has a convention for their use.
You might not need to build your own caching system. If you aren't using Shiki directly, chances are that this has already been addressed by the libraries you're using.
Using Shiki in the browser might require a different approach, make sure to check Shiki's architecture to learn more.

Huge thanks to: @ChcJohnie and @ericvalcik for these findings.

An invitation to OSS Contributors for Screenshot

Hector Sosa — Tue, 30 May 2023 13:29:45 +0000

Screenshot is an open-source tool that provides users with granular controls to frame their screenshots and build engaging content faster.

How does it work?

To use Screenshot, go to usescreenshot.app, (1.) click on the frame to paste your clipboard's image, and then (2.) adjust the settings as needed.

We are actively working to improve and add more settings to Screenshot. Our goal is to provide a simple but powerful set of controls that can adjust to your needs.

What's under the hood?

Screenshot is a web-application being built with React in TypeScript, bootstrapped with create-next-app, and styled with TailwindCSS and Radix UI components heavily inspired by ui.shadcn.com.

Share your feedback

If you encounter an issue or would like to suggest a new feature, please feel free to reach out using our GitHub Repository at usescreenshot.app/github.

Contributing

Contributing to Screenshot is a great opportunity to join OSS. Specially at this early pre-release stage, we are actively looking to engage with users and developers to learn more together about Screenshot.

Issues, Pull requests, and Discussions are welcomed! For more information about our project visit: GitHub Repository at usescreenshot.app/github

If you find Screenshot helpful, we'd appreciate giving it a Star in GitHub.

Fun fact: All of the screenshots used in this article have been created using usescreenshot.app, with the exception of the text.

Building React Hooks - Copy to Clipboard

Hector Sosa — Wed, 05 Apr 2023 12:45:31 +0000

How many times have you seen out there in the wild the need to copy to the clipboard? Whether it's a piece of code (no shame if it's from StackOverflow 💁🏻‍♂️ cough cough), a URL you want to share 💅🏻, or a simple text you need to refer elsewhere 🤓.

The easiest way to reduce friction in having something copied to the clipboard is by enabling buttons, and we all know that "Copy to clipboard" buttons are literally everywhere. So today we'll design a React Hook that enables our application to interact with the user's clipboard. Why hooks? 🤷🏻‍♂️

React applications are built from components. Generally, components are built using Hooks, whether they are built-in or custom.

A quick refresher on what you need to know about React Hooks:

All your Hooks should be written in camelCase and starting with use, such as useState. If your linter is configured for React, it should help you with this.
Hooks can only be called at the top level (before any returns). They shouldn't be called inside loops, conditions, or nested functions.
Only Hooks and components can call other Hooks! Therefore, functions that don’t call Hooks don’t need to be Hooks. You don't need hooks for everything.

Why Custom React Hooks?

Integrating custom React hooks that can be incredibly useful in different use cases. Here are a few examples:

useLocalStorage: This hook provides an easy way to store and retrieve data in the browser's localStorage. This can be useful for persisting data across sessions or keeping track of user preferences.
useMedia: This hook allows you to query the media query string and return a boolean indicating whether it matches or not. This can be useful for implementing responsive design, hiding or showing elements based on screen size, or dynamically changing styles.
usePrevious: This hook allows you to keep track of the previous value of a state variable. This can be useful when you need to compare the current and previous values and trigger a side effect based on the difference.
useAsync: This hook allows you to easily manage asynchronous operations with error handling, loading and data states. This can be useful for making API calls or handling long-running operations.
useDebounce: This hook lets you debounce the execution of a function by a specified delay. This is useful when you have an input field that triggers a search query, but you don't want to make the API call on every keystroke.

There are many other custom hooks available that can help you simplify your code and make it more reusable. The best hooks to use will depend on your specific use case and requirements.

How to use `Clipboard.writeText()`

The Clipboard interface's writeText() property writes the specified text string to the system clipboard.

navigator.clipboard
  .writeText("Text to copy")
  .then(()=> /* Clipboard successfully set */)
  .catch((err) => /* Clipboard write failed */);

If we go ahead and integrate this directly into a button, it could look something like this:

import React from "react";
import { CopyIcon, ErrorIcon, SuccessIcon } from "@/components/icons";

export const CopyButton = ({ 
    textToCopy, 
    children 
  }: { 
    textToCopy: string, 
    children?: React.ReactNode 
  }) => {
  const [clipboardState, setClipboardState] = React.useState<boolean | Error>(false);
  return (
    <button
      onClick={() => {
        navigator.clipboard
          .writeText(code)
          .then(() => setClipboardState(true))
          .catch((e) => setClipboardState(e));
      }}
    >
      {children}
      {clipboardState ? (
        clipboardState instanceof Error ? <ErrorIcon /> : <SuccessIcon />
      ) : (
        <CopyIcon />
      )}
    </button>
  );
};

We could call it a day, but we can do better. At a simple glance, here's what we would need:

⛔️ Check for support on navigator.clipboard. Even if we abstract this logic into a handler function our component would start to get messy.
⛔️ We aren't resetting our UI after the operation. Setting a timeout would come in handy but this would require even more code.
⛔️ The more this functionality is required in our codebase, the harder it'll get to adopt and maintain.

Creating a Custom Hook

Custom Hooks should abstract as much logic as possible from the component that interacts with build-in React Hooks. We should only expose exactly what the UI needs to call the operation and provide the right feedback to the user.

Here is what our custom hook will do:

✅ navigator.clipboard support check before executing operations;
✅ Handle automatic resets after interacting with the clipboard;
✅ Keep a simple and straight-forward hook to consume anywhere in our codebase.

import React from "react";
type CopyState = "READY" | "SUCCESS" | Error;

export const useClipboard = ({ delay = 2500 } = {}) => {
  const [state, setState] = React.useState<CopyState>("READY");
  const [copyTimeout, setCopyTimeout] =
    React.useState<ReturnType<typeof setTimeout>>();

  function handleCopyResult(result: CopyState) {
    setState(result);
    clearTimeout(copyTimeout);
    setCopyTimeout(setTimeout(() => setState("READY"), delay));
  }

  function copy(valueToCopy: string) {
    if ("clipboard" in navigator) {
      navigator.clipboard
        .writeText(valueToCopy)
        .then(() => handleCopyResult("SUCCESS"))
        .catch((error) => error instanceof Error && handleCopyResult(error));
    } else {
      handleCopyResult(
        new Error("`useClipboard`: Navigation Clipboard is not supported")
      );
    }
  }

  return { copy, state };
};

Is there a one-size-fits-all design approach?

Following patterns/conventions helps your consumer to understand what your hook does and where state, Effects, and other React features might be “hidden”. However, React Hooks may return arbitrary values.

Notice we aren't returning a traditional tuple [value, setValue]. Although, depending on the use case, it may be favorable to follow this design. Additionally, we could expose other methods/values in our hook depending on our application's needs.

Here are other options you can choose to build in and provide to your consumers:

isClipboardSupported to indicate whether or not the component can use the clipboard;
copiedText to provide feedback on what's in the clipboard by using clipboard.readText();
reset() method to reset failed operations.

As-is, with this abstraction in place, this is how all components that require clipboard interaction would look like with clipboard.copy and clipboard.state.

import React from "react";
import { CopyIcon, ErrorIcon, SuccessIcon } from "@/components/icons";
import { useClipboard } from "@/hooks";

export const CopyButton = ({ 
    textToCopy, 
    children 
  }: { 
    textToCopy: string, 
    children?: React.ReactNode 
  }) => {
  /* ⬇️ Methods are now available to copy and check the hook's state */
  const clipboard = useClipboard();
  return (
    <button onClick={() => clipboard.copy(textToCopy)}>
      {children}
      /* ⬇️ Type autocompletion will make it easy to structure your UI */
      {clipboard.state === "READY" && <CopyIcon />}
      {clipboard.state === "SUCCESS" && <SuccessIcon />}
      {clipboard.state === "ERROR" && <ErrorIcon />}
    </button>
  );
};

Bonus Hook - Set and Clear Timeouts

Yes, you don't need hooks for everything, but there is still an additional level of abstraction we could achieve here. Notice how useClipboard clears and calls a timeout every single time the button is used. Executing a function after a specified delay is also a very common use case in React applications. So let's take it a step further and design a bonus hook: useTimeout.

Let's jot down what would we want from a useTimeout hook:

✅ Methods to call and cancel a given timeout;
✅ Control between timeouts;
✅ Avoid triggering unnecessary re-renders.

This is a perfect use case to write a hook that interacts with useRef. Why? (a) Unlike state, refs are mutable and (b) Refs are not required for and don't trigger re-renders.

Normally, writing or reading ref.current during render is not allowed. However, it’s fine in the case below because the result is always the same, and the condition only executes during initialization so it’s fully predictable.

import React from "react";

export const useTimeout = (callback: Function, delay: number) => {
  const callbackRef = React.useRef<Function | null>(null);
  const timeoutIdRef = React.useRef<number | null>(null);

  /* ⬇️ Only executed during initialization */
  if (!callbackRef.current) {
    callbackRef.current = callback;
  }

  const call = React.useCallback(() => {
    if (!timeoutIdRef.current) {
      timeoutIdRef.current = window.setTimeout(() => {
        callbackRef.current && callbackRef.current();
        timeoutIdRef.current = null;
      }, delay);
    }
  }, [delay]);

  const cancel = React.useCallback(() => {
    if (timeoutIdRef.current) {
      window.clearTimeout(timeoutIdRef.current);
      timeoutIdRef.current = null;
    }
  }, []);

  return { call, cancel };
};

This hook could be improved as well. For instance, we could choose to provide our consumers with the option to autoInvoke the hook without having to call it. As-is though, our useClipboard and codebase can benefit from this abstraction. Here's how to use this one:

import React from "react";
import { useTimeout } from "@/hooks";

type CopyState = "READY" | "SUCCESS" | Error;

export const useClipboard = ({ delay = 2000 } = {}) => {
  const [state, setState] = React.useState<CopyState>("READY");
  /* ⬇️ We consume our hook passing the needed params */
  const timeout = useTimeout(() => setState("READY"), delay);

  function handleCopyResult(result: CopyState) {
    setState(result);
    /* ⬇️ We call the timer and leave the rest to the hook */
    timeout.call();
  }

  function copy(valueToCopy: string) {
    if ("clipboard" in navigator) {
      navigator.clipboard
        .writeText(valueToCopy)
        .then(() => handleCopyResult("SUCCESS"))
        .catch((error) => error instanceof Error && handleCopyResult(error));
    } else {
      handleCopyResult(
        new Error("`useClipboard`: Navigation Clipboard is not supported")
      );
    }
  }

  return { copy, state };
};

Wrapping up

Learning how to write a custom React Hook can give you several benefits:

Reusability: extract and reuse common logic in your application. By creating a custom hook, you can encapsulate complex functionality into a reusable unit that can be easily shared across different components and projects.
Abstraction: keep implementation details and focus on the high-level behavior of your component. This can help you write more declarative code and make your components easier to understand and maintain.
Composition: enable the possibility to combine multiple hooks together to create more complex functionality. This can give you the advantage of composition patterns to build more powerful and flexible components.
Better performance: reduce the amount of redundant code and avoid unnecessary re-renders.
Improved code organization: organize your code more effectively by separating concerns and promoting a more modular architecture. Create a clear separation of concerns between your components and hooks, which can make your code easier to reason about and maintain over time.

The main takeaway here is that learning how to write custom React Hooks can help you write cleaner, more modular, and more reusable code, which can save you time and effort in the long run.

Check out the code for this implementation on hectorsosa.me/hooks. How would you design this hook? Is there anything we've missed? Let us know at @_ekqt.

For more articles and full resources visit Webscope's Blog.

This article references:

Understanding Buttons and Links from Zero

Hector Sosa — Thu, 26 Jan 2023 13:59:36 +0000

How can we build from scratch buttons and links that are easy to use, typesafe and modular that just make sense? Welcome to a new series on basic React Components that are built with TypeScript and TailwindCSS from the ground up. All of these will be OSS and free to use.

Disclaimer: If you aren't onboard using React, TypeScript or TailwindCSS. Please note this series includes all of them.

TL;DR: at the end of the article you can find examples of how to use both of them by themselves or to create Navigation and Footer components.

Here's what we're building:

This article was originally published at Webscope's blog. For all resources/source code/examples please visit: Understanding Buttons and Links from Zero

Buttons vs Links

Maybe a hot take: let's treat our buttons and links differently, no? Let's keep things simple, a button shouldn't be a link and vice-versa.

Buttons start an action. The text on the button should tell what will happen when the user clicks on it. A Link is a reference to a resource. This can either be external (e.g. a different website) or internal (e.g. a specific element or page in the current website).

If you need to execute an action: use a button. If you need to navigate to a resource: use a link. What experience you want the user to have entirely depends on you.

What to consider - Buttons and Links

Here are some decisions you need to take when making either of these:

Typography and color: family, size, text/background color
Borders and spacing: radius, width, color, padding
Responsive design
Handling hover, focus, and other states
Dark mode styles

Here are some personal considerations when designing a button:

Name, role and keyboard-focusable should all be accessible (use the right HTML elements)
The contrast between text and background should pass accessibility checks with both light and dark modes (you can check this with the inspection tool from your Devtools)
Choose borders to define the look and type of your element (Tertiary buttons sometimes only have bottom borders. Inline, external, and navigation links should look different)
The padding ratio should be at least a 3 to 1 (horizontal to vertical) or bigger for buttons and for links it should be at least 2 to 1.
At smaller viewports the buttons should take full length, the links should remain at its length and they should both be stacked (very personal opinion)
Hover, active, focus, and disabled states are a must and should be significantly different from each other (use the Force element state pane from your DevTools to design accordingly)
The dark mode should alter all the color-related properties (background, color, borders, states)

Test these elements by clicking on each of them, using the keyboard's Tab key to toggle focus between them, change the viewport's size and enable dark mode all to see how these iterations work.

Here's a Button element TailwindPlayground:

Here's a Links Anchor element TailwindPlayground:

Creating a Button Component

A button component will allow you to use all of the design decisions made until now, integrate variants for different button types and also quickly consume the component around your code. Let's take a look at the decisions you need to make:

What props definitions do you need to create vs which ones can you reuse (more is less here, the more you can inherit from the button element, the better)
How will you allow your custom props (let's call these variants) to interact with each other (will you need discriminated unions or will your props overlap with each other by design)
What variants will you define as default (the fewer props you need to declare when using your custom component, the better)

Our goal here is to create a button component that can handle the following markup with typesafety:

import Button from "@/components/Button";

/* All buttons should be able to use the button attributes */
export default function Buttons(){
    return (
        <>
            /* When variant isn't define the button
               should default to primary */
            <Button icon >Submit</Button>
            /* Only primary buttons can have an icon */
            <Button variant="secondary" >Save</Button>
            <Button variant="tertiary" >Cancel</Button>

        </>
    )
}

Here you need to decide what is it that you need. It's all up to you, but for now let's create three variants ("primary", "secondary", and "tertiary") and an icon prop (that defaults to an arrow on the right side of the button) that can only be used when the variant is primary.

/* Most component won't need to obtain a ref for its inner element  */
type ButtonProps = React.ComponentPropsWithoutRef<"button"> &
    /* 1. A discriminated union with a never type will signal
       when should the icon prop be used.
       2. Partials constructs all of its properties as optional.
    */
    Partial<
        | {
              variant: "primary";
              icon: boolean;
          }
        | {
              variant: "secondary" | "tertiary";
              icon: never;
          }
    >;

export default function Button({
    variant = "primary",
    icon,
    ...props
}: ButtonProps){
    return (
        <button
            {...props}
            className={`
                ...defaultStyles
                ${variant === "primary" ? "..." : ""}
                ${variant === "secondary" ? "..." : ""}
                ${variant === "tertiary" ? "..." : ""}
            `}
        >
            {props.children}
            {variant === "primary" && icon && (
                <svg aria-hidden>{...}</svg>
            )}
        </button>
    )
}

If you need to reference the full example visit: Understanding Buttons and Links from Zero

Creating a Link Component

All starting considerations from the button component apply here too. Our goal here is to create a link component (will call anchor component to avoid name conflicts with framework components) that can handle the following markup with typesafety:

import Anchor from "@/components/Anchor";

/* All links should be able to use the anchor attributes */
export default function Links(){
    return (
        <>
            /* Only primary Anchors can have an icon */
            <Anchor 
                variant="external" 
                href="#" 
                target="_blank" 
                rel="noreferrer" 
            >
                External
            </Anchor>
            <Anchor variant="nav" href="#">Navigation</Anchor>

        </>
    )
}

Here we'll create two variants ("external", "nav") and and add an icon conditionally without a prop and depending on which variant is used.

type AnchorProps = React.ComponentPropsWithoutRef<"a"> & {
    variant?: "external" | "nav";
};

/* No need to worry about all of the additional props */
export default function Anchor({ variant, ...props }: AnchorProps) {
    return (
        <a
            {...props}
            className={`
                ...defaultStyles
                ${variant === "external" ? "..." : ""}
                ${variant === "nav" ? "..." : ""}
            `}
        >
            {props.children}
            {variant && (
                <svg 
                    aria-hidden 
                    className={`${variant === "external" ? "..." : "..."}`} 
                >{...}
                </svg>
            )}
        </a>
    )
}

If you need to reference the full example visit: Understanding Buttons and Links from Zero

This article was originally published at Webscope's blog. For all resources/source code/examples please visit: Understanding Buttons and Links from Zero

Thanks for reading, until next time!

Understanding Suspense with Next 13

Hector Sosa — Fri, 06 Jan 2023 16:09:02 +0000

Before even talking about Suspense we need to know that the most important addition in React 18 is concurrency. In computer science, Concurrency is the ability to deal with lots of things at once, which is not the same as doing lots of things at once (as parallelism is).

How React has achieved concurrency has been completely abstracted from us, as React wants us to focus on what we want the user experience to look like, whereas they'll handle how to deliver that experience.

When it comes to UX, Concurrency is such a big deal because it's the driving mechanism that enables our applications to have multiple versions of its UI at any time without blocking the main thread, all whilst enabling fast, consistent and reliable experiences for our users.

Originally published in Webscope's blog: Understanding Suspense with Next 13

Where does Suspense fit in all this?

If you're new to the React ecosystem, you might be asking yourself: What's Suspense? Suspense lets you declaratively specify the loading state for a part of the component tree if it's not yet ready to be displayed.

Suspense isn't new in the React ecosystem. However, now in React 18, Suspense has support for server-rendering and brings all of React's new concurrent features. This also is a huge win for DX, because as developers, we are no longer forced between doing something early, or doing something late, we just literally need to start using Suspense.

Concurrency in React 18 is unlocked by Suspense, making "UI Loading state" a first-class declarative concept in the React programming model.

How does it work?

Conceptually, you can think of Suspense as being similar to a catch block. However, instead of catching errors, it catches components "suspending". Any component in the tree can "suspend", which means that it's not ready to render.

Only Suspense-enabled data sources will activate Suspense, such as:

Lazy-loading component code using lazy() (pre-React 18)
Data fetching with Suspense-enabled frameworks like Relay, Next.js, Remix

Luckily for us, the code looks exactly the same:

<div>
    <Card />
    <Suspense fallback={<PhotoSkeleton />}>
        // The Photo component will suspend 
        // and React will show PhotoSkeleton until ready
        <Photo /> 
    </Suspense>
</div>
<div>
    <Suspense fallback={<ContentSkeleton />}>
        <Content />
    </Suspense>
</div>

What are the biggest perks of using Suspense in React 18?

Streaming HTML lets you start emitting HTML as early as you’d like, streaming HTML for additional content together with the <script> tags that put them in the right places.
Selective Hydration lets you start hydrating your app as early as possible before the rest of the HTML and the JavaScript code are fully downloaded. It also prioritizes hydrating the parts the user is interacting with, creating an illusion of instant hydration.

How to use Suspense in Next 13?

Thanks to Next 13 new file-system based router and special file conventions using Suspense becomes a breeze. Their framework abstracts boundaries altogether (this also includes Error boundaries) by letting us focus even more on what we want the user experience to look like, while they handle the rest.

Next 13 achieves this abstraction using their file-based router. Let's imagine a directory structure where we are building a route called /loading (we probably should've used a better name but as you all know, naming is hard):

# @path: ./app/examples
├── loading            # <-- Route segment
│   └──loading.tsx    # <-- Loading UI
│   └──page.tsx       # <-- Page content for `/examples/loading` route

As you can already tell, each folder in a route represents a route segment as long as it has a page.tsx file (so ./app/examples/loading directory structure would translate to the path /examples/loading).

In Next 13, loading.tsx files automatically wrap a page or child layout in a React Suspense boundary without having to declare it manually, providing an instant loading state on the first load and when navigating between sibling routes.

The directory structure above would translate into the following component hierarchy:

// @path: ./app/examples/loading
<Layout>
    <Suspense fallback={<LoadingSkeleton />}>
        <Page />
    </Suspense>
</Layout>

By using these special file conventions, you can structure your Suspense boundaries with ease:

// @path: ./loading/loading.tsx
export default function Loading() {
    // You can add any UI inside Loading, including a Skeleton.
    return <LoadingSkeleton />;
}

// @path: ./loading/Page.tsx
export default function Page() {
    return <PageContent />;
}

Main takeaways

Next 13 help us create meaningful Loading UI with React Suspense. Here is what you need to know:

The special file loading.tsx (by default server components) enables us to show instant loading states from the server for an entire route segment while its content loads.
You can mix and match your app's architecture using manually-defined <Suspense /> boundaries for more granular loading UI.
Navigation is interruptible, shared layouts remain interactive while nested layouts or pages load.

All resources can be found in Webscope's blog: Understanding Suspense with Next 13

Shipping Zero JavaScript with Astro

Hector Sosa — Wed, 16 Nov 2022 13:37:34 +0000

Astro is an all-in-one web framework designed for building content-focused websites. With this approach in mind, it delivers an incredible developer experience to build server-first, intuitive to use, flexible and fully-featured websites. Anyone who knows a little bit of HTML and CSS all the way up to seasoned developers can leverage Astro's opt-in complexity framework to build for the web.

Astro's biggest perks

Let's see what are the basics that Astro brings to the table, Astro is...

...easy to use and by design less complex than any other UI framework or language (any valid HTML is a valid Astro component, see Why Astro - Easy to Use),
...fast by default shipping ZERO Javascript out of the box, it takes an MPA approach loading on average 90% less JavaScript (see MPAs vs SPAs),
...incredibly featured, flexible and UI-agnostic supporting several frameworks (supporting React, Preact, Svelte, Vue and more), an easier JSX, scoped CSS, file-based routing, data-fetching, and a lot more (see Integrations).

We've built a sample project called Astro for Docs (see source code: GH: Astro for Docs) to showcase how straight-forward and flexible it is to use Astro for Beginners.

What's in the menu for today?

After playing around with this project, it turns out you CAN REALLY build a content-focused website with ZERO JavaScript using Astro. Based on what we've learned, here's what we'd like to show you:

Writing in "Astro" as a language to write Astro Components
Use Markdown files as pages with Astro's MDX and TailwindCSS integrations.
Design nested layouts for better developer experience.
Leverage Astro's Runtime APIs to build components.

Read the entire research at Webscope's blog: Shipping Zero JavaScript with Astro

We ran npm create astro@latest with TypeScript and a blank, empty project and here are our main takeaways:

Astro does deliver a great DX regardless of your level of experience, as building Astro components only really requires HTML and CSS.
Astro is UI-agnostic, meaning you can BYOF it and bring your own framework. They have official support for React, Preact, Solid, Svelte, Vue, and Lit. You can even mix and match different frameworks.
Astro shines with statically generated content. Even if there is no SSR or ISR like Next.js, Astro is considering per-page support for SSR in their 2022 Q4 roadmap.
Astro can ship ZERO JS (you'd be surprised how many things can be achieved with only HTML and CSS). Regardless if you need to introduce Astro Islands and UI frameworks, it loads 40% faster with 90% less JavaScript in comparison to modern frameworks.

Feel free to explore this example using the resources below:

Originally published: Shipping Zero JavaScript with Astro

Build a Tiny Calendar without Flex or useState

Hector Sosa — Tue, 25 Oct 2022 09:00:23 +0000

Is it possible to build a fully functional calendar component under 7 kB without using CSS Flex or useState? Let's explore that possibility by using Day.js with CSS Grid, TailwindCSS, React and TypeScript. Here's what each of these are bringing to the table today:

Day.js — a tiny and fast 2kB alternative API to parse, manipulate and display dates on the web (date-fns is 9.5 times larger).
TailwindCSS — skip CSS Flex by learning the fundamentals of CSS Grid the smart way using Tailwind's Grid utility classes.
React — extract state logic into reducers by exploring useReducer and skipping additional re-renders using useCallback
TypeScript — work smarter and faster by taking advantage of TypeScript's autocompletion and IntelliSense.

There's a lot of ground to cover, so please go through this guide along with the finished component: Calendar GH Repo | Open 'Calendar' in StackBlitz.

Getting started with Day.js

Regardless of the library of choice (if any), here's what we need: (a) current date, (b) current month, and (c) dates for the entire month. Let's take a look how Day.js helps us to get started in defining those initial values:

// USING THE LIBRARY `dayjs`
// dayjs().toDate()      -> Timestamp of today's date / typeof Date
// dayjs().daysinMonth() -> Days in today's month / typeof number

// REUSABLE UTILITY FUNCTIONS FOR `dayjs`
/** Create a date at the start of the day 00:00. */
function today() {
    return dayjs().startOf("day").toDate();
}

/** Create an array of Dates for a given month */
function createMonth(month = today()) {
    return Array.from(
        { length: dayjs(month).daysInMonth() },
        (n, i) => n = dayjs(month).date(i + 1).toDate()
    );
}

These functions will help us clearly define initial values for our calendar with very little code. Once we have these values defined, we are ready to build our first Calendar grid to display each of those dates. The initial values are kept separately for our reducer function to use when we introduce our state logic into our component.

const initialValues = {
    selectedDate: today(),
    currentMonth: today(),
};

export default function Calendar() {
    const { selectedDate, currentMonth } = initialValues;
    const currentMonthDates = createMonth(currentMonth);
    return (
        <div>
            {currentMonthDates.map((date) => (
                <div key={date.toString()}>
                    {date.toString()}
                </div>
            ))}
        </div>
    );
}

Building our Calendar using CSS Grid and TailwindCSS

Using TailwindCSS we can apply and define our Grid property with the utility class grid grid-cols-7, then we can map over our array of dates and create a button for each of them for our users to interact with. By applying the CSS property grid-template-columns: repeat(7, minmax(0, 1fr)); using grid-cols-7, we are explicitly defining the columns and allocation of our columns for all the rows of content to follow.

We also have an array named firstDayOfMonth that contains more Tailwind utility classes. We used this array to define a given utility class for our first item (set conditionally using index === 0) and start the calendar on the correct day of the week (i.e. Monday, Tuesday, etc.).

For any given date (i.e. 1st of October 2022), Day.js can tell us which day of the week that date falls in. For example, the 1st of October 2022 falls on a Saturday, so it's the 7th day of the week (based on a Sunday to Saturday calendar week), calling dayjs(date).day() will return 7 accessing the right utility class to display our calendar.

export default function Calendar() {
    // ...
    const firstDayOfMonth = [
        "col-start-1",
        "col-start-2",
        "col-start-3",
        "col-start-4",
        "col-start-5",
        "col-start-6",
        "col-start-7",
    ];
    return (
        <div className="grid grid-cols-7">
            {currentMonthDates.map((date, index) => (
                <div
                    className={index === 0 ? firstDayOfMonth[dayjs(date).day()] : ""}
                    key={date.toString()}
                >
                    <button>{dayjs(date).format("D")}</button>
                </div>
            ))}
        </div>
    );
}

Using Reducers to Manage State

Now we need to think how to further reduce complexity, keeping all of our calendar logic in a single easy-to-access place using reducers.

Components with many state updates spread across many event handlers can get overwhelming. For these cases, you can consolidate all the state update logic outside your component in a single function, called a reducer.

Reducers are a great way to cut down on code when many event handlers modify state in a similar or related way (i.e. when updating month, we also need to update the days of the month). It also helps you cleanly separate your state logic and improve readability to easily understand what happened on each update.

We need to (1) write a reducer function (which will process all of our actions), (2) use the reducer (function and initial values) in our component, and (3) set dispatch actions to update our component

// REDUCER FUNCTION OUTSIDE COMPONENT
/** Manages state for selected date and current month  */
function reducer(state, action) {
    switch (action.type) {
        case "SELECT_DATE": {
            return {
                ...state,
                selectedDate: action.value,
            };
        }
        case "UPDATE_MONTH": {
            return {
                ...state,
                currentMonth: action.value,
            };
        }
    }
}

// USING OUR REDUCER IN COMPONENT
export default function Calendar() {
    const [ state, dispatch ] = useReducer(reducer, initialValues);
    // ...
    return (
        // ...
    );
}

// DISPATCHING AN ACTION WITHIN COMPONENT
/** Performs calculations and dispatches reducer actions to update state */
function handleDispatch(action) {
    const { type, value } = action;
    switch (type) {
        case "SELECT_DATE": {
            dispatch({ type, value });
            // TODO: Return component's value
            // setValue: value;
            break;
        }
        case "UPDATE_MONTH": {
            const updatedMonth = dayjs(currentMonth)
                .add(value, "month")
                .toDate();
            dispatch({ type, value: updatedMonth });
            break;
        }
    }
}

Avoiding Additional Renders

When you optimize rending performance, you will sometimes need to cache the functions that you pass to child components.

Once our calendar is looking good and behaving the way we want it to, we need to figure out a way for our Calendar to return a Date value for our application. To avoid re-rendering our component, we can use a combination of the ref property and React's useCallback.

React uses ref as a reserved property on built-in primitives, where it stores DOM nodes once a component is rendered/mounted. However, the ref's type declaration type Ref<T> = RefCallback<T> | RefObject<T> | null not only allows a ref object into it, but also a callback function. This allows us to cache a function definition (using both ref and useCallback) without having to use useEffect. Let's implement a callback ref for our calendar component:

export default function Calendar({value, setValue}) {
    /** Cached function to update component's state at load */
    const callbackRef = useCallback(() => {
        setValue(selectedDate);
    }, []);
    /** Performs calculations and dispatches reducer actions to update state */
    function handleDispatch(action) {
        const { type, value } = action;
        switch (type) {
            case "SELECT_DATE": {
                dispatch({ type, value });
                setValue(value);
                break;
            }
            // ...
        }
    }
    // ...
    return (
        <div ref={callbackRef}>
            // ...
        </div>
    );
}

useCallback will return a memoized version of the callback that only changes if one of the inputs has changed.

For a more detailed explanation, Tk's post has a more detailed explanation of this structure: Avoiding useEffect with Callback refs.

Nice things to add

After setting up our data, styling our calendar, and managing its state, here are a couple of nice things that we added to our component:

Refactor the component into a "container/presentational" pattern. Use the "container" component to work with the data/state and then pass the data as props to the "presentational" component to display its UI.
Use an array and map it to create labels for the days of the week: dayjs().day(index).format("dd").
Add a function to generate dynamic TailwindCSS classes using the native Boolean function: function classNames(...classes) { return classes.filter(Boolean).join(" ")}.
Use focusable elements <button /> and descriptive labels aria-label to make sure your component is accessible.

Feel free to explore this example using the resources below:

Originally published: Build a Tiny Calendar without Flex or useState

tRPC: Understanding Typesafety

Hector Sosa — Mon, 17 Oct 2022 09:41:30 +0000

Typesafety is the extent to which a programming language prevents type errors. The process of verifying and enforcing the constraints of types may occur at compile time or at run-time. A programming language like TypeScript checks a program for errors before execution (at compile time) as a static type checker. In contrast, a library like Zod can also provide you type checking at run-time. So how does a library like tRPC helps us better understand typesafety?

tRPC allows you to easily build and consume fully typesafe APIs, without schemas or code generation.

At its core, tRPC provides the solution to statically type our API endpoints and share those types between our client and server, enabling type safety from end-to-end.

How does tRPC share types between client/server?

Types are shared based on one or many procedures contained in Routers. A procedure is a composable query, mutation or subscription where you define how your client/server interact with each other.

Let's see what you'd need to create a query procedure for a Next.js application. We'll explore these concepts by reviewing our tRPC-basic-starter GH repo. Here's how our file structure initially looks like:

# @path: ./src
├── pages
│   └── api/trpc
│       └── [trpc].ts # <-- tRPC HTTP handler
│   └── _app.tsx      # <-- tRPC Provider
│   └── index.tsx
│   └── [...]
├── server
│   └── routers
│       └── _app.ts   # <-- Main app router
│       └── user.ts   # <-- User sub-router
│       └── [...]     # <-- More sub-routers
│   └── trpc.ts       # <-- Procedure helpers
├── utils
│   └── trpc.ts       # <-- Typesafe tRPC hooks

You could define all of your procedures within the tRPC HTTP handler and completely skip the server directory. However, this wouldn't be a scalable approach. It's very likely that your backend will require several endpoints, for which it is recommended to separate your procedures into different sub-routers and merge them as suggested in the file structure above.

To create a query procedure, at the most basic level we need to define an input (optional and validated with your library of choice), and a query (the actual implementation of the procedure) which runs a function returning the data you need. At the end, the types of each router are exported to provide a fully-typed experience on the client without importing any server code.

// @path: ./src/server/routers/user.ts
import { t } from '../trpc';
import { z } from 'zod';

export const userRouter = t.router({
  // Define a procedure (function) that
  // ...takes an input and provides a query
  // ...as `user.greet.useQuery()`
  greet: t.procedure
    // Input validation
    .input( z.object({ name: z.string() }) )
    .query(({ input }) => {
      // Here you would process
      // any information you'd need
      // ..to return it to your client
      return { text: `Hello, ${input.name}!` };
    }),
});

Using your new tRPC-backend on the client

@tRPC/react provides a set of hooks wrapped around @tanstack/react-query, so under the hood, they work just the same to fetch data from a server. You'll notice that the conventional querying keys and functions are defined within your procedure.

// @path: ./src/pages/index.tsx
import { trpc as t } from '../utils/trpc';

export default function Home() {
  // Wrapped around @tanstack/react-query
  // Can also destructure to access
  // isLoading, isError, isSuccess, error and data
  const result = t.user.greet.useQuery({ name: 'Client' });

  if (result.isLoading) {
    return <div><h1>Loading...</h1></div>
  }

  return <div><h1>{result.data?.text}</h1></div>
}

...and that's the basic setup. Both the result and input are type-inferred from the procedures as defined and will get TypeScript autocompletion and IntelliSense that matches your backend API without requiring any code generation.

More examples of tRPC usage

Let's create an additional sub-router @path: ./src/server/routers/post.ts where we need to provide our client with the following: (a) fetch all posts, (b) fetch post by ID, (c) create a new post. Notice that requirements for a and b are different than for c, as the first two are query procedures and the last one requires a mutation procedure. However, you will notice that there is no difference between queries and mutation apart from semantics.

import { t } from "../trpc";
import { z } from "zod";

type PostType = {
    userId: number;
    id: number;
    title: string;
    body: string;
};

export const postRouter = t.router({
    // Define a procedure that
    // ...doesn't require an input and provides a query
    // ...as `post.allPosts.useQuery()`
    allPosts: t.procedure.query(async () => {
        const allPosts = await fetch(
            "https://jsonplaceholder.typicode.com/posts"
        ).then((response) => response.json());
        return { posts: posts as Array<PostType> };
    }),
    // Define a procedure that
    // ...takes an id and provides a query
    // ...as `post.postById.useQuery({ id })`
    postById: t.procedure
        .input(z.object({ id: z.string() }))
        .query(async ({ input }) => {
            const post = await fetch(
                `https://jsonplaceholder.typicode.com/posts/${input.id}`
            ).then((response) => response.json());
            return { post: post as PostType };
        }),
});

How can we use procedures?

Procedures are able to resolve any custom function to process a validated { input }. Just to name a few examples: you could make use of an ORM like Prisma, a Baas like Supabase, or a headless CMS like Sanity to process your data with the benefits of fully typesafe APIs.

What about Mutations?

Mutations are typically used to create/update/delete data. Let's take a look on how we could create a mutation procedure using our Post sub-router:

import { t } from "../trpc";
import { z } from "zod";

type PostType = {
    userId: number;
    id: number;
    title: string;
    body: string;
};

export const postRouter = t.router({
    // Define a procedure that
    // ...takes an id and executes a mutation
    // ...as `post.createPost.useMutation()`
    // ...from `*.mutate({ input })`
    createPost: t.procedure
        .input(
            z.object({
                title: z.string().min(1),
                body: z.string().min(1),
                userId: z.number(),
            })
        )
        .mutation(async ({ input }) => {
            const post = await fetch(
                "https://jsonplaceholder.typicode.com/posts",
                { method: "POST", body: JSON.stringify(input) }
            ).then((response) => response.json());
            return { response: post as PostType };
        }),
});

Here is how we could execute that mutation from the client:

import { FormEvent, ChangeEvent, useState } from "react";
import { trpc as t } from "../../utils/trpc";

export default function NewPost() {
    // User is fixed for simplicity
    const initValue = { title: "", body: "", userId: 1 };
    const [form, setForm] = useState(initValue);
    const mutation = t.post.createPost.useMutation();

    function handleChange(
        e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>
    ) {
        setForm({ ...form, [e.target.id]: e.target.value });
    }

    function handleSubmit(e: FormEvent<HTMLFormElement>) {
        e.preventDefault();
        mutation.mutate(form);
        setForm(initValue);
    }

    return (
        <form onSubmit={handleSubmit}>
            <label htmlFor="title">Title</label>
            <input
                type="text"
                id="title"
                name="title"
                value={form.title}
                onChange={handleChange}
            />
            <label htmlFor="body">Body</label>
            <textarea
                id="body"
                name="body"
                value={form.body}
                onChange={handleChange}
            />
            <button type="submit">Submit</button>
        </form>
    );
}

Mutations are as simple to do as queries, they're actually the same underneath, but are just exposed differently as syntactic sugar and produce a HTTP POST rather than a GET request.

So WIFY by using tRPC?

What's in it for you using tRPC? We barely scratched the surface, here are a list of features:

Full static typesafety with autocompletion on the client, inputs, outputs and errors.
No code generation, run-time bloat, or build pipeline.
Zero dependencies and a tiny client-side footprint.
All requests are able to be batched automatically into one.
Framework agnostic and compatible with all JavaScript frameworks and runtimes.

Feel free to explore this example using the resources below:

Originally published: tRPC: Understanding Typesafety

CSS Grid - Explicit vs Implicit Grid

Hector Sosa — Wed, 05 Oct 2022 12:21:51 +0000

Grid is a two-dimensional layout system for the web. It excels at combining the control that explicit sizing provides with the flexibility of implicit sizing, which makes it powerful and highly responsive for layouts. A grid will typically have columns, rows, and gaps (commonly referred to as gutters) between each of them.

What can you do with Grid?

You can choose how to size row and column tracks or have them react to the size of the content.
Direct children of the grid container will be automatically placed onto this grid, or place the items in the precise location that you want.
Lines and areas on the grid can be named to make placement easier.
Spare space in the grid container can be distributed between the tracks.
Grid items can be aligned within their area.

Creating a CSS Grid

Applying the display: grid CSS property to an HTML element creates a new grid formatting context for the direct children (referred to as grid items). You can define the line names and track sizing functions of grid columns and rows by using the CSS properties grid-template-columns and grid-template-rows. Let's review the following example .grid>div{Item $}*6, follow along using a CodePen pen.new:

.grid {
  display: grid;
  /* Create column templates */
  /* Where the 1st item has 100px */
  /* and the 2nd item takes the remaining */
  grid-template-columns: 100px auto;
  /* Define column and row gutters */
  gap: 1rem;
}

.grid > div {
  border: 3px dotted black;
}

Explicit vs. Implicit

Notice how we are explicitly defining the size of our columns by using grid-template-columns. By applying the CSS property grid-template-columns: 100px auto;, we are explicitly defining the 1st and 2nd column of our grid, then all of the remaining columns are explicitly defined the same.

So if we aren't using grid-template-rows for our rows, how is Grid defining them? This is exactly how the explicit vs. the implicit grid works. By default, Grid is creating our row tracks (or any of the undefined tracks) implicitly and auto sizing them unless defined otherwise. To define a size for our implicit grid tracks we can use the CSS property grid-auto-columns and grid-auto-rows. Try the following change in our CSS:

.grid {
  display: grid;
  grid-template-columns: repeat(2, 1fr);
  /* Create row templates */
  /* Where the 1st row is explicitly */
  /* the rest will be defined implicitly by Grid */
  grid-template-rows: auto;
  /* Define a size for the implicitly defined tracks */
  /* Where they are all set to 100px instead of auto */
  grid-auto-rows: minmax(100px, auto);
  gap: 1rem;
}

.grid > div {
  border: 3px dotted black;
}

You decide what makes sense to define explicitly or implicitly in your grid depending on your design needs. Before we even question how repeat() or minmax() work and what are CSS Functions, let's use create a real life example using what we've covered. Let's create a simple profile card.

<div class="grid">
  <div>avatar</div>
  <img src="https://avatars.githubusercontent.com/ekqt" alt="Hector Sosa" />
  <div>name</div>
  <div>Hector Sosa</div>
  <div>bio</div>
  <div>From 🇭🇳</div>
  <div>location</div>
  <div>Prague, Czech Republic</div>
</div>
<style>
  .grid {
    width: min(100% - 1rem, 30rem);
    margin: 4rem auto;
    font-family: monospace;
    /* Grid Styling */
    display: grid;
    grid-template-columns: 1fr 3fr;
    grid-auto-rows: minmax(50px, auto);
    gap: 1rem;
  }

  .grid>div {
    border: 1px solid lightgray;
    border-radius: 0.5rem;
    padding: 1rem;
  }

  .grid>div:nth-child(odd) {
    text-align: right;
  }

  .grid>img {
    max-height: 100px;
    border-radius: 100%;
  }
</style>

Create a quick CodePen by going to pen.new, paste the snippet and try changing the grid-related CSS properties to experiment with them. This is just an example, notice the heavy use of <div/>, IRL make sure you make your best effort in writing Semantic HTML.

Originally published: CSS Grid - Explicit vs Implicit Grid

Mapping request paths using Next.js

Hector Sosa — Fri, 30 Sep 2022 12:01:34 +0000

Inside your Next.js application, your next.config.js file is a regular Node module used by the server and build phases where you can configure rewrites and redirects for your application. What's the difference between them?

Rewrites allow you to map a request path to a different destination as a URL proxy (masking the destination path, without changing the User's location at all). In contrast, redirects will reroute you to a new page fully disclosing the destination URL.

Both of them are async functions that return at least an array of objects that require the following key-value pairs: source, destination, permanent (only for redirects). Rewrites can be incredibly useful to temporarily map old paths: /old-blog/:slug to /new-blog/:slug ensuring there are no broken links in your application. However, let's say if you'd want to map /github to your GH profile. Here, you'd use a redirect instead.

/*** next.config.js ***/
module.exports = {
  async redirects() {
    return [
      {
        source: '/github',
        // `source` type `String` - is the incoming request path pattern
        destination: 'https://github.com/ekqt',
        // `destination` type `String` - is the path you want to route to
        permanent: true,
        // `permanent` type `Boolean` Only for Redirects
        // `true` will use 308 to cache the redirect
        // `false` will use 307 as temporary
      },
    ]
  },
}

Vercel also offers a solution for redirects and rewrites within their vercel.json Project config file. Here, redirects and rewrites are framework agnostic. You can use them with any framework supported on their platform. However, in case of a Next.js application, Vercel recommends framework level redirects as they do have precedence over platform level redirects. Here's Lee Rob's project config file.

What about subdomains?

With subdomains such as subdomain.domain.com, Vercel explains this incredibly easy (here's their redirecting subdomain guide). In short, let's say you want to rewrite app.acme.com to acme.com/app, you'll need to configure a rewrite making use of the has field.

/*** vercel.json ***/
{
  "rewrites": [
    // Requests to app.acme.com, will be rewritten to acme.com/app.
    {
      "source": "/:path*",
      "has": [
        {
          "type": "host",
          "value": "app.acme.com"
        }
      ],
      "destination": "/app/:path*"
    }
  ]
}

Originally published: Mapping request paths using Next.js

Learn the Basics - GitHub's CLI

Hector Sosa — Thu, 22 Sep 2022 11:37:21 +0000

GitHub CLI, or gh, is a free and open source tool that enables you to use GitHub's pull requests, issues, repositories and more directly from your command line. gh is available via Homebrew by running the command brew install gh.

You are working in one of your projects, where you will create (a) an issue, (b) a branch and (c) a pull request to (d) merge changes into your main production branch. We will explore these gh commands straight from its Manual.

Creating an issue

GitHub Issues helps you to track ideas, feedback, tasks, bugs and plan for your work right where development takes place.

## Other available flags
## -a --assignee <login> // Use "@me" to self-assign
## -l --label <name> // Check your pre-defined labels

$ gh issue create --t "My new issue"  --b "Here are more details." 

## Add the web flag at the end to open the draft before submitting
## -w --web

Creating a branch to work on an issue

If you used the --web flag, you can create a branch to work on an issue directly from the issue page by clicking under Development > Create a branch. Once the branch is created, to start working, you can checkout the branch in your local repository:

$ git fetch origin
$ git checkout <branch_name>

## Can verify by running
$ git branch

This is incredibly useful and convenient because this links any pull request created for that branch, where successfully merging that PR will replace the relationship (from branch to PR) and automatically close the issue.

Creating a pull request to review your work

You finished and committed your work. now you're ready to create a PR. Pull requests (PR) lets you discuss and review potential changes before (if 'LGTM') merging them into production. I would recommend creating your PR interactively. For more information on the available flags, visit CLI Manual: PR Create

## I would recommend creating your PR Interactively
## This will give you access to nano to write better notes
$ gh pr create
? Title <title>
? Body [(e) to launch nano, enter to skip]
## After editing the body it will display as <Received>

## Once created, you can view and access the PR by running:
$ gh pr list
$ gh pr <number> --web

Merging your changes to production

Once the changes you've made on your head branch are ready to be merged into the main (base) branch, you are ready to push your code to production.

## --delete-branch: will delete the local and remote branch after merge
## --merge: will merge the commits with the base branch
$ gh pr merge <number> --body <text> --delete-branch --merge

# If no argument, the PR that belongs to the current branch is selected.

Immediately after this, (a) your issue will be marked as closed, (b) the local and remote development branch will be deleted and your (c) commit change merged into the main branch. For more information on visit GitHub's documentation: Collaborating with pull requests.

Originally published: Learn the Basics — GitHub’s CLI

No-brainer Dark Mode for Next.js

Hector Sosa — Sun, 18 Sep 2022 22:57:45 +0000

TIL: @pacocoursey next-themes. I've been pretty happy using @tailwindCSS and letting the system render the right theme for the user, but if you do want to add UI controls. Give this no-brainer a shot, here's how I did mine.

Set the provider and attribute to display the active theme as a class. This will enable all dark classes present in the HTML tree. Don't forget to declare this in your @tailwindCSS config file: module.exports = { darkMode: 'class' }:

import { ThemeProvider } from "next-themes";
import type { AppProps } from "next/app";

function MyApp({ Component, pageProps }: AppProps) {
    return (
        <ThemeProvider attribute="class">
                <Component {...pageProps} />
        </ThemeProvider>
    );
}

To consume and toggle the UI, use their useTheme hook. To avoid hydration errors, return a loading state of your choice until fully mounted:

import { useState, useEffect } from "react";
import { useTheme } from "next-themes";

import { SunIcon, MoonIcon } from "@heroicons/react/outline";

export default function ThemeToggler() {
    const { resolvedTheme, setTheme } = useTheme();
    const [mounted, setMounted] = useState(false);

    useEffect(() => { setMounted(true) }, []);

    if (!mounted) return <></>;

    return (
        <button
            onClick={() => {
                setTheme(resolvedTheme === "dark" ? "light" : "dark");
            }}
        >
            {resolvedTheme === "dark" ? <SunIcon /> : <MoonIcon />}
        </button>
    );
}

It is that simple. It has 74,528 weekly npm downloads and if it's good enough for @leeerob, it's good for me too. Get creative with your loading state and toggle button (or not && KISS). Check out their next-themes GH repo for more info.

Originally published: No-brainer Dark Mode for Next.js

Forem: Hector Sosa

Caching Shiki for Faster Build Times

Introduction

How does it work?

What are the easiest customizations you can use?

Using CSS variables for theming

Using custom renderers and CSS counters for line numbers

Faster build times

A word on Shiki's explanations

Final thoughts

An invitation to OSS Contributors for Screenshot

How does it work?

What's under the hood?

Share your feedback

Contributing

Building React Hooks - Copy to Clipboard

Why Custom React Hooks?

How to use Clipboard.writeText()

Creating a Custom Hook

Is there a one-size-fits-all design approach?

Bonus Hook - Set and Clear Timeouts

Wrapping up

Understanding Buttons and Links from Zero

Buttons vs Links

What to consider - Buttons and Links

Creating a Button Component

Creating a Link Component

Understanding Suspense with Next 13

Where does Suspense fit in all this?

How does it work?

What are the biggest perks of using Suspense in React 18?

How to use Suspense in Next 13?

Main takeaways

Shipping Zero JavaScript with Astro

Astro's biggest perks

What's in the menu for today?

Build a Tiny Calendar without Flex or useState

Getting started with Day.js

Building our Calendar using CSS Grid and TailwindCSS

Using Reducers to Manage State

Avoiding Additional Renders

Nice things to add

tRPC: Understanding Typesafety

How does tRPC share types between client/server?

Using your new tRPC-backend on the client

More examples of tRPC usage

How can we use procedures?

What about Mutations?

So WIFY by using tRPC?

CSS Grid - Explicit vs Implicit Grid

What can you do with Grid?

Creating a CSS Grid

Explicit vs. Implicit

Mapping request paths using Next.js

What about subdomains?

Learn the Basics - GitHub's CLI

Creating an issue

Creating a branch to work on an issue

Creating a pull request to review your work

Merging your changes to production

No-brainer Dark Mode for Next.js

How to use `Clipboard.writeText()`