<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>barney&apos;s tech blog</title>
<link>https://southcla.ws</link>
<description>I&apos;m a multidisciplinary maker. this site is a never-ending exploration into the details. aka southclaws.</description>
<language>en</language>
<atom:link href="https://southcla.ws/rss.xml" rel="self" type="application/rss+xml" />
<item>
<title>How to implement server side logout in Next.js app directory</title>
<link>https://southcla.ws/how-to-implement-logout-nextjs-cache-revalidate</link>
<guid isPermaLink="true">https://southcla.ws/how-to-implement-logout-nextjs-cache-revalidate</guid>
<pubDate>Wed, 02 Oct 2024 00:00:00 GMT</pubDate>
<description>&lt;p&gt;I recently rewrote a couple naively implemented &amp;quot;logout&amp;quot;/&amp;quot;sign out&amp;quot; buttons in Next.js applications (both using the &amp;quot;App directory&amp;quot; setup) and it took enough frustration, digging and non-obvious documentation to convince me I needed to write a short guide for anyone else unfortunate enough to get trapped in this enigma.&lt;/p&gt;
&lt;h2&gt;Standard setup&lt;/h2&gt;
&lt;p&gt;I build all sites and apps with the most securely configured cookies by default, no local storage Authorization bearer tokens, cookies use what browsers are already good at without the need to reinvent the wheel. It&amp;#x27;s very rare you actually need to take full control of session tokens with custom fetch headers and local storage implementations. Use-cases exist, but with additional contextual and specific requitements.&lt;/p&gt;
&lt;p&gt;I also have very bad internet, so I frequently interact with pages before JS has loaded. Logging out is an absolute basic fundamental and should not require me to wait (sometimes tens of) seconds before I can action it.&lt;/p&gt;
&lt;p&gt;So the solution needs to:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Work with server-side cookies, no JavaScript cookie access or client-side logic&lt;/li&gt;
&lt;li&gt;Correctly flush the cache and trigger revalidation&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;What you&amp;#x27;re here for, the solution&lt;/h2&gt;
&lt;p&gt;No recipe-blog-life-story for SEO, here&amp;#x27;s the solution, I&amp;#x27;ll leave my yapping for after.&lt;/p&gt;
&lt;h3&gt;Don&amp;#x27;t use Next.js &lt;code&gt;&amp;lt;Link&amp;gt;&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Before you get to the actual handler, please be aware that you &lt;em&gt;cannot&lt;/em&gt; use the Next.js &lt;code&gt;next/link&lt;/code&gt; anchor tag to link to &lt;code&gt;/logout&lt;/code&gt;. The reason for this is, in Next.js&amp;#x27; infinite wisdom, &lt;code&gt;&amp;lt;Link&amp;gt;&lt;/code&gt; tags are clever and will trip you up. Don&amp;#x27;t get me wrong, their functionality is amazing at providing smooth app experiences, but they should only be used for navigating between pages in the authenticated experience. In order for &lt;code&gt;/logout&lt;/code&gt; to work, we need a normal HTML page transition that triggers a full page reload.&lt;/p&gt;
&lt;p&gt;The full page reload is actually what makes &lt;code&gt;revalidatePath&lt;/code&gt; work as expected. Without this, yes the page &lt;em&gt;is&lt;/em&gt; revalidated, but if you &lt;a href=&quot;https://nextjs.org/docs/app/api-reference/functions/revalidatePath&quot;&gt;check the docs&lt;/a&gt; for this API, it notes that it only takes effect on the &lt;em&gt;next&lt;/em&gt; page load. Since you&amp;#x27;re (probably) already within a Layout component and not moving to a different layout component, it won&amp;#x27;t refresh. This is the bit that took me ages to realise.&lt;/p&gt;
&lt;pre class=&quot;language-html&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;a&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;href&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;/logout&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;Logout&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;a&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;Route handler&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;app/logout/route.ts&lt;/code&gt;: which maps to &lt;code&gt;https://yoursite.com/logout&lt;/code&gt;&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; revalidatePath &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;next/cache&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; cookies &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;next/headers&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; NextResponse &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;next/server&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;token comment&quot;&gt;// Your frontend&apos;s address: http://localhost:3000 or https://my.production.domain.com&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token constant&quot;&gt;WEB_ADDRESS&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; process&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;env&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token constant&quot;&gt;NEXT_PUBLIC_WEB_ADDRESS&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;token comment&quot;&gt;// Your cookie&apos;s name, usually specified by the backend.&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; cookieName &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;my-app-session&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token constant&quot;&gt;GET&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token comment&quot;&gt;// Tell Next.js to purge the entire cache, no stale data should stay after the redirect back to the index page.&lt;/span&gt;
  &lt;span class=&quot;token function&quot;&gt;revalidatePath&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;/&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;layout&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token comment&quot;&gt;// You can redirect back to the index, or to another page such as /login&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; destination &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token template-string&quot;&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;&lt;span class=&quot;token constant&quot;&gt;WEB_ADDRESS&lt;/span&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;/&lt;/span&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token comment&quot;&gt;// Clear the session cookie explicitly. Generally this can be done by just&lt;/span&gt;
  &lt;span class=&quot;token comment&quot;&gt;// using Set-Cookie: &amp;#x3C;cookie-name&gt;=; but Next.js gives us an API to do it.&lt;/span&gt;
  &lt;span class=&quot;token function&quot;&gt;cookies&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;delete&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;cookieName&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; NextResponse&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;redirect&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;destination&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    headers&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
      &lt;span class=&quot;token comment&quot;&gt;// Some browsers accept this directive to clear cookies and other data.&lt;/span&gt;
      &lt;span class=&quot;token string-property property&quot;&gt;&quot;Clear-Site-Data&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token template-string&quot;&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;*&quot;&lt;/span&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;

      &lt;span class=&quot;token comment&quot;&gt;// Next.js accepts this directive to clear its own client fetch cache.&lt;/span&gt;
      &lt;span class=&quot;token string-property property&quot;&gt;&quot;Cache-Control&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;no-store&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Why and how I got here&lt;/h2&gt;
&lt;p&gt;The apps I&amp;#x27;m working on make use of a few Next.js features that made this whole ordeal more confusing than it should be. Regardless, the solution above will work for all scenarios, but I&amp;#x27;m documenting how I got here for:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;if any poor victims of Next.js are desperately searching the same keywords I was, and;&lt;/li&gt;
&lt;li&gt;there were many red herrings along the way, and a lack of clear documentation or examples made it difficult to determine the root cause&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;Parallel routes and conditional auth-based rendering&lt;/h3&gt;
&lt;p&gt;I make use of parallel routes in order to provide a different experience for the &lt;code&gt;/&lt;/code&gt; index page based on whether or not you&amp;#x27;re logged in. A fairly standard approach ranging from changing a navigation item between &amp;quot;Login/Sign up&amp;quot; and &amp;quot;Your dashboard/profile/account/etc&amp;quot; to rendering an entirely different page, much like Linear.app, Vercel.com and GitHub.com - visiting the &lt;code&gt;/&lt;/code&gt; index page on these sites will either drop you onto their marketing landing page or your account&amp;#x27;s dashboard, ther&amp;#x27;es no separate &lt;code&gt;/dashboard&lt;/code&gt; route, it&amp;#x27;s all on the home page.&lt;/p&gt;
&lt;p&gt;Which is a nice user experience, I log in once and then always navigate to the root when I need to use the tool.&lt;/p&gt;
&lt;p&gt;This throws a bit of a spanner in the works for revalidation, and was a source of a bit of confusion.&lt;/p&gt;
&lt;p&gt;So, to refresh on &lt;a href=&quot;https://nextjs.org/docs/app/building-your-application/routing/parallel-routes&quot;&gt;Next.js documentation&lt;/a&gt;, here&amp;#x27;s the deal:&lt;/p&gt;
&lt;p&gt;You have a root &lt;code&gt;layout.tsx&lt;/code&gt; and two folders, &lt;code&gt;@authenticated&lt;/code&gt; and &lt;code&gt;@guest&lt;/code&gt;. The guest route renders your marketing site, and the authenticated route renders your dashboard/feed/whatever logged-in users see.&lt;/p&gt;
&lt;p&gt;Next.js will scan the root &lt;code&gt;app/&lt;/code&gt; folder for folders prefixed with &lt;code&gt;@&lt;/code&gt; and pass them as &lt;code&gt;ReactNode&lt;/code&gt; props to the root layout.&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;default&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;RootLayout&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  guest&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  authenticated&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; Readonly&lt;span class=&quot;token operator&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  guest&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; React&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;ReactNode&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  authenticated&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; React&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;ReactNode&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And then you conditionally render these based on some logic, most likely a call to your API to check if the user is logged in. You can also check if a cookie is present and skip the API call, but this can cause issues because a cookie being &lt;em&gt;present&lt;/em&gt; does not necessarily mean a &lt;em&gt;session&lt;/em&gt; is present. A cookie can contain anything, usually some sort of encrypted or signed token. But you really need to actually talk to the API to &lt;em&gt;validate&lt;/em&gt; that token, it may have expired, become malformed or become invalid by some other means.&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; session &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;getSession&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token comment&quot;&gt;// Valid session? Show the user their dashboard&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;session&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;main&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;authenticated&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;main&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

  &lt;span class=&quot;token comment&quot;&gt;// No session? Show the marketing/landing page.&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;main&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;guest&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;main&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Why this is relevant to the logout debacle is for two reasons:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Revalidation: This root layout will not re-validate unless you fully refresh the app&lt;/li&gt;
&lt;li&gt;Parallel rendering: You may see a blank page if this branching logic gets confused&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;So, a brief overview of the footguns.&lt;/p&gt;
&lt;h4&gt;Revalidation&lt;/h4&gt;
&lt;p&gt;When you call &lt;code&gt;revalidatePath(&amp;quot;/&amp;quot;, &amp;quot;layout&amp;quot;)&lt;/code&gt; in the &lt;code&gt;/logout&lt;/code&gt; handler, you might, as I did, expect this to trigger this root layout to re-render and this call &lt;code&gt;getSession&lt;/code&gt; again, fail and render the guest route. This was not the case, &lt;em&gt;sometimes&lt;/em&gt;... I thought I had cracked it at one point, but it turns out caching is hard (who knew!?) so sometimes this would work, other times it wouldn&amp;#x27;t.&lt;/p&gt;
&lt;p&gt;Dropping a &lt;code&gt;console.log&lt;/code&gt; into this root layout will confirm it doesn&amp;#x27;t re-render. Even if the &lt;code&gt;/logout&lt;/code&gt; handler redirected to a different page, such as &lt;code&gt;/login&lt;/code&gt; it would usually not cause a re-render. The times when it does re-render are simply due to timing out the max-age, pure fluke.&lt;/p&gt;
&lt;p&gt;This is something that threw me off the trail of using &lt;code&gt;&amp;lt;a&amp;gt;&lt;/code&gt; instead of &lt;code&gt;&amp;lt;Link&amp;gt;&lt;/code&gt;, I thought &lt;code&gt;revalidatePage&lt;/code&gt; was not working because in my mind, I &lt;em&gt;was&lt;/em&gt; navigating to the page again, because a 307 redirect in my mind means &amp;quot;Navigate the browser to this route&amp;quot;.&lt;/p&gt;
&lt;p&gt;What was actually happening was, Next.js was receiving that header, after not actually changing the underlying browser page being rendered and simply doing absolutely nothing. The browser did what it was told to: delete the cookie. But Next.js was going &amp;quot;I&amp;#x27;m already at &lt;code&gt;/&lt;/code&gt; so I won&amp;#x27;t do anything&amp;quot;. This caused the root layout to remain unaffected and thus never checked the session and never re-rendered the guest content.&lt;/p&gt;
&lt;h4&gt;Parallel&lt;/h4&gt;
&lt;p&gt;Parallel routes are weird. They&amp;#x27;re quite useful for advanced page transitions and conditional routing, but they only work at the root level (for now) and hold confusing semantics that go against common expectations for how browsers work (a common theme with Next.js...)&lt;/p&gt;
&lt;p&gt;In combination with the revalidation issues, this was another layer of red herring causing the browser&amp;#x27;s URL bar to change to &lt;code&gt;/login&lt;/code&gt; but no content to change.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/2024-10-02%20how-to-implement-logout-nextjs-cache-revalidate/image-3.png&quot; alt=&quot;the browser address bar showing /login but the page content did not change&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Essentially, what I understand happened was because that root layout never revalidated, it was still on the &lt;code&gt;@authenticated&lt;/code&gt; parallel route, and &lt;code&gt;/login&lt;/code&gt; does not exist within that folder. So, for unknown reasons, it simply kept the same page rendered (the &lt;code&gt;/&lt;/code&gt; index), changed the browser&amp;#x27;s address bar to show &lt;code&gt;/login&lt;/code&gt; and went to sleep.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/2024-10-02%20how-to-implement-logout-nextjs-cache-revalidate/image-1.png&quot; alt=&quot;network tab of dev tools showing two requests, one to logout and one to the index page&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;All the while, the network tab of developer tools showed everything as expected, a GET to &lt;code&gt;/logout&lt;/code&gt;, a redirect header, a &lt;code&gt;GET&lt;/code&gt; to &lt;code&gt;/login&lt;/code&gt; but... wait&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/2024-10-02%20how-to-implement-logout-nextjs-cache-revalidate/image.png&quot; alt=&quot;network tab of dev tools showing the content-type header as text/x-component&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;What on earth is &lt;code&gt;text/x-component&lt;/code&gt;?&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/2024-10-02%20how-to-implement-logout-nextjs-cache-revalidate/image-2.png&quot; alt=&quot;the response body of the text/x-component request shows some proprietary Next.js format data&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;That&amp;#x27;s not a HTML page, that&amp;#x27;s a Next.js internal thing, it&amp;#x27;s &lt;em&gt;describing&lt;/em&gt; a page, but it&amp;#x27;s not an actual page.&lt;/p&gt;
&lt;p&gt;From what I can gather, this was Next.js skipping an unnecessary page transition as well as getting confused with parallel routes due to the root layout continuing to render a route group that did not contain a &lt;code&gt;/login&lt;/code&gt; route, because that only exists within &lt;code&gt;@guest&lt;/code&gt;.&lt;/p&gt;
&lt;h3&gt;Blessing, curse, pick your poison, in too deep to quit?&lt;/h3&gt;
&lt;p&gt;(not relevant, but also not quite a rant about Next.js)&lt;/p&gt;
&lt;p&gt;I love Next.js, I&amp;#x27;ve used it since almost the first release, it changed how I build websites and webapps and solved enough of the React boilerplate back then (~2016/7 I think?) that it allowed me to focus on design, experience and product.&lt;/p&gt;
&lt;p&gt;All the companies I&amp;#x27;ve worked with, products I&amp;#x27;ve built, I&amp;#x27;ve used, recommended or migrated to Next.js and every time it&amp;#x27;s been a positive choice for everyone involved.&lt;/p&gt;
&lt;p&gt;But, and I echo the sentiment of much of the major discourse I see around the product, it&amp;#x27;s getting &lt;em&gt;really&lt;/em&gt; complicated. App directory was a big step towards that complication.&lt;/p&gt;
&lt;p&gt;And I like the app-directory setup, it&amp;#x27;s a mental model I can get behind. Metadata, opengraph, caching, swr, are all tools I use on every product I build and it&amp;#x27;s all very easy once you figure out the weirdness. And that&amp;#x27;s the problematic part that&amp;#x27;s making me recommend Next.js to others less and less.&lt;/p&gt;
&lt;h4&gt;Abstractions leakier than a screen door on a submarine&lt;/h4&gt;
&lt;p&gt;After so many years of using this framework, I&amp;#x27;m still hit with poorly written (or empty) error messages, compiled JS stack traces that are completely useless to me, lack of context and generally just leaky abstractions all around.&lt;/p&gt;
&lt;p&gt;React is an abstraction over HTML, and Next.js is an abstraction over React. On top of that you&amp;#x27;ve got TypeScript, JSX and polyfill/ES version transpilation. A lot gets lost in translation and invalid states are too easy to get into.&lt;/p&gt;
&lt;p&gt;And then on top of all of that, the novel behaviours and APIs that Next.js provides need to be thoroughly documented because Vercel has seemingly infinite &lt;a href=&quot;https://mcfunley.com/choose-boring-technology&quot;&gt;innovation tokens&lt;/a&gt;. And when you end up in a rabbithole of 3 very specific Next.js-only scenarios, all working together in subtle ways to fuck your day up, &lt;a href=&quot;https://nextjs.org/docs/app/building-your-application/caching&quot;&gt;a 4,000 word essay on cache logic&lt;/a&gt; is not really what you have the energy to sit down and absorb.&lt;/p&gt;
&lt;p&gt;Documenting software is hard, I&amp;#x27;m not criticising the Next.js team because the documentation is actually very good. But there are enough permutations of new behaviours, leaky abstractions, intertwining systems that the underlying surface area becomes so complex that you simply cannot document every possible case. And at that point, perhaps the system itself is just &lt;em&gt;too complex&lt;/em&gt;.&lt;/p&gt;
&lt;p&gt;I love Next.js, or at least I&amp;#x27;ve developed stockholm syndrome because I don&amp;#x27;t have the time or energy to framework-hop. I&amp;#x27;m in too deep.&lt;/p&gt;</description>
</item>
<item>
<title>How to customise image layouts in Markdown with Next.js</title>
<link>https://southcla.ws/how-to-customise-markdown-images-mdx-nextjs</link>
<guid isPermaLink="true">https://southcla.ws/how-to-customise-markdown-images-mdx-nextjs</guid>
<pubDate>Sat, 27 Apr 2024 00:00:00 GMT</pubDate>
<description>&lt;p&gt;Markdown has somehow become the defacto document standard in the tech world. It&amp;#x27;s quite simple, has no real specification (as far as I know) but despite that has become a success for blogs (like this one) technical documentation and even entire websites.&lt;/p&gt;
&lt;p&gt;But formatting options are quite limited - by design. You can do the basics like bold, italics, etc. but no colours, no highlights and certainly no alignment or advanced layouts.&lt;/p&gt;
&lt;p&gt;Traditionally, &amp;quot;Word Processing&amp;quot; or digital documents have provided all of these features as well as many more.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-27-13-47-50.png&quot; alt=&quot;2024-04-27-13-47-50&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;HTML lets you do most of this, sometimes with a bit of fighting against CSS, but for the most part you can essentially construct almost any layout you can imagine using the tools of the web.&lt;/p&gt;
&lt;p&gt;Markdown is significantly disadvantaged due to its syntax, which isn&amp;#x27;t a bad thing, Markdown is actually readable when in its non-rendered form (plain text) while HTML is far from that. But we can balance that readability with new functionality without harming the plain-text version or the ease of authorship (like how I&amp;#x27;m writing this into a plain text document without the need for a Word equivalent.)&lt;/p&gt;
&lt;h2&gt;The tools at play&lt;/h2&gt;
&lt;p&gt;Next.js is in the title so that one is obvious.&lt;/p&gt;
&lt;p&gt;For this blog and content-heavy sites I build, I use Hashicorp&amp;#x27;s Next.js MDX library:&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://github.com/hashicorp/next-mdx-remote/&quot;&gt;https://github.com/hashicorp/next-mdx-remote/&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;Which is amazingly useful and a must-have if you&amp;#x27;re building a Next.js site with Markdown. This is what it looks like:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token comment&quot;&gt;// Read the text from a Markdown file, or a database, or whatever.&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; source &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;readFile&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;fullpath&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;token comment&quot;&gt;// Parse the text into a structure&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; content&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; frontmatter &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;compileMDX&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  source&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  options&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    parseFrontmatter&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;

  &lt;span class=&quot;token comment&quot;&gt;// Customise what your p tags, h tags, a tags, etc should render as.&lt;/span&gt;
  components&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token function-variable function&quot;&gt;img&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;props&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&gt;&lt;/span&gt; &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;MyCustomImage&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token spread&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;props&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;/&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;token comment&quot;&gt;// Pass the structured content and metadata to a React component and render it&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;h1&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;frontmatter&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;title&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;h1&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;article&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;content&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;article&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I&amp;#x27;m also using Panda CSS but that&amp;#x27;s largely irrelevant here, you can use any styling tool you like as next-mdx-remote provides you the ability to set class names and custom component overrides for any block or inline element.&lt;/p&gt;
&lt;h2&gt;Hacking markdown&lt;/h2&gt;
&lt;p&gt;In the example above, I&amp;#x27;ve shown you can also override any of the regular HTML components with your own React components. For this, we&amp;#x27;ll override &lt;code&gt;img&lt;/code&gt; and provide our own.&lt;/p&gt;
&lt;pre class=&quot;language-js&quot;&gt;&lt;code&gt;&lt;span class=&quot;token literal-property property&quot;&gt;components&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token function-variable function&quot;&gt;img&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token parameter&quot;&gt;props&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&gt;&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;&amp;#x3C;&lt;/span&gt;MyCustomImage &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;props&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;/&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;What we&amp;#x27;re going to do is provide a way for our Markdown code to specify an image size and a float alignment property without introducing any custom parsing logic or new syntax.&lt;/p&gt;
&lt;p&gt;If I write the following Markdown:&lt;/p&gt;
&lt;pre class=&quot;language-markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;token url&quot;&gt;&lt;span class=&quot;token operator&quot;&gt;!&lt;/span&gt;[&lt;span class=&quot;token content&quot;&gt;this is my alt text&lt;/span&gt;](&lt;span class=&quot;token url&quot;&gt;/this-is-my-image.png&lt;/span&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then the &lt;code&gt;MyCustomImage&lt;/code&gt; component receives the following props:&lt;/p&gt;
&lt;pre class=&quot;language-json&quot;&gt;&lt;code&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;src&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;/this-is-my-image.png&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;alt&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;this is my alt text&quot;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The alt text is the key here, it doesn&amp;#x27;t &lt;em&gt;need&lt;/em&gt; to be used for alt text, it can be used as a portal from Markdown world to React world!&lt;/p&gt;
&lt;p&gt;What if we passed in a URL-encoded string?&lt;/p&gt;
&lt;pre class=&quot;language-markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;token url&quot;&gt;&lt;span class=&quot;token operator&quot;&gt;!&lt;/span&gt;[&lt;span class=&quot;token content&quot;&gt;size=small&amp;#x26;align=right&amp;#x26;alt=&quot;this is my alt text&quot;&lt;/span&gt;](&lt;span class=&quot;token url&quot;&gt;/this-is-my-image.png&lt;/span&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then, within &lt;code&gt;MyCustomImage&lt;/code&gt; we can parse the &lt;code&gt;alt&lt;/code&gt; prop with &lt;code&gt;URLSearchParams&lt;/code&gt;:&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; options &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;token class-name&quot;&gt;URLSearchParams&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;alt&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;We can then read the values in &lt;code&gt;options&lt;/code&gt; and do what we need:&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; size &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; options&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;size&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; align &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; options&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;align&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; alt &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; options&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;alt&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And we still have the ability to use alt text for accessibility purposes, which is neat.&lt;/p&gt;
&lt;p&gt;Here&amp;#x27;s an example, the following Markdown:&lt;/p&gt;
&lt;pre class=&quot;language-markdown&quot;&gt;&lt;code&gt;&lt;span class=&quot;token url&quot;&gt;&lt;span class=&quot;token operator&quot;&gt;!&lt;/span&gt;[&lt;span class=&quot;token content&quot;&gt;size=small&amp;#x26;align=right&amp;#x26;caption=&quot;isn&apos;t this neat?&quot;&lt;/span&gt;](&lt;span class=&quot;token url&quot;&gt;/images/2024-04-27-14-12-15.png&lt;/span&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Renders the following image:&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-27-14-12-15.png&quot; alt=&quot;isn&amp;#x27;t this neat?&quot;/&gt;&lt;br/&gt;&lt;em&gt;isn&amp;#x27;t this neat?&lt;/em&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Due to the following rules:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;options.size&lt;/code&gt; drives the max-width&lt;/li&gt;
&lt;li&gt;&lt;code&gt;options.align&lt;/code&gt; drives the container&amp;#x27;s align-items property
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;left&lt;/code&gt; maps to &lt;code&gt;start&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;center&lt;/code&gt; maps to &lt;code&gt;center&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;right&lt;/code&gt; maps to &lt;code&gt;end&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;code&gt;options.caption&lt;/code&gt; renders a &lt;code&gt;&amp;lt;p&amp;gt;&lt;/code&gt; below with the caption text
&lt;ul&gt;
&lt;li&gt;I&amp;#x27;m also re-using the caption for the &lt;code&gt;&amp;lt;img&amp;gt;&lt;/code&gt; alt-text value.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Annoyingly, because of the resulting HTML structure from MDX, you can&amp;#x27;t use float layouts for laying images beside and interspersed with text easily. This is because for float layouts to work, the image needs to be placed either immediately beside or inside the paragraph you want to intersperse with, and MDX currently renders them as completely separate paragraph elements:&lt;/p&gt;
&lt;pre class=&quot;language-html&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;p&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;div&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
        &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;img&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;alt&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;isn&apos;t this neat?&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;src&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;/images/2024-04-27-14-12-15.png&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
        &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;aside&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;isn&apos;t this neat?&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;aside&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;div&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;p&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;p&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
    The text in the paragraph
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;p&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;There will be a workaround for this but it would likely involve messing with the underlying AST.&lt;/p&gt;
&lt;p&gt;Anyway, that&amp;#x27;s the trick, and you could use this for anything really such as adding links to images or applying effects.&lt;/p&gt;
&lt;p&gt;However, it&amp;#x27;s worth considering that there&amp;#x27;s a limit when it comes to readability and at some point, you might be best to just set up a custom component and use that in your document.&lt;/p&gt;</description>
</item>
<item>
<title>Colour Ramps with Panda CSS</title>
<link>https://southcla.ws/colour-ramps-with-panda-css</link>
<guid isPermaLink="true">https://southcla.ws/colour-ramps-with-panda-css</guid>
<pubDate>Sat, 27 Apr 2024 00:00:00 GMT</pubDate>
<description>&lt;p&gt;Tailwind, Chakra, Panda, all these frameworks and more all come with colour tokens structured with a colour name and a number usually ranging from around 50 to 900 in increments of 100.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-27-11-44-05.png&quot; alt=&quot;Some of Tailwind&amp;#x27;s colour tokens&quot;/&gt;&lt;br/&gt;&lt;em&gt;Some of Tailwind&amp;#x27;s colour tokens&lt;/em&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-27-11-44-32.png&quot; alt=&quot;Some of Chakra UI&amp;#x27;s colour tokens&quot;/&gt;&lt;br/&gt;&lt;em&gt;Some of Chakra UI&amp;#x27;s colour tokens&lt;/em&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;And these are incredibly useful when getting started on a new project. No need to set up your own swatches for the basics.&lt;/p&gt;
&lt;p&gt;Panda CSS also comes with a default theme with lots of colours following this convention of &lt;code&gt;colour.level&lt;/code&gt; where lower levels are generally towards the lighter, pastel side and higher levels are more vibrant or darker.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://panda-css.com/docs/customization/theme&quot;&gt;https://panda-css.com/docs/customization/theme&lt;/a&gt;&lt;/p&gt;
&lt;h2&gt;Skating your own ramp&lt;/h2&gt;
&lt;p&gt;The bundled colours in these frameworks are useful, but eventually you&amp;#x27;ll need to do your own. Whether it&amp;#x27;s a brand specific colour, a strict design system or you just have an eye for detail.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-27-12-04-22.png&quot; alt=&quot;I skateboarded for about a year and I did not become cooler...&quot;/&gt;&lt;br/&gt;&lt;em&gt;I skateboarded for about a year and I did not become cooler...&lt;/em&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;One way of doing this would be to simply loop through some hue values and generate a set of &lt;code&gt;hsl()&lt;/code&gt; or &lt;code&gt;lch()&lt;/code&gt; strings but you will run into differences with perceived lightness.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://nerdy.dev/lch-luminance-vs-hsl-lightness&quot;&gt;https://nerdy.dev/lch-luminance-vs-hsl-lightness&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;I used this looping technique with LCH on Storyden for the accent colour, the administrator can choose a hue to represent their site and the code generates a colour ramp for that hue. This colour can then be used in various places such as buttons and the ramp is used for different states (for example an active button may be darker and a hovered button may be lighter.)&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; flatRamp &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; ramp&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;reduceRight&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;o&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; r&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; i&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;minL&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; maxL&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; flatClampL&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;minC&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; maxC&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; flatClampC&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token constant&quot;&gt;L&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; minL &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;maxL &lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt; minL&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;/&lt;/span&gt; rampSize&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; i &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; flatContrast&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token constant&quot;&gt;C&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; minC &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;maxC &lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt; minC&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;/&lt;/span&gt; rampSize&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; i&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; fill &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token template-string&quot;&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;oklch(&lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;&lt;span class=&quot;token constant&quot;&gt;L&lt;/span&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;% &lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;&lt;span class=&quot;token constant&quot;&gt;C&lt;/span&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;% &lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;hue&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;deg)&lt;/span&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; text &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;readableColorWithFallback&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;token function&quot;&gt;parseColourWithFallback&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;fill&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;to&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;srgb&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;toString&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; format&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;hex&quot;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token template-string&quot;&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;--accent-colour-flat-fill-&lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;r&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; fill&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token template-string&quot;&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;--accent-colour-flat-text-&lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;r&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; text&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;o&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;But there are more reasons that even this code is going to be problematic, most importantly it&amp;#x27;s using &lt;code&gt;oklch&lt;/code&gt; which is very new and won&amp;#x27;t be present in older browsers, leading to a fallback colour to be painted (which is going to be very ugly!)&lt;/p&gt;
&lt;p&gt;Luckily there&amp;#x27;s a library for that!&lt;/p&gt;
&lt;h2&gt;Rampensau&lt;/h2&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-27-12-32-11.png&quot; alt=&quot;every time I hit the random button it&amp;#x27;s somehow beautiful&quot;/&gt;&lt;br/&gt;&lt;em&gt;every time I hit the random button it&amp;#x27;s somehow beautiful&lt;/em&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;I came across this a while ago, it&amp;#x27;s a beautiful tool for making colour ramps using various parameters such as basic start/end, number of swatches, max lightness, etc. but it also has advanced features such as the curve function to use which is very useful for dealing with perceived lightness issues.&lt;/p&gt;
&lt;p&gt;The best part is, it&amp;#x27;s also a JS library! That means you can import the code and generate these on the fly.&lt;/p&gt;
&lt;h2&gt;Mixing in some Panda CSS&lt;/h2&gt;
&lt;p&gt;If you don&amp;#x27;t already know about Panda CSS, it&amp;#x27;s a static CSS generation tool that integrates nicely into your codebase to provide type safe code-generated design tokens allowing you to statically declare everything at build time.&lt;/p&gt;
&lt;p&gt;The configuration is also a program in and of itself, so you can import JavaScript or TypeScript code to programmatically drive various design tokens for your site.&lt;/p&gt;
&lt;p&gt;So let&amp;#x27;s take that ramp in the screenshot above and import the code:&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; colours &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;generateColorRamp&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  total&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  hStart&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;214.716&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  hStartCenter&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;0.5&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token function-variable function&quot;&gt;hEasing&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;x&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&gt;&lt;/span&gt; x&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  hCycles&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;1.173&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;

  sRange&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token number&quot;&gt;0.852&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;0.927&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token function-variable function&quot;&gt;sEasing&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;x&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;x &lt;span class=&quot;token operator&quot;&gt;&amp;#x3C;&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;0.5&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;4&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; x &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; x &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; x &lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;1&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt; Math&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;pow&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;token number&quot;&gt;2&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; x &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  lRange&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token number&quot;&gt;0.047&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;0.979&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token function-variable function&quot;&gt;lEasing&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;x&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&gt;&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;Math&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;cos&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;Math&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token constant&quot;&gt;PI&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; x&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;/&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The types this returns is a basic &lt;code&gt;[number, number, number][]&lt;/code&gt; array which corresponds to HSL parameters.&lt;/p&gt;
&lt;p&gt;Once you have the &lt;code&gt;colours&lt;/code&gt; array you can turn that into a Panda-compatible token:&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; entries &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; colours&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;color&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; idx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; index &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; idx &lt;span class=&quot;token operator&quot;&gt;===&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;0&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;50&quot;&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; idx &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;100&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;
    &lt;span class=&quot;token template-string&quot;&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;index&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
      value&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;colorToCSS&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;color&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;hsl&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; tokens &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; Object&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;fromEntries&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;entries&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;If you inspect &lt;code&gt;tokens&lt;/code&gt;, you&amp;#x27;ll see:&lt;/p&gt;
&lt;pre class=&quot;language-js&quot;&gt;&lt;code&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;50&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(204 35% 40%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;100&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(208 34.89026063100137% 39.24615775982386%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;200&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(212 34.122085048010966% 37.075555538987224%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;300&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(216 32.03703703703704% 33.75%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;400&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(220 27.976680384087793% 29.670602220836635%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;500&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(224 22.023319615912207% 25.329397779163376%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;600&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(228 17.962962962962962% 21.250000000000004%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;700&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(232 15.877914951989025% 17.92444446101278%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;800&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(236 15.109739368998628% 15.753842240176146%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string-property property&quot;&gt;&apos;900&apos;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token literal-property property&quot;&gt;value&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&apos;hsl(240 15% 15.000000000000002%)&apos;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now all you need to do is assign that to a colour token in your Panda config:&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; defineConfig &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;@pandacss/dev&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;default&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;defineConfig&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  theme&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    extend&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
      tokens&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
        colors&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
          brand&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; tokens&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now you&amp;#x27;ll be able to use these tokens in recipes, semantic tokens, JSX props, etc:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;styled.p&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;color&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;brand.500&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
  this is the brand colour!
  &lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;br&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;/&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;styled.span&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;color&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;brand.700&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;this is a bit darker&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;styled.span&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;br&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;/&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;styled.span&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;color&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;brand.200&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;this is a bit lighter&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;styled.span&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;styled.p&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And whenever you want to play with the colours, you can just load up Rampensau&amp;#x27;s site and make more colour ramps!&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://meodai.github.io/rampensau/&quot;&gt;https://meodai.github.io/rampensau/&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;I hope this was useful, happy colouring!&lt;/p&gt;
&lt;p&gt;(By the way, there&amp;#x27;s a &lt;a href=&quot;https://southcla.ws/design&quot;&gt;secret page&lt;/a&gt; on this site that shows the colour ramps I&amp;#x27;m using! You can also &lt;a href=&quot;https://github.com/Southclaws/southcla.ws&quot;&gt;browse the source code&lt;/a&gt;.)&lt;/p&gt;</description>
</item>
<item>
<title>How to read Markdown frontmatter in Next.js edge functions</title>
<link>https://southcla.ws/nextjs-opengraph-image-markdown-frontmatter-metadata</link>
<guid isPermaLink="true">https://southcla.ws/nextjs-opengraph-image-markdown-frontmatter-metadata</guid>
<pubDate>Fri, 19 Apr 2024 00:00:00 GMT</pubDate>
<description>&lt;p&gt;`
This blog, like many others, is built on simple Markdown files. It&amp;#x27;s also built with Next.js which makes certain things really easy to achieve.&lt;/p&gt;
&lt;p&gt;One of those things is opengraph meta images. These things:&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-19-15-35-33.png&quot; alt=&quot;2024-04-19-15-35-33&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Where obviously I want to source that data from the posts themselves - the frontmatter at the top:&lt;/p&gt;
&lt;pre class=&quot;language-yaml&quot;&gt;&lt;code&gt;&lt;span class=&quot;token punctuation&quot;&gt;---&lt;/span&gt;
&lt;span class=&quot;token key atrule&quot;&gt;title&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; Fluid typography kerning in CSS
&lt;span class=&quot;token key atrule&quot;&gt;subtitle&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; Taking fluid typography one step further by meticulously controlling kerning pairs.
&lt;span class=&quot;token key atrule&quot;&gt;hero&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; /images/southclaws_purple_and_blue_mountain_scenery_behind_the_screen_i_31127cb3&lt;span class=&quot;token punctuation&quot;&gt;-&lt;/span&gt;ef1a&lt;span class=&quot;token punctuation&quot;&gt;-&lt;/span&gt;4226&lt;span class=&quot;token punctuation&quot;&gt;-&lt;/span&gt;8b16&lt;span class=&quot;token punctuation&quot;&gt;-&lt;/span&gt;15d10328e4f2.png
&lt;span class=&quot;token punctuation&quot;&gt;---&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now for the text metadata, it&amp;#x27;s quite simple:&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;generateMetadata&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;props&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; Props&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;try&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; metadata &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;getContent&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;props&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;params&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;post&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
      title&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token template-string&quot;&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;span class=&quot;token interpolation&quot;&gt;&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;${&lt;/span&gt;metadata&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;title&lt;span class=&quot;token interpolation-punctuation punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt; | barney&apos;s tech blog&lt;/span&gt;&lt;span class=&quot;token template-punctuation string&quot;&gt;`&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      description&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; metadata&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;subtitle&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;catch&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;_&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;undefined&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;You can &lt;a href=&quot;https://github.com/Southclaws/southcla.ws/blob/321bf7088f58b8e2fc3c4cb9dd43007afb689a78/src/app/(default)/(posts)/%5Bpost%5D/page.tsx#L12-L22&quot;&gt;browse the code on GitHub&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;What &lt;code&gt;getContent&lt;/code&gt; does is quite simple:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;reads the markdown file&lt;/li&gt;
&lt;li&gt;parses it using &lt;a href=&quot;https://github.com/hashicorp/next-mdx-remote&quot;&gt;next-mdx-remote&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Now I wanted to grab the title and hero image to use in the &lt;a href=&quot;https://nextjs.org/docs/app/api-reference/file-conventions/metadata/opengraph-image&quot;&gt;opengraph-image file&lt;/a&gt; which should be simple, call &lt;code&gt;getContent(props.params.post)&lt;/code&gt; with the slug extracted from the request, get the title/image and use those with &lt;a href=&quot;https://github.com/vercel/satori/&quot;&gt;Satori&lt;/a&gt; to generate an image.&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;default&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Image&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;props&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; Props&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; metadata &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;getContent&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;props&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;params&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;post&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;But when I tried this, I saw:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;Module not found: Can&amp;#x27;t resolve &amp;#x27;fs/promises&amp;#x27;
&amp;gt; 1 | import { readFile } from &amp;quot;fs/promises&amp;quot;;
    | ^
  2 | import { glob } from &amp;quot;glob&amp;quot;;
  3 | import { compileMDX } from &amp;quot;next-mdx-remote/rsc&amp;quot;;
  4 | import path from &amp;quot;path&amp;quot;;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Of course, the images are running in an &amp;quot;edge&amp;quot; context, meaning they will be deployed to serverless functions which is a slightly different environment to regular Node.js code and there are &lt;a href=&quot;https://edge-runtime.vercel.app/features/available-apis#unsupported-apis&quot;&gt;quite a few APIs missing&lt;/a&gt;. Notably this:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Native Node.js APIs are not supported. For example, you can&amp;#x27;t read or write to the filesystem&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;And of course my &lt;code&gt;getContent&lt;/code&gt; function uses a file read API which is not available in this environment.&lt;/p&gt;
&lt;h2&gt;Opt out of Edge&lt;/h2&gt;
&lt;p&gt;One way to avoid this is to simply opt out of using edge compute to render opengraph images. That&amp;#x27;s a simple solution:&lt;/p&gt;
&lt;pre class=&quot;language-ts&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; runtime &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;nodejs&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;However, I wanted to keep using edge compute for this as it does cost less and those images are generated and cached closer to readers, resulting in a faster load time.&lt;/p&gt;
&lt;h2&gt;Getting creative&lt;/h2&gt;
&lt;p&gt;I didn&amp;#x27;t want to write a whole new approach to reading the file etc, it &lt;em&gt;is&lt;/em&gt; possible via &lt;code&gt;fetch&lt;/code&gt; and &lt;code&gt;import.meta.url&lt;/code&gt; in theory but the way my blog is set up, I don&amp;#x27;t know the exact file name in advance due to how I&amp;#x27;m storing the date in the filename. So this isn&amp;#x27;t ideal.&lt;/p&gt;
&lt;p&gt;Instead, I wrote a simple API endpoint &lt;a href=&quot;https://github.com/Southclaws/southcla.ws/blob/321bf7088f58b8e2fc3c4cb9dd43007afb689a78/src/app/meta/route.ts#L10&quot;&gt;&lt;code&gt;/meta?slug=the-post-slug&lt;/code&gt;&lt;/a&gt; which just calls &lt;code&gt;getContent&lt;/code&gt; and uses the regular Node.js file system APIs that I already have.&lt;/p&gt;
&lt;p&gt;Then, when the &lt;a href=&quot;https://github.com/Southclaws/southcla.ws/blob/321bf7088f58b8e2fc3c4cb9dd43007afb689a78/src/app/(default)/(posts)/%5Bpost%5D/opengraph-image.tsx#L29&quot;&gt;opengraph-image handler&lt;/a&gt; is hit, it simply &lt;a href=&quot;https://github.com/Southclaws/southcla.ws/blob/321bf7088f58b8e2fc3c4cb9dd43007afb689a78/src/content/edge.ts#L10&quot;&gt;makes a &lt;code&gt;fetch&lt;/code&gt; call&lt;/a&gt; to this endpoint to get the metadata.&lt;/p&gt;
&lt;hr/&gt;
&lt;p&gt;Next.js is really amazing, the ability to throw these building blocks together and end up with a site that is performant is powerful.&lt;/p&gt;</description>
</item>
<item>
<title>How to diagnose Hydration failed</title>
<link>https://southcla.ws/how-to-diagnose-next-hydration</link>
<guid isPermaLink="true">https://southcla.ws/how-to-diagnose-next-hydration</guid>
<pubDate>Wed, 27 Dec 2023 00:00:00 GMT</pubDate>
<description>&lt;p&gt;This happens when the server renders one tree and the client hydrates to a different tree.&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;Hydration failed because the initial UI does not match what was rendered on the server
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The most common tutorials and even the Next.js docs talk about useEffect and mistakes relating to client/server code around interactive components.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://nextjs.org/docs/messages/react-hydration-error&quot;&gt;https://nextjs.org/docs/messages/react-hydration-error&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;One of the lesser talked about causes of this is invalid HTML. Which is actually the #1 item in the list on Next.js docs.&lt;/p&gt;
&lt;h2&gt;Why does invalid HTML cause this error?&lt;/h2&gt;
&lt;p&gt;Basically, browsers are really lenient about what they will render. So if you have invalid HTML, the browser will &lt;em&gt;not&lt;/em&gt; try to fix it for you but it &lt;em&gt;will&lt;/em&gt; try to render it for you.&lt;/p&gt;
&lt;p&gt;But the Next.js server also pre-processes the static HTML that&amp;#x27;s delivered on the server render. When it does, it seems to clean up mistakes like this. When it finds a &lt;code&gt;\&amp;lt;p\&amp;gt;&lt;/code&gt; nested within a &lt;code&gt;\&amp;lt;p\&amp;gt;&lt;/code&gt; for example, it simply moves the child to a sibling.&lt;/p&gt;
&lt;p&gt;For example, this is the resulting HTML rendered in the browser from a mistake I made in the &lt;a href=&quot;https://github.com/Southclaws/storyden&quot;&gt;Storyden&lt;/a&gt; codebase where I nested a button inside a menu trigger which is already a button:&lt;/p&gt;
&lt;pre class=&quot;language-html&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;button&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;menu::R9mnnnjbqkq::trigger&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;button&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;class&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;button&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;svg&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;...&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;svg&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;button&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;button&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is quite easy to find, React tells you with a nice message:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;Warning: Expected server HTML to contain a matching &amp;lt;button&amp;gt; in &amp;lt;button&amp;gt;.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And the reason this causes the hydration error is because this issue is actually &lt;em&gt;&amp;quot;fixed&amp;quot;&lt;/em&gt; automatically on the server render. If you disable javascript in your browser and render the nested button, you&amp;#x27;ll see:&lt;/p&gt;
&lt;pre class=&quot;language-html&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;button&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;menu::R9mnnnjbqkq::trigger&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;button&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;button&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;class&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;button&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;svg&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;...&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;svg&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;button&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The child button (the one with the class) has been shifted out of the parent button and is now a sibling. It&amp;#x27;s also a sibling with no children so if you rendered this, it would be invisible. However, it can cause layout issues because if these buttons are inside a grid or a flex container then, as children, they will contribute to layout calculations.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-27-11-49-46.png&quot; alt=&quot;2023-12-27-11-49-46&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;h2&gt;Ark menus&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;A side note about Ark menus.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;In moving from Chakra to Ark, I ran in to a couple of instances where I forgot to mark a trigger as a child component. If you don&amp;#x27;t add &lt;code&gt;asChild&lt;/code&gt;, then &lt;code&gt;MenuTrigger&lt;/code&gt; in the below example becomes a &lt;code&gt;\&amp;lt;button\&amp;gt;&lt;/code&gt; and obviously &lt;code&gt;\&amp;lt;MoreAction /\&amp;gt;&lt;/code&gt; is a button already so you end up with a nested button.&lt;/p&gt;
&lt;p&gt;Make sure you add the &lt;code&gt;asChild&lt;/code&gt; prop if you&amp;#x27;re using an existing component as a button.&lt;/p&gt;
&lt;pre class=&quot;language-diff&quot;&gt;&lt;code&gt;&lt;span class=&quot;token deleted-sign deleted&quot;&gt;&lt;span class=&quot;token prefix deleted&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;token line&quot;&gt; &amp;#x3C;MenuTrigger&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token inserted-sign inserted&quot;&gt;&lt;span class=&quot;token prefix inserted&quot;&gt;+&lt;/span&gt;&lt;span class=&quot;token line&quot;&gt; &amp;#x3C;MenuTrigger asChild&gt;
&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token unchanged&quot;&gt;&lt;span class=&quot;token prefix unchanged&quot;&gt; &lt;/span&gt;&lt;span class=&quot;token line&quot;&gt;   &amp;#x3C;MoreAction /&gt;
&lt;/span&gt;&lt;span class=&quot;token prefix unchanged&quot;&gt; &lt;/span&gt;&lt;span class=&quot;token line&quot;&gt; &amp;#x3C;/MenuTrigger&gt;
&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In Storyden, I don&amp;#x27;t construct icon-buttons ad-hoc, instead I keep them all in one place and use them as components. This keeps naming consistent and makes it easier to re-use semantically similar actions throughout the product. A &amp;quot;More&amp;quot; menu in the above example is always the same behaviour, appearance, ARIA roles, etc. and I can change it app-wide if I want.&lt;/p&gt;</description>
</item>
<item>
<title>How does YouTube&apos;s blurry background work?</title>
<link>https://southcla.ws/how-does-youtube-colour-blur-work</link>
<guid isPermaLink="true">https://southcla.ws/how-does-youtube-colour-blur-work</guid>
<pubDate>Tue, 12 Dec 2023 00:00:00 GMT</pubDate>
<description>&lt;p&gt;If you&amp;#x27;ve watched a YouTube video recently, on web or the mobile app, you might have noticed that behind the video there&amp;#x27;s a slight splash of colour behind the video that spreads all the way up to the search bar.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-12-07-30-32.png&quot; alt=&quot;2023-12-12-07-30-32&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;It&amp;#x27;s a nice effect, and it&amp;#x27;s not just a static image, it feels like a video but it&amp;#x27;s not that either. So what is it?&lt;/p&gt;
&lt;p&gt;It gradually changes colour in the background, so if you leave a video playing or skip to a later part with different colours, you&amp;#x27;ll notice the background change to match. Pretty cool!&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-12-07-33-41.png&quot; alt=&quot;2023-12-12-07-33-41&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;h2&gt;&lt;code&gt;id=&amp;quot;cinematics&amp;quot;&lt;/code&gt;&lt;/h2&gt;
&lt;p&gt;After deleting every element from the inspector, I found that the element that was responsible for the effect was a &lt;code&gt;div&lt;/code&gt; with an &lt;code&gt;id&lt;/code&gt; of &lt;code&gt;cinematics&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-12-07-35-51.png&quot; alt=&quot;2023-12-12-07-35-51&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;And if you play the video with the actual video container hidden with &lt;code&gt;display: none;&lt;/code&gt; you&amp;#x27;ll see that the &amp;quot;cinematics&amp;quot; effect isn&amp;#x27;t a video at all, it&amp;#x27;s a series of blurred images fading between each other.&lt;/p&gt;
&lt;a href=&quot;https://southcla.ws/how-does-youtube-colour-blur-work&quot;&gt;Watch this video on the blog&lt;/a&gt;
&lt;p&gt;This isn&amp;#x27;t an &lt;code&gt;&amp;lt;img&amp;gt;&lt;/code&gt; or even a &lt;code&gt;&amp;lt;video&amp;gt;&lt;/code&gt; it&amp;#x27;s actualy two &lt;code&gt;&amp;lt;canvas&amp;gt;&lt;/code&gt; elements on top of each other!&lt;/p&gt;
&lt;p&gt;The canvas on top plays this, which fades from black to colour every 5 seconds.&lt;/p&gt;
&lt;a href=&quot;https://southcla.ws/how-does-youtube-colour-blur-work&quot;&gt;Watch this video on the blog&lt;/a&gt;
&lt;p&gt;And the canvas underneath that plays this, which is the exact same as the sequence above but without the fades and 5 seconds ahead.&lt;/p&gt;
&lt;a href=&quot;https://southcla.ws/how-does-youtube-colour-blur-work&quot;&gt;Watch this video on the blog&lt;/a&gt;
&lt;p&gt;When played on top of each other, the effect is these 5 second thumbnail-like images are fading between each other.&lt;/p&gt;
&lt;p&gt;Here&amp;#x27;s the HTML of these elements:&lt;/p&gt;
&lt;pre class=&quot;language-html&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;div&lt;/span&gt;
  &lt;span class=&quot;token special-attr&quot;&gt;&lt;span class=&quot;token attr-name&quot;&gt;style&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;
    position: absolute;
    inset: 0px;
    pointer-events: none;
    transform: scale(1.5, 2);
  &lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;canvas&lt;/span&gt;
    &lt;span class=&quot;token attr-name&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;110&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token attr-name&quot;&gt;height&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;75&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token special-attr&quot;&gt;&lt;span class=&quot;token attr-name&quot;&gt;style&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;token value css language-css&quot;&gt;&lt;span class=&quot;token property&quot;&gt;position&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; absolute&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;token property&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 100%&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;token property&quot;&gt;height&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 100%&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;/&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;canvas&lt;/span&gt;
    &lt;span class=&quot;token attr-name&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;110&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token attr-name&quot;&gt;height&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;75&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token special-attr&quot;&gt;&lt;span class=&quot;token attr-name&quot;&gt;style&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;token value css language-css&quot;&gt;&lt;span class=&quot;token property&quot;&gt;position&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; absolute&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;token property&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 100%&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;token property&quot;&gt;height&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 100%&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; &lt;span class=&quot;token property&quot;&gt;opacity&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 1&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;/&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;div&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Rationale&lt;/h2&gt;
&lt;p&gt;I think its done this way for a few reasons:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;playing the video twice, one blurred, would put strain on the client device to blur the video - blurring things is actually quite computationally expensive, especially for devices that can&amp;#x27;t use hardware accelleration to do it.&lt;/li&gt;
&lt;li&gt;similarly, producing a video with this content on the YouTube server at the time of upload would be expensive and the file would be large and yet another thing to download alongside the main video.&lt;/li&gt;
&lt;li&gt;the effect is actually quite subtle, so it&amp;#x27;s not worth the effort to make it a video, it&amp;#x27;s just a nice touch.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;And how it&amp;#x27;s working beyond the &lt;code&gt;&amp;lt;canvas&amp;gt;&lt;/code&gt; I think:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;when the video is uploaded, YouTube grabs a small amount of dominant colours every 5 seconds - 32 is my guess (a 4 * x grid)&lt;/li&gt;
&lt;li&gt;when someone loads a video page, this data is also loaded - it would be very small, 4 bytes per colour (RGBA) _ 32 colours _ (seconds of video / 5 seconds) = 7kb for a 5 minute video roughly.&lt;/li&gt;
&lt;li&gt;the &lt;code&gt;&amp;lt;canvas&amp;gt;&lt;/code&gt; elements are both drawn from the same data, but one is offset by 5 seconds.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;And notable things:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;if you skip to any point in the video, the effect transitions smoothly to whatever colours are closest to the point you skipped at.&lt;/li&gt;
&lt;li&gt;if you skip to the end of the video, the effect transitions smoothly to black.&lt;/li&gt;
&lt;li&gt;the first 5 seconds of the bottom canvas is black then cuts to colour after this, because the top canvas fades from black, the first 5 seconds are just a fade from black to colour.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;How to do it yourself&lt;/h2&gt;
&lt;p&gt;Now I&amp;#x27;m not going to give a full tutorial here (i&amp;#x27;m going to work shortly) but I&amp;#x27;ll drop some signposts!&lt;/p&gt;
&lt;p&gt;Based on browsing the code for 5 minutes, they&amp;#x27;re using &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/filter&quot;&gt;CanvasRenderingContext2D + blur&lt;/a&gt;:&lt;/p&gt;
&lt;pre class=&quot;language-js&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;bBc&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;token operator&quot;&gt;!&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;filter&quot;&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;token class-name&quot;&gt;CanvasRenderingContext2D&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;prototype&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;||&lt;/span&gt;
    &lt;span class=&quot;token constant&quot;&gt;H&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;kevlar_watch_cinematics_css_blur&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And blurring by about 40px:&lt;/p&gt;
&lt;pre class=&quot;language-js&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;var&lt;/span&gt; &lt;span class=&quot;token function-variable function&quot;&gt;cBc&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token parameter&quot;&gt;a&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  a&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;ambientV2Container
    &lt;span class=&quot;token operator&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;hBc&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;a&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Hh&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;a&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;container&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;token literal-property property&quot;&gt;position&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;absolute&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;token literal-property property&quot;&gt;top&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;0&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;token literal-property property&quot;&gt;left&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;0&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;token literal-property property&quot;&gt;right&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;0&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;token literal-property property&quot;&gt;bottom&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;0&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;token string-property property&quot;&gt;&quot;pointer-events&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;none&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;token literal-property property&quot;&gt;transform&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;scale(&quot;&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;iBc&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;a&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;, &quot;&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;jBc&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;a&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;)&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;token function&quot;&gt;bBc&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;&amp;#x26;&amp;#x26;&lt;/span&gt;
        &lt;span class=&quot;token function&quot;&gt;Hh&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;
          a&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;container&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
          &lt;span class=&quot;token string&quot;&gt;&quot;filter&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
          &lt;span class=&quot;token string&quot;&gt;&quot;blur(&quot;&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;zl&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;cinematic_watch_css_filter_blur_strength&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;40&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;px)&quot;&lt;/span&gt;
        &lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I&amp;#x27;d recommend &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial&quot;&gt;MDN&amp;#x27;s Canvas tutorial&lt;/a&gt; to get to grips with the basics of canvas. It&amp;#x27;s a very powerful tool and pretty much powers any highly interactive web experience from image editors to 3D rendering.&lt;/p&gt;</description>
</item>
<item>
<title>Migrating from Chakra UI to Panda CSS</title>
<link>https://southcla.ws/how-to-migrate-from-chakra-ui-to-panda-css</link>
<guid isPermaLink="true">https://southcla.ws/how-to-migrate-from-chakra-ui-to-panda-css</guid>
<pubDate>Fri, 08 Dec 2023 00:00:00 GMT</pubDate>
<description>&lt;p&gt;In this article I&amp;#x27;ll be covering the motivations behind why I&amp;#x27;m adopting Panda CSS for my frontend work, how it compares to Chakra UI, and how you can migrate from Chakra UI to Panda CSS gradually as well as what kind of work is required to maintain both in the same codebase for a period of time.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/chakra-to-panda.png&quot; alt=&quot;The Chakra UI logo with a curly arrow pointing to the Panda CSS logo&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;h2&gt;What actually is Panda CSS?&lt;/h2&gt;
&lt;p&gt;You know what Panda is, because you searched for it and found this article. But just to ~~give you a refresher~~ do some SEO magic for Google.&lt;/p&gt;
&lt;p&gt;Panda CSS is a new utility-first CSS framework. Now you might be thinking &amp;quot;oh so just like tailwind/tachyons&amp;quot; and the outcome does look similar but there&amp;#x27;s a key difference. Panda&amp;#x27;s main power is that it&amp;#x27;s built on the idea of code generation rather than pre-defined utility classes. So instead of writing tweet sized &lt;code&gt;className&lt;/code&gt; strings you can make use of generated classes or JSX style props much like styled-components.&lt;/p&gt;
&lt;p&gt;But it retains the unrivaled (in my opinion) developer experience of style props, for example:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;styled.article&lt;/span&gt;
  &lt;span class=&quot;token attr-name&quot;&gt;className&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;content&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token attr-name&quot;&gt;display&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;flex&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token attr-name&quot;&gt;flexDir&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;column&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token attr-name&quot;&gt;gap&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;8&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token attr-name&quot;&gt;w&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;full&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token attr-name&quot;&gt;overflow&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;hidden&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;becomes these utility classes:&lt;/p&gt;
&lt;pre class=&quot;language-css&quot;&gt;&lt;code&gt;&lt;span class=&quot;token selector&quot;&gt;.d_flex&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;display&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; flex&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token selector&quot;&gt;.flex_column&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;flex-direction&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; column&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token selector&quot;&gt;.gap_8&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;gap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;--spacing-8&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token selector&quot;&gt;.w_full&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;--sizes-full&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token selector&quot;&gt;.overflow_hidden&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;overflow&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; hidden&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And it&amp;#x27;s all based on modern web native technologies like CSS layers, variables and conditionals.&lt;/p&gt;
&lt;p&gt;One thing worth noting is that Panda CSS is &lt;em&gt;just&lt;/em&gt; the styles part. It&amp;#x27;s not a component library and does not provide out of the box components to use like Chakra does. Panda is sort of like a replacement for Emotion, which Chakra uses. If you want to know more about this growing ecosystem, I highly recommend reading this by Segun Adebayo, the creator of Chakra UI:&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://www.adebayosegun.com/blog/chakra-panda-ark-whats-the-plan&quot;&gt;https://www.adebayosegun.com/blog/chakra-panda-ark-whats-the-plan&lt;/a&gt;&lt;/p&gt;
&lt;h2&gt;Motivations to move&lt;/h2&gt;
&lt;p&gt;Now, Chakra UI is fairly similar so why might you want to change? If you&amp;#x27;ve come across this article from a Google search, perhaps you&amp;#x27;ve already made the decision and understand the why and are only interested in the what and how. If that&amp;#x27;s the case, feel free to skip forward.&lt;/p&gt;
&lt;p&gt;It boils down to three reasons:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Outgrown somewhat, I&amp;#x27;m hitting roadblocks more often&lt;/li&gt;
&lt;li&gt;Feels bloated, lots of client side JS with Emotion&lt;/li&gt;
&lt;li&gt;Need a static solution for Storyden&amp;#x27;s on-prem use-case&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;I work on a few frontend projects ranging from small, mostly static, landing pages/marketing sites, both personal and commercial as well as large complex web applications, one of which is &lt;a href=&quot;https://storyden.org/&quot;&gt;Storyden&lt;/a&gt; the other is &lt;a href=&quot;https://joinodin.com/&quot;&gt;Odin&lt;/a&gt; where I&amp;#x27;m a full stack engineer and we&amp;#x27;re currently going through this migration.&lt;/p&gt;
&lt;p&gt;Among all of my work, I value simple pipelines and isolated complexity. Complexity is always present and managing it is the difference between a dead &amp;quot;side project&amp;quot; and a successful product.&lt;/p&gt;
&lt;p&gt;Chakra served me very well and it will continue to do so for some projects but with products like Odin and Storyden that I&amp;#x27;m going to customise all the components anyway &lt;em&gt;and&lt;/em&gt; I want small static CSS and minimal runtime impact, Panda just makes more sense.&lt;/p&gt;
&lt;p&gt;If you want to read the first Storyden PR that started the migration, that&amp;#x27;s here: https://github.com/Southclaws/storyden/pull/30&lt;/p&gt;
&lt;h3&gt;What&amp;#x27;s the deal with RSC, SSR and &lt;code&gt;&amp;quot;use client&amp;quot;&lt;/code&gt;?&lt;/h3&gt;
&lt;p&gt;This is the one that got me started exploring alternatives to Chakra. The main thing Next.js 13 introduced was the usage of a fairly new React feature called &amp;quot;React server components&amp;quot; Josh Comeau wrote a great piece on the details of what that actually means and I encourage you to read it if you&amp;#x27;re interested:&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://www.joshwcomeau.com/react/server-components/&quot;&gt;https://www.joshwcomeau.com/react/server-components/&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;What confused me at first was RSC, SSR and &amp;quot;use client&amp;quot;, which this article covers very well! The short version is: Chakra UI still supports server side &lt;em&gt;rendering&lt;/em&gt;, but not server &lt;em&gt;components&lt;/em&gt;. Which means I can&amp;#x27;t make use of certain component tree optimisations and features mentioned in the above article.&lt;/p&gt;
&lt;p&gt;The reason for this is that Chakra UI uses &lt;a href=&quot;https://emotion.sh/&quot;&gt;Emotion&lt;/a&gt; for styling, which is a CSS-in-JS library. It&amp;#x27;s great, I&amp;#x27;ve used it for years, but it&amp;#x27;s not compatible with RSC for various reasons.&lt;/p&gt;
&lt;p&gt;So I decided to switch in order to both make use of the latest Next.js features as well as learn how they work in a real production application.&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;async&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Server&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; data &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;await&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;fetch&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;/v1/threads&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;

  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Client&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;threads&lt;/span&gt;&lt;span class=&quot;token script language-javascript&quot;&gt;&lt;span class=&quot;token script-punctuation punctuation&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;data&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;threads&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;/&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In this minimal example, the &lt;code&gt;Box&lt;/code&gt; we see is not Chakra&amp;#x27;s, but Panda&amp;#x27;s. And the component is a React Server Component, which allows top-level awaited fetch.&lt;/p&gt;
&lt;h3&gt;Static is generally simpler&lt;/h3&gt;
&lt;p&gt;The other reason is that Chakra has been getting in the way a bit more recently, both at my full-time job and in my own products. I&amp;#x27;ve been using it for a few years now and I&amp;#x27;ve always been a fan of the developer experience. But the generated styles are named using hashes, the bundles are quite big and I&amp;#x27;ve run across a few weird bugs over the years that are often down to Emotion itself or style state getting out of sync.&lt;/p&gt;
&lt;p&gt;Panda, being mostly built on the ideas of CSS variables, design tokens and code generation felt much simpler. And now that I&amp;#x27;ve migrated or been involved in the migration of about 4 and a half codebases, I can safely say it is.&lt;/p&gt;
&lt;h2&gt;Migrating&lt;/h2&gt;
&lt;p&gt;Alright let&amp;#x27;s get to the good bit. How do you migrate from Chakra UI to Panda CSS?&lt;/p&gt;
&lt;p&gt;It&amp;#x27;s fairly smooth but it will depend quite a bit on your approach to web development. If you&amp;#x27;re a strong advocate for semantic HTML and separation of concerns when it comes to semantics, styles and behaviours then you won&amp;#x27;t run into much trouble. But we all have technical debt so I&amp;#x27;ll cover some common cases I&amp;#x27;ve seen and the solutions I&amp;#x27;ve had success with.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Note that this will focus on Next.js as that&amp;#x27;s my primary framework and the most popular. The same principles &lt;em&gt;may&lt;/em&gt; apply to other frameworks but honestly, I&amp;#x27;ve no idea.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3&gt;Install Panda CSS&lt;/h3&gt;
&lt;p&gt;Follow the installation instructions from the Panda documentation, no additional steps are required but I can recommend a few:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;set &lt;code&gt;jsxFramework: &amp;quot;react&amp;quot;&lt;/code&gt; in your Panda configuration: this enables style props, so you can continue to use &lt;code&gt;&amp;lt;Box w=&amp;quot;full&amp;quot;&amp;gt;&lt;/code&gt; and friends.&lt;/li&gt;
&lt;li&gt;add &lt;code&gt;&amp;quot;paths&amp;quot;: {&amp;quot;@/styled-system/*&amp;quot;: [&amp;quot;styled-system/*&amp;quot;]}&lt;/code&gt; to your tsconfig for import mapping.&lt;/li&gt;
&lt;li&gt;add &lt;code&gt;styled-system&lt;/code&gt; to &lt;code&gt;include&lt;/code&gt; in tsconfig so all the types do their thing.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Relevant documentation: https://panda-css.com/docs/concepts/style-props&lt;/p&gt;
&lt;h3&gt;Switch out the CSS reset&lt;/h3&gt;
&lt;p&gt;Next, you&amp;#x27;ll want to switch out the CSS reset for Panda&amp;#x27;s. This is purely because there&amp;#x27;s no point having two resets, and Panda&amp;#x27;s will be your main one going forward anyway so it&amp;#x27;s best to get this out of the way (and identify any weirdness) as early on as possible.&lt;/p&gt;
&lt;p&gt;First enable Panda&amp;#x27;s reset, it&amp;#x27;s called &amp;quot;preflight&amp;quot; for some reason 🤷&lt;/p&gt;
&lt;p&gt;Docs: https://panda-css.com/docs/references/config#preflight&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;default&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;defineConfig&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  preflight&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then disable Chakra&amp;#x27;s reset in the top-level context provider in the root layout.&lt;/p&gt;
&lt;p&gt;Docs: https://chakra-ui.com/getting-started/cra-guide#chakraprovider-props&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;function&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Providers&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; children &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; PropsWithChildren&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;CacheProvider&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;ChakraProvider&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;resetCSS&lt;/span&gt;&lt;span class=&quot;token script language-javascript&quot;&gt;&lt;span class=&quot;token script-punctuation punctuation&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token boolean&quot;&gt;false&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
      ...
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And you&amp;#x27;re done! Refresh your app and you &lt;em&gt;should&lt;/em&gt; see no differences. If you do, I&amp;#x27;d love to know so I can add them here for future readers &lt;a href=&quot;https://twitter.com/southclaws&quot;&gt;@southclaws&lt;/a&gt;!&lt;/p&gt;
&lt;h3&gt;Start with layout primitives&lt;/h3&gt;
&lt;p&gt;Now you can start migrating your components. I recommend starting with the layout primitives, things like &lt;code&gt;Box&lt;/code&gt;, &lt;code&gt;Flex&lt;/code&gt;, &lt;code&gt;Grid&lt;/code&gt; and &lt;code&gt;Stack&lt;/code&gt;. These are the easiest to migrate because they&amp;#x27;re mostly just layout and spacing. Chakra&amp;#x27;s default theme uses numeric tokens such as &amp;quot;2&amp;quot;, &amp;quot;4&amp;quot; but also named tokens like &amp;quot;md&amp;quot; for medium and &amp;quot;lg&amp;quot; for large.&lt;/p&gt;
&lt;p&gt;The scale of the numeric tokens is the same:&lt;/p&gt;
&lt;p&gt;However, named tokens are slightly different. Chakra has:&lt;/p&gt;
&lt;pre class=&quot;language-css&quot;&gt;&lt;code&gt;&lt;span class=&quot;token property&quot;&gt;--chakra-sizes-container-sm&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 640px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token property&quot;&gt;--chakra-sizes-container-md&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 768px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token property&quot;&gt;--chakra-sizes-container-lg&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 1024px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token property&quot;&gt;--chakra-sizes-container-xl&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 1280px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Whereas Panda has:&lt;/p&gt;
&lt;pre class=&quot;language-css&quot;&gt;&lt;code&gt;&lt;span class=&quot;token property&quot;&gt;--breakpoints-sm&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 640px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token property&quot;&gt;--breakpoints-md&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 768px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token property&quot;&gt;--breakpoints-lg&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 1024px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token property&quot;&gt;--breakpoints-xl&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 1280px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token property&quot;&gt;--breakpoints-2xl&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 1536px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And there are a few other places where tokens in the default theme differ. But this is where strict tokens really helps. You&amp;#x27;ll get TS compiler warnings everywhere when these tokens don&amp;#x27;t match.&lt;/p&gt;
&lt;p&gt;As for when the values differ, you&amp;#x27;ll just have to add some custom tokens to your Panda config. I recommend using the same names as Chakra&amp;#x27;s tokens so that you can migrate gradually with minimal disruption.&lt;/p&gt;
&lt;h3&gt;How do conditionals work?&lt;/h3&gt;
&lt;p&gt;This is something that caught myself some of my coworkers off guard. Chakra is fairly SPA focused so it encourages you to use JavaScript quite a lot to handle conditions. This can range from simple things like using ternary operators for styles to using &lt;code&gt;useBreakpoint&lt;/code&gt; to determine a component&amp;#x27;s size.&lt;/p&gt;
&lt;p&gt;Panda takes a different approach and encourages you to use the native tools of the web platform. This mostly boils down to:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;CSS conditionals and variables&lt;/li&gt;
&lt;li&gt;Media queries&lt;/li&gt;
&lt;li&gt;Data attributes&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;One place where this caught me off guard was a floating sidebar component that used the same width as the navigation layout&amp;#x27;s void area that it floated above. In one file I declared this:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;export&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;token constant&quot;&gt;SIDEBAR_WIDTH&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  md&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;25%&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  lg&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;33%&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And in the two components, I simply imported this conditional and used it.&lt;/p&gt;
&lt;p&gt;But this does not work with Panda, because it cannot statically analyse the runtime value of &lt;code&gt;SIDEBAR_WIDTH&lt;/code&gt; and therefore cannot generate the correct CSS. So, I could (and initially did) just copy-paste the width and leave a comment, but the correct way to do it would be to define a width in the config with a conditional.&lt;/p&gt;
&lt;p&gt;Docs: https://panda-css.com/docs/concepts/responsive-design&lt;/p&gt;
&lt;p&gt;First, define a semantic token called &lt;code&gt;sidebarWidth&lt;/code&gt;&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;sizes&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  sidebarWidth&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    value&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
      md&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;25%&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      lg&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;33%&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then, in the component, you simply use &lt;code&gt;sidebarWidth&lt;/code&gt; for the width.&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;styled.header&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;sidebarWidth&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And that&amp;#x27;s it! If we inspect the generated CSS, we can see it&amp;#x27;s using a media query and a CSS variable to set the width.&lt;/p&gt;
&lt;pre class=&quot;language-css&quot;&gt;&lt;code&gt;&lt;span class=&quot;token atrule&quot;&gt;&lt;span class=&quot;token rule&quot;&gt;@media&lt;/span&gt; screen &lt;span class=&quot;token keyword&quot;&gt;and&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token property&quot;&gt;min-width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 48em&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token selector&quot;&gt;:where(:root, :host)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token property&quot;&gt;--sizes-sidebar-width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 25%&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;token atrule&quot;&gt;&lt;span class=&quot;token rule&quot;&gt;@media&lt;/span&gt; screen &lt;span class=&quot;token keyword&quot;&gt;and&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token property&quot;&gt;min-width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 64em&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token selector&quot;&gt;:where(:root, :host)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token property&quot;&gt;--sizes-sidebar-width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; 33%&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;h3&gt;Avoiding or isolating dynamism&lt;/h3&gt;
&lt;p&gt;This is mostly just general web application advice though it mostly applies to the kinds of applications that I work with: public facing, first-render-performance-sensitive web &lt;em&gt;applications&lt;/em&gt; that also act as web &lt;em&gt;sites&lt;/em&gt;. Storyden is a perfect example as it&amp;#x27;s an application with lots of interactive parts, but it&amp;#x27;s also a website that provides public pages that are indexed by crawlers and used by a variety of users and devices.&lt;/p&gt;
&lt;p&gt;You may have Chakra code that looks like this:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;backgroundColor&lt;/span&gt;&lt;span class=&quot;token script language-javascript&quot;&gt;&lt;span class=&quot;token script-punctuation punctuation&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;isSomething &lt;span class=&quot;token operator&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;blue&quot;&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;red&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;React makes this quite easy to do, and it&amp;#x27;s not inherently bad, but it&amp;#x27;s a technique that should be used with intent. We&amp;#x27;ve discussed how conditionals work for media queries already, but this section concerns interactivity.&lt;/p&gt;
&lt;p&gt;Generally speaking, Panda on its own is not the solution for switching styles based on state. Whereas Chakra will quite happily work well with this as it&amp;#x27;s based on Emotion which does all the CSS changes dynamically.&lt;/p&gt;
&lt;p&gt;In the example above, &amp;quot;Something&amp;quot; is an interactive state, triggered by a user action. We&amp;#x27;re out of pure HTML+CSS world now and into the realm of JavaScript. But if you can&amp;#x27;t switch out the styles based on state, how do you do it?&lt;/p&gt;
&lt;h3&gt;Data attributes&lt;/h3&gt;
&lt;p&gt;The answer is data attributes. This is a web-native way of adding state to your components which is reflected when those components become &lt;em&gt;elements&lt;/em&gt;. Using this encourages you to declare these states in your Panda config, which will generate all the necessary conditional CSS allowing the browser to deal with the state management so you can focus on the user experience.&lt;/p&gt;
&lt;p&gt;Panda has a section of its theme config called &amp;quot;conditions&amp;quot; which is where you set up shorthand names for CSS conditional selectors which you can then use in your components.&lt;/p&gt;
&lt;p&gt;Docs: https://panda-css.com/docs/concepts/conditional-styles&lt;/p&gt;
&lt;p&gt;Given our example, let&amp;#x27;s turn this into a Panda-friendly component 🐼&lt;/p&gt;
&lt;p&gt;First, we need to define a condition in the config:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;conditions&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  something&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;&amp;#x26;:is([data-something])&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Next, you create a semantic token that uses this condition:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;colors&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  somethingConditional&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    value&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
      base&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;red&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      _something&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;blue&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;blockquote&gt;
&lt;p&gt;Note: conditions only work in &lt;em&gt;semantic&lt;/em&gt; tokens! This is because conditionality is fundamentally a semantic thing relevant to the usage context. The regular tokens are more low level and should be used for defining simple key-value data for colours and other things from your design system.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Now you can use it in the component, we even get auto-complete!&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;data-something&lt;/span&gt;&lt;span class=&quot;token script language-javascript&quot;&gt;&lt;span class=&quot;token script-punctuation punctuation&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token boolean&quot;&gt;false&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;backgroundColor&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;somethingConditional&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
  Hello there conditionals!
&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And when you want to change the state, you don&amp;#x27;t need to worry about styling in the context of the component code, you just need to change the data attribute from false to true.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-08-19-59-09.png&quot; alt=&quot;2023-12-08-19-59-09&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;data-something&lt;/span&gt;&lt;span class=&quot;token script language-javascript&quot;&gt;&lt;span class=&quot;token script-punctuation punctuation&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token boolean&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;backgroundColor&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;somethingConditional&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
  Hello there conditionals!
&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-08-19-59-35.png&quot; alt=&quot;2023-12-08-19-59-35&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;h3&gt;Use the &lt;code&gt;vars(--luke)&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;Sometimes you really do need something local to a component and you don&amp;#x27;t really want to pollute the global Panda styles with lots of code that&amp;#x27;s only going to be used in one spot. For example, Storyden has this neat little colour picker that&amp;#x27;s only used on the admin dashboard for setting the theme. Now I could create a recipe for this but it&amp;#x27;s only used in one spot and it&amp;#x27;s not really a &amp;quot;theme&amp;quot; thing, it&amp;#x27;s a &amp;quot;component&amp;quot; thing.&lt;/p&gt;
&lt;p&gt;So for these cases I&amp;#x27;ve been using the &lt;code&gt;style&lt;/code&gt; attribute! And I know, it&amp;#x27;s generally discouraged for good reason but I follow the rule of &lt;em&gt;only&lt;/em&gt; using &lt;code&gt;style&lt;/code&gt; to set variables which are cascaded to children. Then in the children I can use those variables to set styles.&lt;/p&gt;
&lt;p&gt;Be careful with components that accept &lt;code&gt;children&lt;/code&gt; though, there are lots of good resources online about best practices when it comes to this.&lt;/p&gt;
&lt;p&gt;The core difference here is you can&amp;#x27;t just do something like:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;fontSize&lt;/span&gt;&lt;span class=&quot;token script language-javascript&quot;&gt;&lt;span class=&quot;token script-punctuation punctuation&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;someVariable&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;Hello there dynamism!&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;As you&amp;#x27;ll get a type error thanks to Panda&amp;#x27;s strict tokens:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;Type &amp;#x27;string&amp;#x27; is not assignable to type &amp;#x27;ConditionalValue&amp;lt;FontSizeToken&amp;gt; | undefined&amp;#x27;.
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Instead, break out the style attribute:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;style&lt;/span&gt;&lt;span class=&quot;token script language-javascript&quot;&gt;&lt;span class=&quot;token script-punctuation punctuation&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; fontSize&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; someVariable &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;Hello there dynamism!&lt;/span&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;&lt;span class=&quot;token class-name&quot;&gt;Box&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;There may be a better way to do this, and I&amp;#x27;d love to hear your input!&lt;/p&gt;
&lt;h3&gt;Light and Dark mode&lt;/h3&gt;
&lt;p&gt;Light and dark mode is fairly similar to Chakra however the actual implementation is fully native and makes use of &lt;code&gt;prefers-color-scheme&lt;/code&gt; instead of using localStorage to keep this state, like Chakra does.&lt;/p&gt;
&lt;p&gt;In fact, this blog you&amp;#x27;re reading right now makes use of this! Head over to the &lt;a href=&quot;https://github.com/Southclaws/me&quot;&gt;source code&lt;/a&gt; and check out the Panda configuration file.&lt;/p&gt;
&lt;p&gt;In short: &lt;code&gt;_osDark&lt;/code&gt; is a ready to use conditional you can drop in to &lt;em&gt;any&lt;/em&gt; semantic token like this:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;colors&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  background&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    value&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
      base&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;{colors.offblack}&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      _osDark&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;{colors.offwhite}&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Docs: https://panda-css.com/docs/concepts/conditional-styles#color-scheme&lt;/p&gt;
&lt;h3&gt;Regular tokens and semantic tokens&lt;/h3&gt;
&lt;p&gt;Docs: https://panda-css.com/docs/theming/tokens&lt;/p&gt;
&lt;p&gt;One of the mindset shifts I had while learning Panda was the difference between regular tokens and semantic tokens.&lt;/p&gt;
&lt;p&gt;The way I think about this is that regular tokens are low level and are tied to your design system. For example, colours will be the cute colour names your &lt;a href=&quot;https://pixelmeditations.substack.com/&quot;&gt;amazing designer&lt;/a&gt; thought up like &amp;quot;fauve&amp;quot;, &amp;quot;gunsmoke&amp;quot; and (my personal favourite) &amp;quot;minecraft&amp;quot;.&lt;/p&gt;
&lt;p&gt;Semantic tokens are more about the actual use-cases those colours are being used in and will likely be a lot more generic and widely recognised like &amp;quot;success&amp;quot;, &amp;quot;info&amp;quot; and &amp;quot;destructive&amp;quot;.&lt;/p&gt;
&lt;p&gt;Sometimes the differences can blur, like on this blog I originally defined &amp;quot;heading1&amp;quot; as a regular token but then realised it&amp;#x27;s kind of semantic so I moved them to semantic tokens. I think in a larger project with a full typography scale, there may be a large set of sizing tokens defined as regular tokens and then things like &amp;quot;heading&amp;quot;, &amp;quot;body&amp;quot;, etc would be semantic tokens.&lt;/p&gt;
&lt;h2&gt;Chakra UI vs Panda CSS&lt;/h2&gt;
&lt;p&gt;Chakra is great. It really is. Segun and contributors have done an amazing job with the library. It&amp;#x27;s my go-to for quick things but it also scales really well to full-blown applications. Style props are my preferred way to do any form of styling nowadays and Chakra&amp;#x27;s built-in theme, tokens and components are pretty much all you need to build a great product.&lt;/p&gt;
&lt;h3&gt;Compile-time goodness&lt;/h3&gt;
&lt;p&gt;Panda generates all the CSS at compile-time, which I love the idea of. I make use of declarative spec-driven code-generation a lot for my work and applying this to the frontend felt natural.&lt;/p&gt;
&lt;h3&gt;Strict tokens&lt;/h3&gt;
&lt;p&gt;It also has &amp;quot;strict&amp;quot; mode which essentially means that you cannot use ad-hoc styles, you must use tokens. This is great for enforcing consistency, raising inconsistencies to the designer and making sure everything satisfies your design system.&lt;/p&gt;
&lt;h3&gt;Conditionals are web-native&lt;/h3&gt;
&lt;p&gt;Did you ever &lt;code&gt;border={isClicked ? &amp;quot;brand.blue&amp;quot; : &amp;quot;grey.200&amp;quot;}&lt;/code&gt; I did. It&amp;#x27;s nice, but realistically speaking what you&amp;#x27;re looking at here is a JavaScript branch expression. And I promise this isn&amp;#x27;t tin-foil-hat-javascript-fear but it&amp;#x27;s using procedural constructs to encode a semantic that already exists in CSS.&lt;/p&gt;
&lt;p&gt;I&amp;#x27;d rather use the tool for the job, a &lt;code&gt;[data-clicked=&amp;quot;true&amp;quot;]&lt;/code&gt; selector. Panda is great at setting these up and it&amp;#x27;s as simple as `_clicked=&amp;quot;brand.blue&amp;quot;. Which generates purely static CSS. All you need to do is add the data attribute to your component when the time is right. The styling state change is then entirely handled by the browser, declaratively, via the stylesheet.&lt;/p&gt;
&lt;p&gt;This means less state for you to worry about, less expressions being evaluated and ultimately, less code to maintain.&lt;/p&gt;
&lt;h2&gt;Things to watch out for&lt;/h2&gt;
&lt;h3&gt;Type safety is only for components&lt;/h3&gt;
&lt;p&gt;As of writing, currently the types for tokens do not extend to the actual &lt;code&gt;panda.config.ts&lt;/code&gt; file so you can easily make typos with tokens and get confused as to why things break.&lt;/p&gt;
&lt;p&gt;When the code actually gets generated, it doesn&amp;#x27;t seem to check if the token exists and will quite happily just generate CSS with invalid syntax.&lt;/p&gt;
&lt;p&gt;For example, if you set a semantic colour to a nonexistent token:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;colors&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  oops&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    value&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;{colors.reddd}&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And use it in a component:&lt;/p&gt;
&lt;pre class=&quot;language-tsx&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;styled.p&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;color&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;oops&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token plain-text&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The CSS applied to this component is invalid:&lt;/p&gt;
&lt;pre class=&quot;language-css&quot;&gt;&lt;code&gt;&lt;span class=&quot;token selector&quot;&gt;.text_oops&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;color&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;var&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;--colors-oops&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And you can see the variable name is greyed out in the inspector:&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-08-20-26-53.png&quot; alt=&quot;2023-12-08-20-26-53&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;With no warning from Panda at compile-time during development, you&amp;#x27;ll only find out about this when inspecting the actual live site.&lt;/p&gt;
&lt;p&gt;This is annoying but it&amp;#x27;s only isolated to the Panda config currently, and I believe the Panda team are working on a solution for this!&lt;/p&gt;
&lt;h3&gt;Cloudflare can confuse you&lt;/h3&gt;
&lt;p&gt;This isn&amp;#x27;t specifically related to Panda, but I ran into this issue and it&amp;#x27;s not widely documented so I felt it makes sense to mention.&lt;/p&gt;
&lt;p&gt;When I ran into the above issue with invalid token names, I accidentally shipped a version of Storyden that had this CSS:&lt;/p&gt;
&lt;pre class=&quot;language-css&quot;&gt;&lt;code&gt;&lt;span class=&quot;token selector&quot;&gt;.md\:min-w_md&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;min-width&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; container.md&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;code&gt;container.md&lt;/code&gt; is from Chakra, I accidentally copied the token into a Panda component. &lt;code&gt;min-width: container.md&lt;/code&gt; is not valid CSS syntax and because I had Cloudflare&amp;#x27;s CSS minification enabled for production, it failed to minify.&lt;/p&gt;
&lt;p&gt;But it didn&amp;#x27;t just fail to minify, it just considered the entire rest of the file as a single token and stripped all spaces from the rest of the code. This resulted in shipping a CSS file that was half valid and the rest was a single blob of text that included beauties such as &lt;code&gt;@mediascreenand(min-width:64em){&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;To disable this feature, inside a domain property configuration, go to &lt;strong&gt;Speed&lt;/strong&gt; &amp;gt; &lt;strong&gt;Optimization&lt;/strong&gt; &amp;gt; &lt;strong&gt;Content Optimization&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-11-17-56-00.png&quot; alt=&quot;2023-12-11-17-56-00&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-11-17-56-41.png&quot; alt=&quot;2023-12-11-17-56-41&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Then scroll down to &lt;strong&gt;Auto Minify&lt;/strong&gt; and make sure &lt;strong&gt;CSS&lt;/strong&gt; is unchecked.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-11-17-58-03.png&quot; alt=&quot;2023-12-11-17-58-03&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;After a few seconds, head over to the main &lt;strong&gt;Overview&lt;/strong&gt; screen for the domain property:&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-11-17-58-53.png&quot; alt=&quot;2023-12-11-17-58-53&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Hit &lt;strong&gt;Purge cache&lt;/strong&gt; and finally &lt;strong&gt;Purge Everything&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-11-17-59-01.png&quot; alt=&quot;2023-12-11-17-59-01&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2023-12-11-18-00-11.png&quot; alt=&quot;2023-12-11-18-00-11&quot;/&gt;&lt;/span&gt;&lt;/p&gt;</description>
</item>
<item>
<title>Fluid typography kerning in CSS</title>
<link>https://southcla.ws/fluid-typography-kerning-css</link>
<guid isPermaLink="true">https://southcla.ws/fluid-typography-kerning-css</guid>
<pubDate>Sun, 24 Sep 2023 00:00:00 GMT</pubDate>
<description>&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-06-18-45-54.png&quot; alt=&quot;2024-04-06-18-45-54&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;a photo of me inspecting typography during a design review&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;There’s a special place in my heart for typography, it’s my favourite area of design. Signs, posters, magazine covers, books, movie intros, typography is everywhere. But I don’t work in those industries, I work in digital so there are extra considerations to think about on top of the already huge list of elements that matter when it comes to typesetting on the web.&lt;/p&gt;
&lt;p&gt;Of the many shared aspects of real world and digital typography, kerning is often overlooked. In the web world, we call this letter-spacing which is sort of a catch-all for both kerning and tracking. It’s flexible enough to be used for both.&lt;/p&gt;
&lt;p&gt;Every time I design and build a website for a client or a project, I spend a lot of time on the copy, the layout of the copy and the typesetting of the copy. Perhaps more than I should do, and perhaps it’s over the top, and in classic designer fashion only myself and other designers may notice or care, but nonetheless I will Patrick Bateman my way to find that perfect business card paper.&lt;/p&gt;
&lt;p&gt;What this means in practice is I’m making use of many of the CSS tools at my disposal to tightly control the way text flows on the page. This includes favourites like &lt;code&gt;&amp;lt;wbr /&amp;gt;&lt;/code&gt;, &lt;code&gt;&amp;amp;nbsp;&lt;/code&gt; and of course, fluid typography. But before we dive into fluid kerning, what actually is fluid typography?&lt;/p&gt;
&lt;h2&gt;Fluid Typography&lt;/h2&gt;
&lt;p&gt;As with everything I’ve picked up over the years, I stand on the shoulders of giants, and these particular giants are Geoff Graham and Chris Coyier, the authors of &lt;a href=&quot;https://css-tricks.com/snippets/css/fluid-typography/&quot;&gt;Fluid Typography&lt;/a&gt; and &lt;a href=&quot;https://css-tricks.com/simplified-fluid-typography/&quot;&gt;Simplified Fluid Typography&lt;/a&gt; respectively, from my favourite website of my entire career.&lt;/p&gt;
&lt;p&gt;Give the latter one a read for the most up to date approach using CSS “clamp” and if you want to peek into the past approaches, check out the former.&lt;/p&gt;
&lt;p&gt;Essentially, the idea is that instead of setting static breakpoints at specific viewport widths, you utilise the vw unit to drive the size of your type in a dynamic fashion, such that it scales linearly against the viewport width. Then, &lt;code&gt;clamp()&lt;/code&gt; is used to put a limit on the lower and upper bounds.&lt;/p&gt;
&lt;p&gt;For example, say you have a mobile size of 375px (iPhone SE - my default mobile device to design against) and a desktop size of 1440px (a macbook - not sure which one, but it’s a pretty common size)&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-06-18-48-49.png&quot; alt=&quot;2024-04-06-18-48-49&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;So, if you set your font-size to 50vw, it’ll become 720px on a macbook screen.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-06-18-49-02.png&quot; alt=&quot;2024-04-06-18-49-02&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;And it’ll be 188 (rounded up) on an iPhone SE screen.&lt;/p&gt;
&lt;p&gt;This is useful because it gives us a linear scale with a fixed 0-100 space that maps to different sizes on different devices.&lt;/p&gt;
&lt;p&gt;But obviously you don’t want to set your font size to 720px, in reality you want a much more manageable size. So we can pick a low value like 4vw which maps to 57.6px on a macbook and 15px on an iPhone.&lt;/p&gt;
&lt;p&gt;The middle point might be a nice scale but 57.6 is quite big and 15 is quite small, so this is where &lt;code&gt;clamp()&lt;/code&gt; comes in, which allows us to limit the value at some upper and lower bound:&lt;/p&gt;
&lt;pre class=&quot;language-css&quot;&gt;&lt;code&gt;&lt;span class=&quot;token function&quot;&gt;clamp&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;24px&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; 4vw&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; 48px&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Which gives us the same result, but once the screen size is beyond such that the output would be below 24px, it would just remain at 24px instead of scaling down. And the same for the upper bound, on a huge screen like a ultra-wide, it would max out at 48px instead of go to some insane value.&lt;/p&gt;
&lt;p&gt;Okay, so that’s a crash course on fluid typography. It’s very satisfying in practice and allows you to support many devices without many breakpoints. But what’s fluid kerning?&lt;/p&gt;
&lt;h2&gt;Fluid other things&lt;/h2&gt;
&lt;p&gt;Turns out you can apply this concept to any property that accepts pixels as a unit. Unfortunately, much to my disappointment, this does not work with &lt;code&gt;font-width&lt;/code&gt; so I couldn’t play with variable weight typefaces 😢&lt;/p&gt;
&lt;p&gt;I’ve been designing and building a new home page for myself recently, since my old one was built before I even did any design work (back in the days I was a Linux server admin) and it’s pretty boring.&lt;/p&gt;
&lt;p&gt;Earlier in the year I came across this really nice pair of OFL typefaces designed for the Taiwan Space Agency called TASA Orbiter and TASA Explorer. Check out &lt;a href=&quot;https://github.com/adrianzwz/TASA-Typeface-Collection/&quot;&gt;the TASA Typeface Collection&lt;/a&gt;! So I decided to use them for my personal site.&lt;/p&gt;
&lt;p&gt;One thing I do a lot when designing a marketing site, landing page or even a wordmark is mess with the kerning to get things balanced. Most well designed typefaces have decent kerning but not every single letter pair will be perfectly balanced so it’s always worth experimenting. I only made one adjustment to my heading and that was to bring the K and E ever so slightly closer just to tighten up the perceived gap between the letters.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-06-18-59-07.png&quot; alt=&quot;2024-04-06-18-59-07&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;before and after, approximately 12 people on earth care about these kinds of tiny details and I am one of them.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Because I’ve already tightened up the tracking across the entire heading, the gap between the K and the E is more prominent. This is using the following CSS applied to only the K via a span tag:&lt;/p&gt;
&lt;pre class=&quot;language-c&quot;&gt;&lt;code&gt;letter&lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt;spacing&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;token number&quot;&gt;6&lt;/span&gt;px&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;But, because I’m using fluid typography here, the font-size (and, maybe one day, the font-weight 🙏) scales linearly against the viewport size, so on mobile it looks like this:&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-06-18-59-45.png&quot; alt=&quot;2024-04-06-18-59-45&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Which is pretty awful! This is because I’m using raw pixel values instead of anything else. Now I could use rem units here to solve this, which is perfectly acceptable. Using rem would use the &lt;code&gt;:root&lt;/code&gt; element &lt;code&gt;font-size&lt;/code&gt; (which is usually 16px and generally shouldn’t go lower than this for accessibility.)&lt;/p&gt;
&lt;p&gt;But it turns out you can use the fluid typography trick too! Which also gives you finer grained control over the actual minimums and maximums as well as the actual scaling factor. So if I wanted the kerning to bottom out at a different point along the viewport width units scale than the font size, I can do that. Why would you want to do that? In the same way that rounded characters bleed above and below the x-height and baseline, kerning isn’t always an exact science and sometimes text can be more readable at a different size with a different kerning than just a straight up function of the font size itself (which you get quite easily from rem units.)&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-06-19-00-19.png&quot; alt=&quot;2024-04-06-19-00-19&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;So there you have it, meticulously crafted, fluidly scaling kerning pairs. Time consuming? Yes. Nobody will notice? Probably. Overkill? Definitely. But worth it.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-06-19-00-32.png&quot; alt=&quot;2024-04-06-19-00-32&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Look at that subtle off-white coloring. The tasteful kerning of it. Oh my God, it even has fluid typography...&lt;/p&gt;
&lt;/blockquote&gt;</description>
</item>
<item>
<title>Finding the dominant colour in logo images: the why and the how</title>
<link>https://southcla.ws/finding-dominant-colour-in-logo-image</link>
<guid isPermaLink="true">https://southcla.ws/finding-dominant-colour-in-logo-image</guid>
<pubDate>Fri, 31 Mar 2023 00:00:00 GMT</pubDate>
<description>&lt;p&gt;There are two parameters for the visual experience to balance when building a social platform: how much control over the overall design and how complex that control is. In this post, I’m going to show you how my team found this balance and implemented a simple solution.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-54-22.png&quot; alt=&quot;2024-04-08-17-54-22&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Those of you who are reading this and are around the millennial age may remember a social platform called Bebo. One thing Bebo allowed you to do was upload custom CSS for your profile page. Tumblr did this too (and still does!) as well as a handful of other early social platforms.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-54-34.png&quot; alt=&quot;2024-04-08-17-54-34&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;tumblr was one of the most unique social media platforms of the millennial era… and yes I am using past tense, it’s basically a zombie now.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;This is very high visual design control, if you know what you’re doing you can essentially treat the platform as a website provider and turn their page structure into whatever layout and design you want.&lt;/p&gt;
&lt;p&gt;On the other end, there’s Twitter, which doesn’t allow any visual customisation at all. You get to set your profile picture, header image and that’s pretty much it. You can change colours but only from a choice of 6 and it only affects your experience, not those viewing your profile.&lt;/p&gt;
&lt;p&gt;Substack actually provides some simple but effective customisation options, you can pick any arbitrary colour as an “accent colour” like a lot of platforms nowadays, but you can even choose the typeface that your writing is rendered with. While this totally makes sense for a writing platform, I still think it’s really cool and it’s still not very common these days!&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-54-42.png&quot; alt=&quot;2024-04-08-17-54-42&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;I picked mauve… obviously&lt;/p&gt;
&lt;p&gt;Accent colours, highlight colours, brand colours, these are everywhere. The industry seems to have settled on this being your “customisation”. Gone are the days of custom CSS for your social page.&lt;/p&gt;
&lt;h2&gt;The ever-present buzzword: Simplicity&lt;/h2&gt;
&lt;p&gt;People use “simplicity” to justify almost anything in the product and engineering world, especially additional complexity.&lt;/p&gt;
&lt;p&gt;To me, it’s become a bit of a cop-out answer to a lot of things in recent years. Almost to the point where the sentiment itself has reached semantic satiation.&lt;/p&gt;
&lt;p&gt;With that said, there are definitely times in digital product interface design when simplicity is going to result in a tangible positive outcome. For example, simplifying the onboarding process for customers into your application or website is going to result in a lower dropoff rate.&lt;/p&gt;
&lt;h3&gt;A splash of colour&lt;/h3&gt;
&lt;p&gt;This is exactly where accent colours and the balance of customisation come in. While designing the onboarding flows for &lt;a href=&quot;https://www.joinodin.com/&quot;&gt;Odin&lt;/a&gt;, our designer wanted to get the absolute bare minimum information from the customer and do the most with it.&lt;/p&gt;
&lt;p&gt;The end result of successful onboarding is some kind of profile (a person’s profile, a syndicate or a company, depending on what the customer wants to do) and that profile will have an &lt;em&gt;accent colour&lt;/em&gt;.&lt;/p&gt;
&lt;p&gt;Anything that’s not directly serving that goal to achieve this can be omitted from the flow and left for the customer to explore in settings later.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-55-07.png&quot; alt=&quot;2024-04-08-17-55-07&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;the assorted horsemen of the &amp;lt;input type=”color”&amp;gt;pocalypse&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Now, I like using the correct semantic HTML and native components wherever possible as much as the next person. But colour pickers just ain’t it chief, I’m sorry! The experience is &lt;em&gt;wildly&lt;/em&gt; inconsistent across platforms (yes, we care about more than Apple customers, crazy concept, I know.) and a lot of them are just generally not very user-friendly. (Apple’s is pretty mid but I have no idea what’s going on with the Android one above, it looks like My First Widget tutorial.)&lt;/p&gt;
&lt;p&gt;We didn’t want to introduce another blocking requirement because our team is very small (if you want to change that, reach out to me!) so there’s an interesting alternative…&lt;/p&gt;
&lt;h1&gt;Finding the dominant colour in an image&lt;/h1&gt;
&lt;p&gt;&lt;em&gt;If you read the &lt;strong&gt;why&lt;/strong&gt; I hope you found it informative and it wasn’t too much of the same vibes as those recipe blogs that start every post with a 5-page life story… now on to the &lt;strong&gt;how&lt;/strong&gt;!&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;We have three kinds of profiles on the Odin platform: people, syndicates and companies. I’m not going to focus on people here because the complexity involved in processing &lt;em&gt;photographs&lt;/em&gt; is much higher than that of logo graphics and the tradeoff just isn’t worth it.&lt;/p&gt;
&lt;p&gt;Logos generally have a small handful of colours, often just one in the primary brand material. So the first naïve approach is to simply bucket all pixels based on colour and then get the bucket with the most items.&lt;/p&gt;
&lt;p&gt;I’m going to be writing the code for this article in Go, however, the underlying concepts apply to any language that can load and process images at a pixel level.&lt;/p&gt;
&lt;p&gt;Go comes with a &lt;a href=&quot;https://go.dev/blog/image&quot;&gt;fantastic built-in image library&lt;/a&gt;, given some reader that’s going to provide a stream of bytes from an image, you can parse it in one line:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;im, _, err := image.Decode(r)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;As long as the image being read is one of the supported formats (JPEG, PNG, GIF as far as I can tell) you’ll get an &lt;code&gt;image.Image&lt;/code&gt; object ready to use.&lt;/p&gt;
&lt;p&gt;Now it’s just a simple task of iterating each pixel, grabbing the colour and using a hash table to record the number of hits each colour has:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;rect := im.Bounds()
counts := make(map[color.RGBA]int)

for x := 0; x &amp;lt; rect.Max.X; x++ {
	for y := 0; y &amp;lt; rect.Max.Y; y++ {
		r, g, b, a := im.At(x, y).RGBA()

		c := color.RGBA{
			uint8(r),
			uint8(g),
			uint8(b),
			uint8(a),
		}

		counts[c]++
	}
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is fine but it’s very “sensitive”. Images aren’t just grids of pixels (unless they’re bitmaps, which are impractical to use due to their size) and many formats use lossy compression which results in all sorts of strange artefacts at the pixel level. Viewers rarely notice these artefacts as they’re subtle but they will affect this sort of per-pixel kind of operation quite a bit.&lt;/p&gt;
&lt;p&gt;If we run this code on the Starbucks logo and count the number of pixel buckets (the hash table called &lt;code&gt;counts&lt;/code&gt;) we get 786. If I asked you how many colours were in the Starbucks logo, you’d say either one or two depending on whether or not you count the white background as a colour.&lt;/p&gt;
&lt;p&gt;This is a problem because these subtle differences in colour can result in the output being something you may not expect. What’s visually dominant to the human eye isn’t necessarily simply what the most popular pixel colour will be.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-56-15.png&quot; alt=&quot;2024-04-08-17-56-15&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;It sure looks like just one shade of green, and it should be, &lt;a href=&quot;https://creative.starbucks.com/color/&quot;&gt;according to their brand guidelines&lt;/a&gt; (unsurprisingly named “Starbucks Green”.)&lt;/p&gt;
&lt;p&gt;But if you run a colour picker over the image, not every pixel is equal. This is because the image is not a simple grid of pixels, but a collection of data points and algorithms that somewhat declaratively generate the grid of pixels at runtime. This is the reason there are so many buckets for an image with seemingly only two colours within.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/https___substack-post-media.s3.amazonaws.com_public_images_d5908e7e-aad7-4a68-8133-432248930eac_628x592.gif&quot; alt=&quot;&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;The actual reason why this happens with formats like PNG is out of scope for this post, but Colin McAnlis has written &lt;a href=&quot;https://medium.com/@duhroach/how-png-works-f1174e3cc7b7&quot;&gt;a pretty nice post on how PNG works&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Solving this is fairly simple though. The goal is to “snap” the pixel values to some nearby values so that colours that are only slightly different are considered equal in our hash table and thus contribute to the same bucket.&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;r, g, b, a := im.At(x, y).RGBA()
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The values returned by the RGBA function are, &lt;a href=&quot;https://pkg.go.dev/image/color#Color&quot;&gt;according to the documentation&lt;/a&gt;, within the bounds 0 to 0xffff, or 65,535. So let’s write a function that “snaps” the value to the nearest hundred:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;func normalise(i uint32) int {
	return int(math.Round(float64(i)/100) * 100)
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The math is simple: divide by a hundred, round the result then multiply that result by a hundred. This effectively reduces the precision of the number.&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;fmt.Println(32456, &amp;quot;-&amp;gt;&amp;quot;, normalise(32456))
// 32456 -&amp;gt; 32500
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This gets us one step closer, “nearby” values are now being considered the same value due to this simple rounding.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;There’s a more efficient way to do this using bitwise manipulation but our goal isn’t speed here so I’ll leave that as an exercise for the reader.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;One last thing left to do is map our value space from [0, 65535] to [0, 255]. The reason for this is that we want to end up with a &lt;code&gt;color.RGBA&lt;/code&gt; value and the red, green, blue and alpha struct fields are of the type uint8, which is far smaller than the values returned by the RGBA function above. This is just a simple case of dividing the values by 256.&lt;/p&gt;
&lt;p&gt;And since we’re working in the space of 0-255 now, snapping to the nearest hundred makes a lot less sense. We can instead snap to the nearest multiple of 8. Some experimentation can help you find the balance here.&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;func normalise(i uint32, f uint32) uint8 {
	return uint8(math.Round((float64(i)/256)/float64(f)) * float64(f))
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And putting it all together:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;rect := im.Bounds()
counts := make(map[color.RGBA]int)

for x := 0; x &amp;lt; rect.Max.X; x++ {
	for y := 0; y &amp;lt; rect.Max.Y; y++ {
		r, g, b, _ := im.At(x, y).RGBA()

		c := color.RGBA{
			normalise(r, 8),
			normalise(g, 8),
			normalise(b, 8),
			0,
		}

		counts[c]++
	}
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;One notable change here is the alpha channel is being completely ignored. We’re not interested in considering transparency when bucketing colours.&lt;/p&gt;
&lt;p&gt;Now when the code is run on the Starbucks logo, there are only 123 buckets! We can also filter out anything with a lightness level that’s too close to white or black:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;// RGB to HSL is well-trodden ground, you can find it on the internet.
hsl := tohsl(
    float64(r&amp;gt;&amp;gt;8)/255,
    float64(g&amp;gt;&amp;gt;8)/255,
    float64(b&amp;gt;&amp;gt;8)/255,
)

if hsl.l &amp;lt; 0.2 || hsl.l &amp;gt; 0.9 {
	continue
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This gets the bucket count down to 88. Which seems like a manageable level to continue from and implement the rest of the code.&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;type bucket struct {
	c color.RGBA
	n int
}

type buckets []bucket

func (a buckets) Len() int           { return len(a) }
func (a buckets) Swap(i, j int)      { a[i], a[j] = a[j], a[i] }
func (a buckets) Less(i, j int) bool { return a[i].n &amp;gt; a[j].n }
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;We want to sort the list of normalised colours by the number of times each colour appears in the image (remember, these are normalised colours).&lt;/p&gt;
&lt;p&gt;Now, Go doesn’t really have a lot of tools for easily manipulating hash tables and slices in the same way languages like Java, C#, JavaScript, etc. have, so I am going to grab a third party library called &lt;a href=&quot;https://github.com/samber/lo&quot;&gt;“lo”&lt;/a&gt; to make this a little more expressive and a little less explicit.&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;// turn our hash table into a slice of tuples
// before: { &amp;quot;#34fe56&amp;quot;: 45, ... }
// after: [ [&amp;quot;#34fe56&amp;quot;, 45], ... ]
entries := lo.Entries(counts)

// map each entry to a &amp;quot;bucket&amp;quot; as defined earlier
b := lo.Map(entries, func(e lo.Entry[color.RGBA, int], _ int) bucket {
	return bucket{e.Key, e.Value}
})

// sort the buckets using the logic defined in the &amp;quot;buckets&amp;quot; slice type
sort.Sort(buckets(b))
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;After this bit of processing, we now have a slice of “bucket” values which contain the “rounded” colour and the number of times this, and similar, colours appear in the image.&lt;/p&gt;
&lt;p&gt;Since it’s sorted descending, the first item in the slice is the most dominant colour!&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;return b[0].c, nil
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Which, after running on our Starbucks logo, the result is:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;#107030
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-58-38.png&quot; alt=&quot;2024-04-08-17-58-38&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Which is definitely close enough!&lt;/p&gt;
&lt;hr/&gt;
&lt;p&gt;Hopefully, now you can see why this simple approach only really works for graphics. Photos are much more complex in terms of data density and while this naïve pixel rounding approach would pick the mathematically dominant colour, that’s not necessarily going to be the colour someone would expect.&lt;/p&gt;
&lt;p&gt;If you enjoy discussing problems like this, perhaps you’d be interested in joining our &lt;a href=&quot;https://discord.gg/XF6ZBGF9XF&quot;&gt;100+ strong Discord server&lt;/a&gt; of like-minded folks!&lt;/p&gt;</description>
</item>
<item>
<title>Details that matter: Direct file download errors</title>
<link>https://southcla.ws/details-that-matter-direct-file-download-errors</link>
<guid isPermaLink="true">https://southcla.ws/details-that-matter-direct-file-download-errors</guid>
<pubDate>Sun, 05 Mar 2023 00:00:00 GMT</pubDate>
<description>&lt;p&gt;You’ve probably seen this from time to time when interacting with online services. This happens when the software behind the site hits a problem and does not have a backup plan. “500 Internal Server Error” is a particular category of error defined in the &lt;a href=&quot;https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1&quot;&gt;HTTP specification&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The vast majority of the time, these kinds of errors happen on requests to backend services rather than frontend services – the systems that do business logic rather than the systems that render web pages. So, with a lot of modern web applications being built on the frontend-backend separation of concerns model, you don’t see this kind of last-resort, white screen, Courier New typeface error code.&lt;/p&gt;
&lt;p&gt;This is because you’ll be accessing a frontend that’s performing these requests to the backend elsewhere. Whether that’s on the server during the HTML page render or on the browser via a &lt;code&gt;fetch&lt;/code&gt; function call.&lt;/p&gt;
&lt;p&gt;But there are cases where users will be bypassing this safety net and their browser will make direct requests to the backend. These cases are usually to download or view files.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-48-25.png&quot; alt=&quot;2024-04-08-17-48-25&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;All browsers have the capability to preview certain file formats such as images, audio, video and PDF files. So online services often serve these files with a HTTP header in the response: &lt;code&gt;Content-Disposition: inline&lt;/code&gt; which instructs the requesting browser to render the file (if possible) in the browser’s window, instead of immediately downloading the file to the device.&lt;/p&gt;
&lt;p&gt;And this is one of the requirements of building an investment technology platform that occasionally has to provide legal documents to customers. The nature of &lt;a href=&quot;https://www.joinodin.com/&quot;&gt;Odin’s&lt;/a&gt; business, unfortunately, involves lots of PDF files because apparently, lawyers can’t get enough of 1993’s smash hit Portable Document Format.&lt;/p&gt;
&lt;p&gt;Now, Odin is a heavily product-driven company, and I am very proud to be part of a team that cares deeply about the details when it comes to all aspects of a customer’s experience when using the platform. This care also means we have to embrace the fact that problems will occur, so we apply the same strict process of design and consideration to the unhappy path as we would the happy path.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-08-17-48-34.png&quot; alt=&quot;2024-04-08-17-48-34&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;No bare courier new allowed, we’re doing full HTML errors.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;This is what the backend service kicks back if it runs into an error during a direct file access request. Sure, it’s not using our designer’s beautiful design system or colours and there isn’t a squircle in sight, but it’s infinitely better than a tiny monospace cryptic phrase in the top left corner.&lt;/p&gt;
&lt;p&gt;The error response is simply some hand-written HTML that the server responds with when it catches an unrecoverable error. There’s also a correlation ID and a link for customer support in there.&lt;/p&gt;
&lt;p&gt;Building this in Go&lt;/p&gt;
&lt;hr/&gt;
&lt;p&gt;&lt;em&gt;You can apply this idea to any stack, if Go isn’t your thing you can safely stop reading here, the rest of the post will dive into some code to implement this idea into a real-world application.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;First of all, we need some HTML.&lt;/p&gt;
&lt;pre class=&quot;language-html&quot;&gt;&lt;code&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;body&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;main&lt;/span&gt; &lt;span class=&quot;token special-attr&quot;&gt;&lt;span class=&quot;token attr-name&quot;&gt;style&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;token value css language-css&quot;&gt;&lt;span class=&quot;token property&quot;&gt;text-align&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; center&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;img&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;src&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;https://your.company/logo.png&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token attr-name&quot;&gt;width&lt;/span&gt;&lt;span class=&quot;token attr-value&quot;&gt;&lt;span class=&quot;token punctuation attr-equals&quot;&gt;=&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;360px&lt;span class=&quot;token punctuation&quot;&gt;&quot;&lt;/span&gt;&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;/&gt;&lt;/span&gt;&lt;/span&gt;

    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;h1&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;A problem occurred while satisfying the request&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;h1&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;

    &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;&lt;/span&gt;p&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;%s&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;p&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
  &lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;main&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token tag&quot;&gt;&lt;span class=&quot;token punctuation&quot;&gt;&amp;#x3C;/&lt;/span&gt;body&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;&gt;&lt;/span&gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Next, we format this string with the underlying error message. And &lt;em&gt;&lt;strong&gt;no&lt;/strong&gt;&lt;/em&gt; that does not mean simply calling &lt;code&gt;err.Error()&lt;/code&gt; and dumping whatever random assortment of strings it spits out into your error. Your customers deserve better than that.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f&quot;&gt;When life gives you lemons, write better error messages.&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;Fortunately, &lt;a href=&quot;https://github.com/Southclaws/fault&quot;&gt;Fault&lt;/a&gt; is there to help with its end-user-specific error messaging helper. For more on that, check out the big post I wrote on why Fault exists:&lt;/p&gt;
&lt;p&gt;And the last piece of the puzzle is to remember to set the correct header. You don’t need to worry about &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition&quot;&gt;Content Disposition&lt;/a&gt; because HTML is by default rendered (otherwise the web wouldn’t be the web!) all you need is &lt;code&gt;text/html&lt;/code&gt; as the &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type&quot;&gt;Content-Type&lt;/a&gt; and your error message game will immediately be stepped up with minimal effort!&lt;/p&gt;
&lt;hr/&gt;
&lt;p&gt;If you enjoyed this post, consider subscribing! I write about building products with a balance between the technology behind them, the design that goes into them and the cultural and political effects surrounding it all.&lt;/p&gt;</description>
</item>
<item>
<title>Wrapping errors in Go</title>
<link>https://southcla.ws/wrapping-errors-in-go-a-new-approach</link>
<guid isPermaLink="true">https://southcla.ws/wrapping-errors-in-go-a-new-approach</guid>
<pubDate>Sun, 18 Sep 2022 00:00:00 GMT</pubDate>
<description>&lt;p&gt;I&amp;#x27;ve changed &lt;strong&gt;all&lt;/strong&gt; error wrapping in two production codebases from this:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;failed to do a thing&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And this:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fmt&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Errorf&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;failed to do a thing: %w&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; err&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And (ugh... yes this existed somewhere) this:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Errorf&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;failed to do a thing: %v&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; err&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;With the following code:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; fctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;As well as configured the &amp;quot;wrapcheck&amp;quot; linter to warn developers about anything other than &lt;code&gt;fault.Wrap&lt;/code&gt; at error handling sites.&lt;/p&gt;
&lt;p&gt;And I&amp;#x27;m going to tell you why this was the best thing I did to those codebases this year.&lt;/p&gt;
&lt;h2&gt;Enter: Structured Errors&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;doesn&amp;#x27;t have the same ring as sandman&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;For a little context, &lt;a href=&quot;https://www.southcla.ws/go-structured-errors/&quot;&gt;it&amp;#x27;s worth skimming over the previous post&lt;/a&gt;, in which I covered the journey that lead to &amp;quot;structured errors&amp;quot; which plug nicely into structured logging.&lt;/p&gt;
&lt;p&gt;During that journey, I wrote a library called &amp;quot;errctx&amp;quot;, error context, which performed the simple task of facilitating decorating call trees with metadata, dumping that into an error and allowing that data to be pulled out at the other end and logged out. Without the need for a complex tracing system set up.&lt;/p&gt;
&lt;p&gt;But this was only half of the solution. After errctx saw a little bit of widespread experimental use among packages, some patterns were emerging.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; errctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ctx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This works great, but I had also written a few other helpers to solve other problems as well. And of course I didn&amp;#x27;t want to entirely &lt;em&gt;lose&lt;/em&gt; the ability to decorate error chains with additional &lt;em&gt;written&lt;/em&gt; content. So with pkg/errors and my other wrapper library, things got very crowded:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; errctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;errtag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;failed to do thing&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And if you read the earlier post, you know how I feel about ergonomics. This is very far from ergonomic.&lt;/p&gt;
&lt;h2&gt;Package surface bloat&lt;/h2&gt;
&lt;p&gt;However, there was a problem I wanted to avoid. That was writing a large monolithic library that solved only my exact problems. These kinds of libraries can be useful sometimes but they can also just become open source for the sake of open source. In other words, not actually useful for others to use.&lt;/p&gt;
&lt;p&gt;I wanted to write something useful. Something that other engineers and products can benefit from. I wanted to solve the problem of making structured errors easy while also providing a simple interface.&lt;/p&gt;
&lt;h2&gt;State of the art&lt;/h2&gt;
&lt;p&gt;The way &amp;quot;error wrapping&amp;quot; in Go has a very commonly used pattern. It&amp;#x27;s not a defined pattern but more of an idiom that everyone just follows loosely.&lt;/p&gt;
&lt;p&gt;Let&amp;#x27;s look at this code again, it looks familiar...&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;errctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;errtag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;failed to do thing&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This code must be read from inside out. &lt;code&gt;err&lt;/code&gt; starts its involvement in this tangled mess by being referenced in a new instance of a struct from &lt;a href=&quot;https://github.com/pkg/errors/&quot;&gt;pkg/errors&lt;/a&gt; called &lt;a href=&quot;https://github.com/pkg/errors/blob/master/errors.go#L188&quot;&gt;&lt;code&gt;withMessage&lt;/code&gt;&lt;/a&gt; and then again into &lt;a href=&quot;https://github.com/pkg/errors/blob/master/errors.go#L192&quot;&gt;&lt;code&gt;withStack&lt;/code&gt;&lt;/a&gt; and then it&amp;#x27;s returned and passed to &lt;code&gt;errtag.Wrap&lt;/code&gt; which does the same thing into a struct named &lt;code&gt;withTag&lt;/code&gt; (if memory serves) and then &lt;em&gt;again&lt;/em&gt; into a struct called &lt;code&gt;withContext&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-21-18-48.png&quot; alt=&quot;2024-04-07-21-18-48&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Just because our &lt;em&gt;data structure&lt;/em&gt; is heavily nested, does not mean our code ergonomics need to echo that so explicitly. What we&amp;#x27;re actually doing is (conceptually, not in reality) creating immutable copies of the input with some additions.&lt;/p&gt;
&lt;p&gt;The familiarity I pointed out earlier is that of HTTP middleware (or, really, any kind of middleware-esque data mutation pipeline)&lt;/p&gt;
&lt;p&gt;Middleware essentially takes a request and creates a new request with some extra information tacked on. Again, conceptually, not all the time in reality.&lt;/p&gt;
&lt;p&gt;But you don&amp;#x27;t set up middleware with a bunch of nested function calls do you?&lt;/p&gt;
&lt;h2&gt;Functional programming in the wild&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;yes, it actually happens sometimes!&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;How HTTP middleware is designed in most libraries and languages as a stored list of curried functions which are then &lt;em&gt;applied&lt;/em&gt; to each request. A curried function is basically a function where you&amp;#x27;ve shuffled around the arguments so that you store some input parameters but return a new function that has not been called yet.&lt;/p&gt;
&lt;p&gt;This technique allows you to specify &lt;em&gt;some&lt;/em&gt; parameters now and others &lt;em&gt;later&lt;/em&gt;. This is powerful, especially when you have a common function signature and an uncommon set of additional parameters you want to provide.&lt;/p&gt;
&lt;p&gt;Say you have this function, and you want to apply it to a whole bunch of input data. But your separator and your prefix never changes.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;joinAndPrefix&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;strings &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; sep &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; prefix &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; prefix &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; strings&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Join&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;strings&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; sep&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In this example program, the input data is sort of like a conveyor belt of parameters as this function is repeatedly called with different inputs:&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-21-19-14.png&quot; alt=&quot;2024-04-07-21-19-14&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;a, b, c, d and e here are just different string slices, but the other params are always identical.&lt;/p&gt;
&lt;p&gt;Since you&amp;#x27;re always going to pass, for example &lt;code&gt;&amp;quot;,&amp;quot;&lt;/code&gt; as the separator and &lt;code&gt;&amp;quot;items: &amp;quot;&lt;/code&gt; as the prefix, you can curry this function to make it more ergonomic and easier to test.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;makeJoinAndPrefixer&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;sep &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; prefix &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;s &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; prefix &lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt; strings&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Join&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;s&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; sep&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now we can construct a function with, essentially what is, some pre-defined parameters:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;prefixer &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;makeJoinAndPrefixer&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;,&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;items: &quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And apply that function to inputs, since the other two arguments are kind of stored &lt;em&gt;inside&lt;/em&gt; the function instance itself:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token function&quot;&gt;prefixer&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;sword&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;shield&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;milk&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token comment&quot;&gt;// items: sword, shield, milk&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-21-21-02.png&quot; alt=&quot;2024-04-07-21-21-02&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;The separator and prefix are now stored inside the function, the only thing that now changes for each invocation of the function is the string slice parameter.&lt;/p&gt;
&lt;p&gt;And, you can imagine this being very useful in a data pipeline, say you had a map/filter/reduce library (&lt;a href=&quot;https://github.com/Southclaws/dt&quot;&gt;such as this one I made quickly one day&lt;/a&gt;) you could easily pass this prefixer to the pipeline:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;data &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
newData &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; dt&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;data&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; prefixer&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token comment&quot;&gt;// newData = []string{ ... }&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And if you have a well defined and understood function signature, such as &lt;code&gt;(http.ResponseWriter, *http.Request)&lt;/code&gt; then this idea suddenly becomes extremely useful!&lt;/p&gt;
&lt;p&gt;Think about it, you don&amp;#x27;t build middleware with dependencies by writing functions that look like this:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;auth&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;w http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;ResponseWriter&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; r &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Request&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; a &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;authService&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; jwt &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;jwtDecoder&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; l &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;logger&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Logger&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;&lt;a href=&quot;https://github.com/Southclaws/dt&quot;&gt;https://github.com/Southclaws/dt&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;You&amp;#x27;d write it like this:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;auth&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;a &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;authService&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; jwt &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;jwtDecoder&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; l &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;logger&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Logger&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;w http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;ResponseWriter&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; r &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Request&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;(In reality it may look slightly different as you may be using a non-standard HTTP library like Echo, or the more commonly used middleware approach with &lt;code&gt;func (next http&lt;/code&gt;&lt;strong&gt;&lt;code&gt;.&lt;/code&gt;&lt;/strong&gt;&lt;code&gt;Handler) http&lt;/code&gt;&lt;strong&gt;&lt;code&gt;.&lt;/code&gt;&lt;/strong&gt;&lt;code&gt;Handler&lt;/code&gt; but the fundamental concept is the same)&lt;/p&gt;
&lt;p&gt;So, that&amp;#x27;s a lightning course on currying, named after Haskell Curry by Moses Schönfinkel. But how does that help us make error management more ergonomic?&lt;/p&gt;
&lt;h2&gt;&lt;code&gt;func(error) error&lt;/code&gt;&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;(btw that&amp;#x27;s the mic-drop moment of this whole post)&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Given that all these error libraries typically implement themselves as &lt;code&gt;Wrap(error, otherstuff...)&lt;/code&gt; so if we want to combine many error wrappers together, all we need to do is &lt;em&gt;curry&lt;/em&gt; the functions!&lt;/p&gt;
&lt;p&gt;Now, &lt;em&gt;any&lt;/em&gt; error library can be implemented as a series of simple decorators that contribute whatever information they need to the error chain. Instead of picking between a few huge batteries-included error libraries or composing a bunch of nested function calls, you can cleanly compose together small simple utilities.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; fctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;InvalidInput&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Any wrapper from any library can be curried into a Fault decorator. Let&amp;#x27;s say you have a library for storing the current request ID into an error:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;WithReq&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;id RequestID&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; reqerr&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; id&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And now it can be added to a Fault error wrap site, alongside any other decorators you may need:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; fctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;WithReq&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;requestID&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;There&amp;#x27;s a lot you can do with such a simple interface. Fault comes with some utilities that provide Fault decorators to add useful metadata to your errors.&lt;/p&gt;
&lt;p&gt;One of those is fctx, which allows you to annotate contexts with key-value metadata then copy that data into an error chain if something goes wrong. This means you can easily access information about a call tree in a structured, ergonomic way that plays well with structured logging tools. You can read more about that here:&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://www.southcla.ws/go-structured-errors/&quot;&gt;Structured Errors in Go&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;Aside from fctx, there are two more utilities that you may find useful.&lt;/p&gt;
&lt;h2&gt;fmsg - people-friendly error messaging&lt;/h2&gt;
&lt;p&gt;One of the major issues I&amp;#x27;ve run into time and time again when building medium sized web applications is how to properly communicate various types of problem to end users. Developers are usually half-covered by scrappy &lt;code&gt;errors.Wrap(err, &amp;quot;failed to do xyz&amp;quot;)&lt;/code&gt; messages. It can get you pretty far with low effort. But you can&amp;#x27;t drop an all-lowercase, techno-jargon-laden, poorly-thought-out string of brain dump onto your end users. That&amp;#x27;s just rude.&lt;/p&gt;
&lt;p&gt;There&amp;#x27;s a fantastic article written by Jenni Nadler about the massive undertaking at Wix to improve their error messaging to people who use their products. I&amp;#x27;d recommend giving it a read:&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f&quot;&gt;When life gives you lemons, write better error messages&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;Many years ago, I wrote a little helper for an open source web project called &lt;code&gt;WithDescription&lt;/code&gt;. (little did I know that I would copy-paste this helper into 7 other codebases after that...) and this helper basically wrapped an error in a very similar way to how pkg/errors did, but instead of one string of text it accepted two.&lt;/p&gt;
&lt;p&gt;The second string was basically a message that would be sent to the API consumer with the intention that it would be displayed in the user interface so the user knew a little more about what went wrong.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;web&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;StatusNotFound&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;w&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; web&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WithDescription&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;New&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;not found&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;No posts were found with that ID&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;That helper wasn&amp;#x27;t really used much. It was &lt;a href=&quot;https://dave.cheney.net/2019/01/08/avoid-package-names-like-base-util-or-common&quot;&gt;buried in a &amp;quot;utils&amp;quot; package&lt;/a&gt; and I never remembered to use it.&lt;a href=&quot;https://southcla.ws/wrapping-errors-in-go-a-new-approach#side-note-1-forgetting-stuff&quot;&gt;¹&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;So when I read Jenni&amp;#x27;s article I remembered this helper I wrote and the problem I was trying to solve and an evolution of this idea ended up being part of the early version of Fault.&lt;/p&gt;
&lt;h3&gt;Writing for your audience&lt;/h3&gt;
&lt;p&gt;An astute reader may have noticed that Fault&amp;#x27;s &lt;code&gt;Wrap&lt;/code&gt; function has no string message. This is because the return value, while satisfying the error interface, is nothing but an empty shell with the sole purpose being to hold an &lt;em&gt;actual&lt;/em&gt; error&lt;a href=&quot;https://southcla.ws/side-note-2-error-containers&quot;&gt;²&lt;/a&gt;.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; fmsg&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;failed to order pizza&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is functionally equivalent to the &lt;code&gt;Wrap&lt;/code&gt; of pkg/errors. It&amp;#x27;s designed for short simple sentences aimed at other developers to read. These messages are, as you would expect, accessible by the &lt;code&gt;.Error()&lt;/code&gt; method. They are joined together with &lt;code&gt;&amp;quot;: &amp;quot;&lt;/code&gt; so when you handle the error, you can access (if you really want to) that oldschool 100 character mess.&lt;/p&gt;
&lt;p&gt;But for prettier error messages, aimed at people &lt;em&gt;using&lt;/em&gt; your product, you can write:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  	fmsg&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WithDesc&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;failed to order pizza&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;There was a problem ordering the pizza.&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And, you can add more messages further up the call tree.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  	fmsg&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WithDesc&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;failed to process cart&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;Your basket could not be processed.&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Which looks a little something like this:&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-21-21-58.png&quot; alt=&quot;2024-04-07-21-21-58&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;When you handle the error, simply call &lt;code&gt;GetIssue&lt;/code&gt; to access a string joined by spaces of all the human-readable messages in order of occurrence&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;issue &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;GetIssue&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token comment&quot;&gt;// Your basket could not be processed. There was a problem ordering the pizza.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This simple approach may not work for all cases, but for early-stage products that are growing in size rapidly, it&amp;#x27;s a game changer for user experience to be able to say &lt;em&gt;something&lt;/em&gt; instead of a generic &amp;quot;Oopsie! Something went wrong 🤪 pls contact support!&amp;quot;&lt;/p&gt;
&lt;h2&gt;ftag - classify your error chains&lt;/h2&gt;
&lt;p&gt;Another issue we kept running into was error chains that expressed a particular &lt;em&gt;type&lt;/em&gt; of problem, but inferring all possible types of problems was not trivial with the bare bones Go standard library errors.&lt;/p&gt;
&lt;p&gt;Well, I mean, it is but it involves either creating a number of custom error wrappers and searching for them with &lt;code&gt;errors.Is&lt;/code&gt; or copious amounts of string pattern matching.&lt;/p&gt;
&lt;p&gt;But the issue was, when a HTTP handler function handled an error, how was it meant to know which HTTP status code to send to the client? Now you can do approximately one status code with the Go standard library tools:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Is&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; sql&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;ErrNoRows&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  w&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WriteHeader&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusNotFound&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Which is fine if your only data source is SQL and your only possible type of response is 404 Not Found. But in real-world applications with all sorts of complex business logic happening, it&amp;#x27;s not always as simple as that.&lt;/p&gt;
&lt;p&gt;For example, a resource being not found may actually be a business logic violation, a failed precondition, to borrow from gRPC&amp;#x27;s nomenclature. So if your query threw a &amp;quot;not found&amp;quot; but your service layer is built under the assumption that the resource &lt;em&gt;does exist&lt;/em&gt; and if it doesn&amp;#x27;t, that&amp;#x27;s not just a simple &amp;quot;not found&amp;quot; it&amp;#x27;s an internal server error. Suddenly your &lt;code&gt;errors.Is&lt;/code&gt; isn&amp;#x27;t doing the right thing anymore.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-21-23-38.png&quot; alt=&quot;2024-04-07-21-23-38&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Now you&amp;#x27;re not alerting your team about 404 errors. Otherwise Slack would be full of alerts about requests to &lt;code&gt;/wp-admin&lt;/code&gt;. So allowing &amp;quot;not found&amp;quot; errors to creep through your service layer means your users are going to find out about bugs before your engineering team does.&lt;/p&gt;
&lt;h2&gt;Tag your error chains!&lt;/h2&gt;
&lt;p&gt;An &amp;quot;ftag&amp;quot;, or, Fault tag, is just a simple string attached to an error chain. There&amp;#x27;s only ever one and the most recently added will overwrite the previous. The default is &lt;code&gt;Internal&lt;/code&gt;&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;InvalidArgument&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The ftag library started life as &amp;quot;errtag&amp;quot; and it used an interface to describe a tag. But that was too awkward to use. Now, ftags are literally just simple strings. You can create your own, or you can use the built-in types which cover most common classes of problem that may occur:&lt;/p&gt;
&lt;p&gt;Code here:&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://github.com/Southclaws/fault/tree/master/ftag&quot;&gt;Southclaws/fault/ftag&lt;/a&gt;&lt;/p&gt;
&lt;h2&gt;Map ftags to HTTP status codes&lt;/h2&gt;
&lt;p&gt;Now you&amp;#x27;ve tagged all your error chains with the appropriate classification, you need to act upon it. Here&amp;#x27;s a simple helper that maps some of the ftag classifications to HTTP status codes:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;statusFromErrorKind&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;k ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Kind&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;token keyword&quot;&gt;switch&lt;/span&gt; k &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;token keyword&quot;&gt;case&lt;/span&gt; ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;InvalidArgument&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusBadRequest
	&lt;span class=&quot;token keyword&quot;&gt;case&lt;/span&gt; ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;NotFound&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusNotFound
	&lt;span class=&quot;token keyword&quot;&gt;case&lt;/span&gt; ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;AlreadyExists&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusConflict
	&lt;span class=&quot;token keyword&quot;&gt;case&lt;/span&gt; ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;PermissionDenied&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusForbidden
	&lt;span class=&quot;token keyword&quot;&gt;case&lt;/span&gt; ftag&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Unauthenticated&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusForbidden
	&lt;span class=&quot;token keyword&quot;&gt;default&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusInternalServerError
	&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;If you&amp;#x27;re using something like Echo with a top-level error handler, you can just call this there and set the response status code once. This means you don&amp;#x27;t have to write explicit repetitive error-handling code in every single handler.&lt;/p&gt;
&lt;h2&gt;End goals&lt;/h2&gt;
&lt;p&gt;My ultimate end goal was to make my team members&amp;#x27; lives easier by&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;making errors structured like logs are&lt;/li&gt;
&lt;li&gt;making it hard to forget to add relevant information&lt;/li&gt;
&lt;li&gt;reducing the need for explicit branching during error handling&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;And so far, after about a month in two production codebases, I&amp;#x27;m very pleased to report that error management has become boring and functional with minimal effort required.&lt;/p&gt;
&lt;p&gt;But I&amp;#x27;d also like to hear some feedback. The &lt;code&gt;func(error) error&lt;/code&gt; interface feels so simple and useful to facilitate flexibility in implementing small simple composable error utilities. I&amp;#x27;m wondering what else members of the Go community may do with this.&lt;/p&gt;
&lt;p&gt;If you read this far, thanks! it&amp;#x27;s a stark contrast to &lt;a href=&quot;https://twitter.com/Southclaws&quot;&gt;my low quality tweets&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Also, if you enjoy working on a codebase with high-quality error management (honestly, weirdly specific, but that&amp;#x27;s cool) &lt;a href=&quot;https://www.vouch.works/southclaws&quot;&gt;hit me up&lt;/a&gt; as we&amp;#x27;re hiring Go engineers!&lt;/p&gt;
&lt;h2&gt;Appendix&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;some notes on the above and the future of Fault&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3&gt;Naming&lt;/h3&gt;
&lt;p&gt;The fault sub-packages were originalled named:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;errctx&lt;/li&gt;
&lt;li&gt;errkind&lt;/li&gt;
&lt;li&gt;errmsg&lt;/li&gt;
&lt;li&gt;errmeta (deleted)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;And I made the decision to change the naming just to cut down on noise and play nicely with gopls giving suggestions. It sounds silly but just having the letter &lt;code&gt;f&lt;/code&gt; being the go-to for Fault as well as Fault&amp;#x27;s decorator utilities is handy.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-21-24-03.png&quot; alt=&quot;2024-04-07-21-24-03&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;h3&gt;Helpful snippets&lt;/h3&gt;
&lt;p&gt;Here&amp;#x27;s a snippet I use constantly for quickly setting up an error wrap site with Fault and fctx:&lt;/p&gt;
&lt;pre class=&quot;language-json&quot;&gt;&lt;code&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;if err != nil&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token property&quot;&gt;&quot;prefix&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;iferr&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token property&quot;&gt;&quot;body&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;
      &lt;span class=&quot;token string&quot;&gt;&quot;if err != nil {&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;token string&quot;&gt;&quot;\treturn nil, fault.Wrap(err, fctx.With(ctx))&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
      &lt;span class=&quot;token string&quot;&gt;&quot;}&quot;&lt;/span&gt;
    &lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token property&quot;&gt;&quot;description&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;Snippet for if err != nil&quot;&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Given that 99% of the time, there&amp;#x27;s always a &lt;code&gt;context.Context&lt;/code&gt; in scope, it saves time to just default to having an &lt;code&gt;fctx&lt;/code&gt; in there.&lt;/p&gt;
&lt;p&gt;That being said, if you&amp;#x27;re frequently using the same combination of decorators, it&amp;#x27;s probably worth writing a function that combines them:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;W&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ctx context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Context&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; msg &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; fctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; fmsg&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;With&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;msg&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;At the beginning of this article, I mentioned that I had configured a linter called &amp;quot;wrapcheck&amp;quot; to treat anything other than Fault as a warning. Here&amp;#x27;s how I did that using golangci-lint:&lt;/p&gt;
&lt;pre class=&quot;language-yaml&quot;&gt;&lt;code&gt;&lt;span class=&quot;token key atrule&quot;&gt;linters-settings&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
  &lt;span class=&quot;token key atrule&quot;&gt;wrapcheck&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;token key atrule&quot;&gt;ignoreSigs&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt;
      &lt;span class=&quot;token punctuation&quot;&gt;-&lt;/span&gt; fault.New(
      &lt;span class=&quot;token punctuation&quot;&gt;-&lt;/span&gt; fault.Newf(
      &lt;span class=&quot;token punctuation&quot;&gt;-&lt;/span&gt; fault.Wrap(
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This means you cannot use &lt;code&gt;errors.New&lt;/code&gt;, &lt;code&gt;errors.Errorf&lt;/code&gt;, &lt;code&gt;fmt.Errorf&lt;/code&gt;, &lt;code&gt;errors.Wrap&lt;/code&gt;, or any other error library in your codebase by accident.&lt;/p&gt;
&lt;p&gt;Not that it really matters, there&amp;#x27;s nothing about Fault&amp;#x27;s design that makes it not work with other error-wrapping libraries or root error constructors, it&amp;#x27;s just easier to stick to one wrapper with many small, simple use-case-specific decorators.&lt;/p&gt;
&lt;h3&gt;Side note 1: Forgetting stuff&lt;/h3&gt;
&lt;p&gt;I mentioned earlier that I didn&amp;#x27;t use &lt;code&gt;WithDescription&lt;/code&gt; because I simply forgot it existed. Part of why that happened I think was that for &lt;em&gt;so long&lt;/em&gt; my default was &lt;code&gt;errors.Wrap&lt;/code&gt;. Typing that for almost a decade builds muscle memory. If I&amp;#x27;m not hacking on a throwaway codebase, I typically would always wrap errors.&lt;/p&gt;
&lt;p&gt;Now I should point out that this was slowly becoming blind faith. Instead of actively thinking about what context was necessary at any given error wrap site, I would just write &amp;quot;failed to &lt;em&gt;verb&lt;/em&gt; the &lt;em&gt;noun&lt;/em&gt;&amp;quot;.&lt;/p&gt;
&lt;p&gt;Fault forces me to think again. If I&amp;#x27;m sitting there, staring at:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;fault&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I can&amp;#x27;t just default to a quote mark and a useless string of text that provides zero value to future readers of the error.&lt;/p&gt;
&lt;p&gt;Do I have a &lt;code&gt;context.Context&lt;/code&gt; in scope? Okay, &lt;code&gt;fctx.With(ctx)&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Is this something the user can maybe action? Was their input wrong or is the program in an invalid state that the user can resolve themselves without contacting support? Okay, &lt;code&gt;fmsg.WithDesc&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;Is the problem that occurred here completely find with sending back a 500 Internal Server error or is there a more semantic classification of this problem? Okay, &lt;code&gt;ftag.With&lt;/code&gt;.&lt;/p&gt;
&lt;h3&gt;Side note 2: Error containers&lt;/h3&gt;
&lt;p&gt;When you wrap an error with Fault, you can pass nothing at all. And given that Fault provides no built-in way of adding a string message to the error, you might be wondering what Fault is doing in that case.&lt;/p&gt;
&lt;p&gt;As with any error management library, you&amp;#x27;ll get some stack information to help you figure out where the problem is. Pretty standard stuff. See the Fault readme for information about that.&lt;/p&gt;
&lt;p&gt;In this sense, a Fault error (the underlying type returned from &lt;code&gt;Wrap&lt;/code&gt;) is more of an &lt;em&gt;error container&lt;/em&gt;. It&amp;#x27;s not representative of any surface level error information but it&amp;#x27;s more of a metadata wrapper around the underlying error value. This kind of breaks a few assumptions around the error type. Such as the return value of the &lt;code&gt;.Error()&lt;/code&gt; method.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-21-24-23.png&quot; alt=&quot;2024-04-07-21-24-23&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;Calling &lt;code&gt;.Error()&lt;/code&gt; on the outer-most error yields: &amp;quot;failed to perform task xyz: &lt;code&gt;&amp;lt;fctx&amp;gt;&lt;/code&gt;: connection refused&amp;quot;&lt;/p&gt;
&lt;p&gt;So what actually happens when you call &lt;code&gt;.Error()&lt;/code&gt;? Fault walks the error chain and &lt;em&gt;skips over&lt;/em&gt; any Fault containers (of which there may be a few in the chain if you&amp;#x27;re wrapping every single error). The non-Fault errors then simply contribute to that boring &lt;code&gt;&amp;quot;: &amp;quot;&lt;/code&gt; separated joined string I mentioned earlier.&lt;/p&gt;
&lt;p&gt;Though this does also introduce another problem for metadata providers. fmsg provides a string but fctx does not. So it simply returns &lt;code&gt;&amp;lt;fctx&amp;gt;&lt;/code&gt; from the &lt;code&gt;.Error()&lt;/code&gt; method.&lt;/p&gt;
&lt;p&gt;I wasn&amp;#x27;t quite sure what to do for this case as I&amp;#x27;m bordering what would be considered idiomatic usage of the &lt;code&gt;error&lt;/code&gt; interface. This seems fine, given that I&amp;#x27;m not actually making use of the output of &lt;code&gt;.Error()&lt;/code&gt; anywhere, Fault provides a much more useful &lt;code&gt;Flatten&lt;/code&gt; helper for getting a structured representation of an error chain.&lt;/p&gt;
&lt;p&gt;But it&amp;#x27;s an opportunity for improvement before v1.0 for sure.&lt;/p&gt;</description>
</item>
<item>
<title>Structured errors in Go</title>
<link>https://southcla.ws/structured-errors-in-go</link>
<guid isPermaLink="true">https://southcla.ws/structured-errors-in-go</guid>
<pubDate>Thu, 01 Sep 2022 00:00:00 GMT</pubDate>
<description>&lt;p&gt;This post documents a catalogue of experiments on the topic of error management in medium-sized Go programs, specifically HTTP APIs, with certain end goals in mind around ergonomics, syntactic salt and making the lives of everyone involved easier. The final result is a simple approach and a new library that I&amp;#x27;ve been using in production for a couple of months now.&lt;/p&gt;
&lt;p&gt;Error handling (or, more accurately, error &lt;em&gt;management&lt;/em&gt;) has always ended up being a hot topic with Go. Most likely because of two things. Firstly, Go&amp;#x27;s early ideas about error handling – as with a lot of Go&amp;#x27;s design – chose to steer away from commonly found implementations such as exception handling and opted for a vastly simpler (at least from an implementation perspective) approach: return values. Secondly, the smallest, simplest form of an error in Go is a string of text. This leaves a lot of room for building on top of the simple concept of a string of text.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;type&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;interface&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token function&quot;&gt;Error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Every Go programmer is familiar with this interface. The beauty in simplicity here is that any type that satisfies this interface is an error. This allows us to construct domain-specific types that satisfy our needs if those needs stretch beyond a simple string of text.&lt;/p&gt;
&lt;p&gt;Okay, so you know that. I did the one thing I hate in articles about some topic and described the absolute basics of said topic despite the fact that whoever is reading this already knows all of that before getting to the &lt;em&gt;actual&lt;/em&gt; content.&lt;/p&gt;
&lt;h2&gt;Structured logging&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;(unrelated to lumberjack unions)&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;I won&amp;#x27;t do that here, promise. You all know what structured logging is. It&amp;#x27;s basically a standard concept in most medium and larger systems. As &lt;a href=&quot;https://www.willett.io/posts/precepts/&quot;&gt;Brandon Willett writes&lt;/a&gt;, &lt;strong&gt;Structured logs are non-negotiable&lt;/strong&gt;.&lt;/p&gt;
&lt;p&gt;So what does this have to do with error handling? Well, first of all, let&amp;#x27;s define &lt;em&gt;error handling&lt;/em&gt; by showing what it&amp;#x27;s not:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;data&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; service&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;GetAccount&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; err
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is not error handling. Nothing about this code is handling anything. This is I-don&amp;#x27;t-know-what-to-do-with-this-error-so-you-deal-with-it.&lt;/p&gt;
&lt;p&gt;And this is fine and this is still one part of what I call error &lt;em&gt;management&lt;/em&gt; because there are a few different key events during the lifecycle of an error.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;data&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; service&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;GetAccount&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;failed to get account&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is somewhat more involved, and arguably, more useful error management. We&amp;#x27;re now annotating the error with a bit more context. So when we finally &lt;em&gt;handle&lt;/em&gt; the error, we will see the original error that &lt;code&gt;GetAccount&lt;/code&gt; produced as well as some &lt;em&gt;context&lt;/em&gt; relevant to the caller of &lt;code&gt;GetAccount&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;And this is &lt;em&gt;error management&lt;/em&gt; for a lot of Go code. Glueing strings together is – a lot of the time – &lt;em&gt;all you need&lt;/em&gt;.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;data&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; service&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;GetThing&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;id&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Wrapf&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;failed to get account: %v&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; id&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;So now, let&amp;#x27;s say the implementation of &lt;code&gt;GetAccount&lt;/code&gt; accesses a database and the database is offline, we would see something like:&lt;/p&gt;
&lt;pre class=&quot;language-none&quot;&gt;&lt;code&gt;failed to get account: 59: database connection refused
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The actual &lt;em&gt;handling&lt;/em&gt; of this error occurs elsewhere. I&amp;#x27;m willing to bet that within the majority of cases, where the service is some form of HTTP based API, the error handling happens near the service boundary.&lt;/p&gt;
&lt;p&gt;The service boundary for a HTTP server is a route handler. The typical approach is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;there&amp;#x27;s an error! oh no&lt;/li&gt;
&lt;li&gt;log.Error&lt;/li&gt;
&lt;li&gt;http.StatusInternalServerError&lt;/li&gt;
&lt;li&gt;the user tweets the error screen to your company account and everyone is slightly less happy&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Step 2 is what we&amp;#x27;re interested in here. &lt;em&gt;Handling&lt;/em&gt; an error in this example means we tell someone about it. That someone is, again, in the majority of cases, probably a log aggregator and an alerting system and, eventually, a human.&lt;/p&gt;
&lt;p&gt;Now, log aggregators are incredibly powerful. You can filter based on the service, the account that made the request, the trace ID, the filename that the log entry originated from, the region the service is running in, and infinitely more options. This is extremely useful for diagnosing issues at scale.&lt;/p&gt;
&lt;p&gt;But you can only do all of that stuff if you &lt;em&gt;actually&lt;/em&gt; structure your log entries. And this is not very structured:&lt;/p&gt;
&lt;pre class=&quot;language-json&quot;&gt;&lt;code&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;message&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;failed to get account: 59: database connection refused&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;level&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;error&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;file&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;api/get_user.go:56&quot;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I can&amp;#x27;t filter all logs by account &amp;quot;59&amp;quot;. Well, I can, I can search for the string of text &amp;quot;account: 59&amp;quot; but that won&amp;#x27;t help when developers use slightly different wording in their messages. Strings of text are for humans to read after all.&lt;/p&gt;
&lt;p&gt;In a perfect world, it would be nice to do this:&lt;/p&gt;
&lt;pre class=&quot;language-json&quot;&gt;&lt;code&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;message&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;failed to get account: 59: database connection refused&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;level&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;error&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;file&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;api/get_user.go:56&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token property&quot;&gt;&quot;account_id&quot;&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;59&quot;&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Which you can do with any structured logging library, but there&amp;#x27;s a wide gap between your error value and your &lt;code&gt;log.Info&lt;/code&gt; call. You can solve this by creating a custom type that satisfies the &lt;code&gt;error&lt;/code&gt; interface:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;type&lt;/span&gt; AccountError &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  message   &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;
  AccountID &lt;span class=&quot;token builtin&quot;&gt;int&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;a &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;AccountError&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; a&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;message
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then, when you handle the error, you can check if the error is of this type and pull out the account ID for logging.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;var&lt;/span&gt; ae &lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;AccountError
&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;As&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;&amp;#x26;&lt;/span&gt;ae&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token comment&quot;&gt;// add ae.AccountID to the structured logging call&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;That&amp;#x27;s a lot of work, imagine doing that on a large system with many different kinds of resources, many different kinds of metadata you want to include with logs. It would be easier if you could just store a &lt;code&gt;map[string]string&lt;/code&gt; of metadata and log that, right?&lt;/p&gt;
&lt;h2&gt;The importance of being ergonomic&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;(not a yoga ad)&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;One thing I&amp;#x27;ve noticed throughout my career in myself, coworkers and open source collaborators I&amp;#x27;ve worked with is that if you make good things hard to do, people won&amp;#x27;t do them.&lt;/p&gt;
&lt;p&gt;Take testing as an example. I wrote a bunch of C++ early on in my software authorship and writing tests for C++ is a whole ordeal. You need a completely separate independent tool to handle the dance of compiling and linking your code as a separate binary with a bunch of extra tooling, macros and functions to facilitate telling the test system where your test functions are.&lt;/p&gt;
&lt;p&gt;Compare that to Go where 1. it&amp;#x27;s built into the toolchain and 2. you literally just add &amp;quot;_test&amp;quot; to your filename. This is so simple that it removes all barriers to writing tests. Easy to write means developers actually do it early instead of ending every PR with a commit titled &amp;quot;add tests&amp;quot;.&lt;/p&gt;
&lt;p&gt;I&amp;#x27;ve still never written a single C++ test, I couldn&amp;#x27;t get the tooling to work with my CMake setup and my compiler configuration so I gave up. Not ergonomic.&lt;/p&gt;
&lt;h2&gt;The ergonomics of errors&lt;/h2&gt;
&lt;p&gt;When it comes to errors, Go does have a fairly ergonomic mechanism. You write a message, maybe add another message, you read it later in the logs and figure out what went wrong. It&amp;#x27;s easy to create errors and it&amp;#x27;s easy to add context to error chains.&lt;/p&gt;
&lt;p&gt;With custom error structs however, it&amp;#x27;s a lot of writing to create your own error type and thus it becomes more of a burden to encourage your team members to do this. I&amp;#x27;ve worked in codebases where there are a couple of custom errors for special cases but most of the time it ends up just being &lt;code&gt;errors.Wrap(err, &amp;quot;thing failed to do stuff&amp;quot;)&lt;/code&gt; which, the majority of the time, I do not find that it adds value to the diagnostic process when things go wrong.&lt;/p&gt;
&lt;p&gt;The key is to build this concept into your entire codebase so it doesn&amp;#x27;t get forgotten. If every single instance of error handling does X, Y and Z then when new developers join your team, they will notice that and follow convention.&lt;/p&gt;
&lt;h2&gt;Design&lt;/h2&gt;
&lt;p&gt;So we want ergonomics? Let&amp;#x27;s start from the top. Forget implementation details, we care about the &lt;code&gt;user experience&lt;/code&gt; of our error management solution. Treat your libraries like products and your team as end-users and you&amp;#x27;ll have a happy team.&lt;/p&gt;
&lt;p&gt;What we want is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;to decorate errors with metadata&lt;/li&gt;
&lt;li&gt;to easily access that metadata when it comes to logging the problem or sending a response to the client.&lt;/li&gt;
&lt;li&gt;make it stupid simple&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;So I&amp;#x27;m going to copy the popular Go structured logging library, Logrus, for this example. It&amp;#x27;s widely used so it&amp;#x27;s probably doing something right when it comes to ease-of-use.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;log&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WithFields&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;log&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Fields&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token string&quot;&gt;&quot;event&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; event&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string&quot;&gt;&quot;topic&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; topic&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token string&quot;&gt;&quot;key&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; key&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Fatal&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;Failed to send event&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;What we want is something similar to this. Let&amp;#x27;s sketch it out:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; Fields&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;token string&quot;&gt;&quot;event&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; event&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token string&quot;&gt;&quot;topic&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; topic&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;token string&quot;&gt;&quot;key&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;:&lt;/span&gt; key&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Looks good! We&amp;#x27;re wrapping the error and the wrapper function takes a second argument that a developer &lt;em&gt;must&lt;/em&gt; fill with a &lt;code&gt;Fields&lt;/code&gt; object.&lt;/p&gt;
&lt;p&gt;And at the other end, we just need to easily pull out the data in a form that&amp;#x27;s simple to pass directly to a call to our logging library:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  metadata &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;GetErrorFields&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  log&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WithFields&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;metadata&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;failed to handle request&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  w&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Write&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;http&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;StatusInternalServerError&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Perfect! We now have structured errors, compatible with structured logging. It&amp;#x27;s low effort to use and the benefits when diagnosing issues are huge.&lt;/p&gt;
&lt;p&gt;And I actually wrote this in early 2022 for &lt;a href=&quot;https://joinodin.com/&quot;&gt;Odin&amp;#x27;s&lt;/a&gt; codebase because problems were becoming increasingly difficult to diagnose due to poor error messages. The logging helper was added to one slice of the application to try it out. It made diagnosing bugs both at development time and in production vastly simpler since I had decorated many of our error returns with additional contextual metadata to aid searching in Datadog.&lt;/p&gt;
&lt;p&gt;But the problem here is there was still an immense amount of manual work required to add all these bits of metadata to error returns. One call to &lt;code&gt;Wrap&lt;/code&gt; is fine but if you have a complex piece of business logic with 10 or more &lt;code&gt;if err != nil&lt;/code&gt;&amp;#x27;s scattered around, it suddenly becomes a lot of work and that hurts the ergonomics.&lt;/p&gt;
&lt;h2&gt;Bridging the context gap&lt;/h2&gt;
&lt;p&gt;I&amp;#x27;ve been using this word &lt;em&gt;context&lt;/em&gt; quite a bit already throughout this article. This word is defined by Oxford as:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;the circumstances that form the setting for an event, statement, or idea, and in terms of which it can be fully understood.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Go&amp;#x27;s adequately named &amp;quot;context&amp;quot; library does exactly this for call trees. It&amp;#x27;s a tool that&amp;#x27;s widely used for cancelling or giving deadlines to long-running operations but it can also be used to store information and carry that information throughout a call tree.&lt;/p&gt;
&lt;p&gt;Now this powerful functionality is not to be taken lightly. Contexts involve a few allocations when reading or writing information (many more than passing arguments or accessing receivers) and from a core software engineering standpoint, contexts can serve to hide information as it&amp;#x27;s essentially a black box. You cannot iterate contexts and print out their contents. You must &lt;em&gt;know&lt;/em&gt; what you&amp;#x27;re looking for via a &amp;quot;context key.&amp;quot;&lt;/p&gt;
&lt;p&gt;So while I&amp;#x27;m advocating for careful and considerate use of Go&amp;#x27;s context library, I&amp;#x27;m also saying &lt;a href=&quot;https://isburmistrov.substack.com/p/all-you-need-is-wide-events-not-metrics&quot;&gt;stuff it full of as much metadata as you can find&lt;/a&gt;. But seriously, as long as your actual business logic isn&amp;#x27;t dependent on the content of a context, I have found the tool quite useful for storing metadata about a call tree or an operation that can be accessed for non-business logic related operations such as logging and error management.&lt;/p&gt;
&lt;p&gt;In reality, this looks like this:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;ctx &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;WithMetadata&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;account_id&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; accountID&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ctx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;

metadata &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;GetErrorFields&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token comment&quot;&gt;// map[string]any{&quot;account_id&quot;: 59}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Contexts only accrue information as they descend into a call tree. Once you return from a function where a context has been wrapped with any of the &amp;quot;With&amp;quot; APIs you often see in Go (&lt;code&gt;WithDeadline&lt;/code&gt;, &lt;code&gt;WithTimeout&lt;/code&gt; and my addition above, &lt;code&gt;WithMetadata&lt;/code&gt;) that information is freed. So you can&amp;#x27;t do this:&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Y&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Context&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  ctx &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WithValue&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;key&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;token string&quot;&gt;&quot;value&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;X&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Context&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
  &lt;span class=&quot;token function&quot;&gt;Y&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;

  ctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Value&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token string&quot;&gt;&quot;key&quot;&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token comment&quot;&gt;// nothing, nil, zilch, it&apos;s gone&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is because when you &amp;quot;wrap&amp;quot; a context, you&amp;#x27;re creating a copy which is only sticking around for the duration of that stack frame. Once you return from a function you lose your modified context. There&amp;#x27;s no two-way state manipulation (a good thing) so you can&amp;#x27;t decorate a call tree on the way down and then read that information back at the top.&lt;/p&gt;
&lt;h2&gt;Errors are context in reverse&lt;/h2&gt;
&lt;p&gt;Hot take. But if you squint a bit, errors are basically contexts but they operate on the ascending side of the call tree, not the descending side.&lt;/p&gt;
&lt;p&gt;Contexts accrue information as they descend the call tree and errors accrue information as they ascend the call tree.&lt;/p&gt;
&lt;p&gt;This means that, if you want to store structured metadata in a context, that information is only useful if you pass it to an error so that metadata can ride the call tree ascension like a rollercoaster all the way up to the top where it&amp;#x27;s actually useful.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://southcla.ws/images/2024-04-07-17-08-55.png&quot; alt=&quot;2024-04-07-17-08-55&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;The Von-Neumann architecture is basically a rollercoaster. You can either go up or down and usually, if you&amp;#x27;re going backwards there&amp;#x27;s a small chance shit hit the fan. (by &lt;a href=&quot;https://unsplash.com/@mboulden?utm_source=ghost&amp;amp;utm_medium=referral&amp;amp;utm_campaign=api-credit&quot;&gt;Meg Boulden / Unsplash&lt;/a&gt;)&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;Putting it all together&lt;/h2&gt;
&lt;p&gt;Okay it&amp;#x27;s about time we had some code. We need a context key, a helper to top up a context with some metadata and another helper to get it out again.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;type&lt;/span&gt; contextKey &lt;span class=&quot;token keyword&quot;&gt;struct&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;WithMeta&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Context&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; kv &lt;span class=&quot;token operator&quot;&gt;...&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Context &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
	&lt;span class=&quot;token keyword&quot;&gt;var&lt;/span&gt; data &lt;span class=&quot;token keyword&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;

	&lt;span class=&quot;token comment&quot;&gt;// overwrite any existing context metadata&lt;/span&gt;
	&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; meta&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ok &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; ctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Value&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;contextKey&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token keyword&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; ok &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
		data &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; meta
	&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;else&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
		data &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;make&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token keyword&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

	l &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;kv&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;token keyword&quot;&gt;for&lt;/span&gt; i &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; i &lt;span class=&quot;token operator&quot;&gt;&amp;#x3C;&lt;/span&gt; l&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; i &lt;span class=&quot;token operator&quot;&gt;+=&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;2&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
		k &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; kv&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;i&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;
		v &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; kv&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;i&lt;span class=&quot;token operator&quot;&gt;+&lt;/span&gt;&lt;span class=&quot;token number&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;

		data&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;k&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; v
	&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

	&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;WithValue&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;ctx&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; contextKey&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; data&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Because we intend to call this multiple times during a call tree, any successive calls to wrapped contexts will already contain metadata. Now I&amp;#x27;ve opted for an extremely simple approach of essentially copying all the fields, if there are any, into the newly wrapped context. This could be an opportunity for memory usage optimisation but that&amp;#x27;s for another day.&lt;/p&gt;
&lt;p&gt;Now we need to wrap errors and store the context&amp;#x27;s metadata hash table into the error, simple stuff.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;type&lt;/span&gt; withContext &lt;span class=&quot;token keyword&quot;&gt;struct&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
	cause &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt;
	meta  &lt;span class=&quot;token keyword&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

&lt;span class=&quot;token comment&quot;&gt;// Omitted: the error implementation that actually makes this an error.&lt;/span&gt;

&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Wrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ctx context&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;Context&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
	meta&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ok &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; ctx&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Value&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;contextKey&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token keyword&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;!&lt;/span&gt;ok &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; err
	&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

	&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;&amp;#x26;&lt;/span&gt;withContext&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; meta&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;And finally, a way to get the metadata information (or a zero-value) out of any error value.&lt;/p&gt;
&lt;pre class=&quot;language-go&quot;&gt;&lt;code&gt;&lt;span class=&quot;token keyword&quot;&gt;func&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;Unwrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err &lt;span class=&quot;token builtin&quot;&gt;error&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
	values &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;token builtin&quot;&gt;string&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

	&lt;span class=&quot;token keyword&quot;&gt;for&lt;/span&gt; err &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; f&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; ok &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; err&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;token operator&quot;&gt;*&lt;/span&gt;withContext&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; ok &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
			&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; m &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; f&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;meta&lt;span class=&quot;token punctuation&quot;&gt;;&lt;/span&gt; m &lt;span class=&quot;token operator&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
				&lt;span class=&quot;token keyword&quot;&gt;for&lt;/span&gt; k&lt;span class=&quot;token punctuation&quot;&gt;,&lt;/span&gt; v &lt;span class=&quot;token operator&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;token keyword&quot;&gt;range&lt;/span&gt; m &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
					values&lt;span class=&quot;token punctuation&quot;&gt;[&lt;/span&gt;k&lt;span class=&quot;token punctuation&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; v
				&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
			&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
		&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

		err &lt;span class=&quot;token operator&quot;&gt;=&lt;/span&gt; errors&lt;span class=&quot;token punctuation&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;token function&quot;&gt;Unwrap&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;err&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt;
	&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

	&lt;span class=&quot;token keyword&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;token function&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;token punctuation&quot;&gt;(&lt;/span&gt;values&lt;span class=&quot;token punctuation&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;token operator&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;token number&quot;&gt;0&lt;/span&gt; &lt;span class=&quot;token punctuation&quot;&gt;{&lt;/span&gt;
		&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;token boolean&quot;&gt;nil&lt;/span&gt;
	&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;

	&lt;span class=&quot;token keyword&quot;&gt;return&lt;/span&gt; values
&lt;span class=&quot;token punctuation&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Because errors in Go are essentially nested within each other like Russian dolls, we need to iterate the tree of errors by repeatedly calling &lt;code&gt;errors.Unwrap(err)&lt;/code&gt; which is pretty much how many error management code works. We&amp;#x27;re basically searching through the chain for an instance of the type we&amp;#x27;re interested in.&lt;/p&gt;
&lt;p&gt;Lots of error code does this repeated unwrapping, which sounds like it could be a performance concern in larger applications but there&amp;#x27;s an argument to be made that if your error handling code is your biggest performance concern then you need to either 1. stop causing so many errors or 2. use a different language!&lt;/p&gt;
&lt;h2&gt;Things to watch out for&lt;/h2&gt;
&lt;p&gt;Great power, great responsibility and all that. As with any kind of logging system that&amp;#x27;s moving information from your application to a third party you must &lt;em&gt;must&lt;/em&gt; &lt;strong&gt;must&lt;/strong&gt; avoid including any sort of PII (personally identifiable information) in your context, errors and logs unless you want to fail your SOC2 certification.&lt;/p&gt;
&lt;p&gt;When decorating errors, the same rules as using logging applies. There are many great articles on this topic, but in summary, avoid:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Email addresses&lt;/li&gt;
&lt;li&gt;Names, even if just first name&lt;/li&gt;
&lt;li&gt;Any form of institutional identifier such as social security, financial, healthcare numbers.&lt;/li&gt;
&lt;li&gt;Any kind of public social media handle&lt;/li&gt;
&lt;li&gt;(hopefully extremely obvious) bank information like credit card numbers or routing+account numbers&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Some tips for what metadata can be included and will help you when diagnosing issues:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Anonymous internal unique identifiers of any kind (user IDs, account IDs, company IDs...) any of them you have available, stick them in your context. You&amp;#x27;ll thank yourself later.&lt;/li&gt;
&lt;li&gt;Relevant timestamps. Obviously you have the timestamp of the log entry already but if you have any other timestamps available that are relevant to your business domain, include them so you can perform time-range queries.&lt;/li&gt;
&lt;li&gt;Slugs are often useful if you have non-technical/QA looking at your logs. Slugs are human-readable URL friendly names often used for things like blog posts or public resources (like a GitHub repository or a customer&amp;#x27;s subdomain)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;And of course, you&amp;#x27;ll still run the risk of some developers using different naming conventions to other developers in key names, &lt;code&gt;user_id&lt;/code&gt; vs &lt;code&gt;userID&lt;/code&gt; for example. So establish a convention and stick to it. Use a centralised package of const strings and custom types to cause compiler errors if you need to. Make mistakes difficult.&lt;/p&gt;
&lt;h2&gt;Here&amp;#x27;s one I made earlier&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;(brits older than 25 who used to watch cbbc, iykyk)&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Of course, it wouldn&amp;#x27;t be a technical article if I wasn&amp;#x27;t going to shill something I made. All of the above was essentially the experimental journey I went through to improve how errors work in a number of codebases I maintain and operate in production settings.&lt;/p&gt;
&lt;p&gt;I&amp;#x27;ve used those learnings to write (and rewrite about 3 times, based on feedback from many a Go engineer) a fairly simple but also pluggable error management library which includes the structured errors functionality discussed in this post as well as some other useful tools.&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://github.com/Southclaws/fault&quot;&gt;https://github.com/Southclaws/fault&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;Now, because of the way this library is architected, you can just use the error context utility called &lt;a href=&quot;https://github.com/Southclaws/fault/blob/master/README.md#fctx&quot;&gt;fctx&lt;/a&gt; on its own as it satisfies the Fault wrapper interface as well as the commonly used &lt;code&gt;Wrap(error, stuff...)&lt;/code&gt; pattern used in many libraries.&lt;/p&gt;
&lt;p&gt;There will also be a future post diving deeper into some of the technical bits and rationale behind Fault and how I use it in production systems. So keep an eye out for that!&lt;/p&gt;
&lt;p&gt;If you made it this far, thank you for reading! I hope this helps you navigate Go errors in larger applications. Feedback on the concepts and writing is greatly appreciated so &lt;a href=&quot;https://twitter.com/Southclaws&quot;&gt;feel free to tweet me&lt;/a&gt;.&lt;/p&gt;</description>
</item>
<item>
<title>The Stockholm Syndrome of SQL</title>
<link>https://southcla.ws/sql</link>
<guid isPermaLink="true">https://southcla.ws/sql</guid>
<pubDate>Sun, 26 Jun 2022 00:00:00 GMT</pubDate>
<description>&lt;blockquote&gt;
&lt;p&gt;This is part 1 of a series analysing the relational database landscape and criticising the design of Structured Query Language.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Our ecosystem of technology tools is modelled after a free market. We have many platforms, tooling and people competing to be the best. The best browser, the best language, the best text editor, the best terminal emulator, the best shell, the best line of text that appears above the bit where you type commands into the terminal. There&amp;#x27;s competition everywhere and that&amp;#x27;s great. It&amp;#x27;s great for the people who build infrastructure and products because better tools make their job easier. It&amp;#x27;s also great for the people using that infrastructure and those products because they get a better experience doing whatever they need to do with those things.&lt;/p&gt;
&lt;p&gt;A question I&amp;#x27;ve asked myself, my mentors, my friends and colleagues is: what&amp;#x27;s the deal with databases and why is there no rich free market of competing ideas?&lt;/p&gt;
&lt;p&gt;I&amp;#x27;m often met with responses such as:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;SQL is &lt;em&gt;fine&lt;/em&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;blockquote&gt;
&lt;p&gt;Don&amp;#x27;t fix what ain&amp;#x27;t broken.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;blockquote&gt;
&lt;p&gt;Everyone uses it, why try to change?&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Which is, honestly, odd. Considering this is the industry within which there are entire movements, almost religious in nature, around fixing and replacing old tools with new tools.&lt;/p&gt;
&lt;p&gt;Of course, asking these questions as a developer straight out of university was normal. The general vibe was that this bright-eyed-and-bushy-tailed desire to make everything perfect would soon disappear. But I&amp;#x27;m now a senior engineer, I&amp;#x27;ve built a ton of products and tools, from dev tools to consumer apps and I&amp;#x27;ve written a huge amount of database-related code from simple queries to long chains of ORM method calls and all manner of multi-level joins, recursive spaghetti and the odd MongoDB aggregation. I&amp;#x27;ve still got a lot to learn at this stage in my career, but I feel like I&amp;#x27;m at a point where I can vocalise my thoughts on this gap in the market.&lt;/p&gt;
&lt;h2&gt;So let&amp;#x27;s talk about the &lt;em&gt;free market of software&lt;/em&gt;.&lt;/h2&gt;
&lt;p&gt;&lt;em&gt;just call me the trustbuster big data 🧑‍⚖️&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;TypeScript is an entire language backed by a trillion-dollar corporation with the sole purpose of reducing the likelihood of &lt;code&gt;undefined is not a function&lt;/code&gt; popping up in error messages. This exists as a compile-to-JavaScript language, of which there are many! JavaScript is sort of a Rosetta&amp;#x27;s Stone of code.&lt;/p&gt;
&lt;p&gt;Deno was started by Ryan Dahl, who created Node.js, in an effort to provide a better platform to build applications using V8. Deno throws out backwards compatibility in an attempt to start fresh and &amp;quot;do things right&amp;quot;. It has a decent following and looks somewhat promising. It uses normal TypeScript, compiles to JavaScript under the hood and executes on the V8 runtime. It&amp;#x27;s basically Node.js but with native TypeScript support and a different approach to dependency management.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://substackcdn.com/image/fetch/w_1456,c_limit,f_webp,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F74faa725-7660-49c2-8904-2cc3994ac03c_512x512.svg&quot; alt=&quot;the deno dino, because all good software products need a cute mascot&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;LLVM and JVM both facilitate the existence of about 16 major languages (not including small side projects and non-commercial stuff) they are both low-ish level platforms that provide a runtime, optimisation and cross-platform usage. If you write a new programming language and it can be compiled with LLVM or JVM, your new language will run on basically any computer on the planet.&lt;/p&gt;
&lt;p&gt;There are three major web browsers currently on the market: Chrome, Firefox and Safari. They all have slightly different advantages. It can be frustrating for a developer sometimes to build websites and web experiences because of this but it&amp;#x27;s all for a net good: consumer choice, innovation and market competition. Safari introduced a way to check if the user prefers a dark colour scheme and shortly after it became standard across all browsers. Firefox created development tools and they are ubiquitous nowadays. Chrome pushed for WebAssembly and that... exists now, so that&amp;#x27;s cool I guess.&lt;/p&gt;
&lt;p&gt;You get the idea, there are examples of the market competition model all over this industry. Even though the vast majority of these products are often free to use, open source and accessible they are still treated as products and the teams building them still treat competing products as competition.&lt;/p&gt;
&lt;h2&gt;The Database Market&lt;/h2&gt;
&lt;p&gt;&lt;em&gt;it&amp;#x27;s far less interesting, trust me&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Pretty much every mainstream relational database out there uses some dialect of SQL. There are no mainstream relational databases that use any other method of interfacing with the data. Of the top 10 databases according to db-engines.com, 7 of them are relational and all of these use SQL.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://substackcdn.com/image/fetch/f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F382fb802-3ee5-4652-b099-76ad884c10de_1346x892.png&quot; alt=&quot;&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;This isn&amp;#x27;t very diverse. Each database has its own dialect of SQL with innovations on top of the base language but there are no really new ideas here.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;SQL is actually a &lt;a href=&quot;https://en.wikipedia.org/wiki/Backronym&quot;&gt;backronym&lt;/a&gt;! It was originally named &amp;quot;sequel&amp;quot; as in, a sequel to SQUARE (Specifying queries using a relational environment, yes that&amp;#x27;s a whole mouthful. Why do nerds love long acronyms so much?) So next time you&amp;#x27;re arguing with someone about how to pronounce SQL, you can drop this knowledge bomb.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;SQL was designed in 1973 and made available in 1979. It hasn&amp;#x27;t really changed much since unlike the rest of the software development world.&lt;/p&gt;
&lt;p&gt;&lt;span&gt;&lt;img loading=&quot;lazy&quot; src=&quot;https://substackcdn.com/image/fetch/f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F156dcb76-396c-44c3-82e0-b1f4b9c2d112_600x470.png&quot; alt=&quot;an IBM database admin mixing on a turntable in order to perform a join query
&quot;/&gt;&lt;/span&gt;&lt;/p&gt;
&lt;p&gt;&lt;em&gt;an IBM database admin mixing on a turntable in order to perform a join query&lt;/em&gt;&lt;/p&gt;
&lt;h2&gt;The Problems&lt;/h2&gt;
&lt;p&gt;&lt;em&gt;here&amp;#x27;s the actual criticism part&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;Because there&amp;#x27;s a lot to unpack here regarding what&amp;#x27;s actually problematic with the status quo of relational databases, I&amp;#x27;m going to summarise the issues here and expand in future posts.&lt;/p&gt;
&lt;p&gt;I&amp;#x27;m aiming to keep this less of a rant and more of a set of proposals for future work in the relational database market. Each future post will outline the issue and a detailed solution in a hypothetical new product.&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Human machine interface vs. application programming interface, why not both?&lt;/li&gt;
&lt;li&gt;A language within a language via string literals is how you lose all static analysis and type safety.&lt;/li&gt;
&lt;li&gt;SQL is too high level to foster an ecosystem of novel approaches to interface design.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Shout at me on Twitter &lt;a href=&quot;https://twitter.com/Southclaws&quot;&gt;@Southclaws&lt;/a&gt; if you want to voice your opinion on any of these particular points.&lt;/p&gt;
&lt;h2&gt;Isn&amp;#x27;t all this just a huge waste of time?&lt;/h2&gt;
&lt;p&gt;&lt;em&gt;trying to change the status quo may feel like a Sisyphean task but there&amp;#x27;s value in it&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;The SQL specification is fairly antithetical to the open source and free software world. You have to pay to get access to the latest ANSI specification. If a budding new software engineer wanted to dig into this document for whatever reason and understand what text is behind the world&amp;#x27;s most common data query language, they need to fork out £150 which is a LOT of money if you&amp;#x27;re not already earning a fairly decent software engineer&amp;#x27;s salary in the US, UK or Europe.&lt;/p&gt;
&lt;p&gt;Meanwhile, I can freely access the POSIX specification, the HTTP specification, the ECMAScript specification (better known as JavaScript), the TCP Specification (or anything written by the IETF, which are actual web pages not awkward PDF files). I can take essentially any existing technology the world&amp;#x27;s software depends on and build my own version of it and test my implementation against a written specification.&lt;/p&gt;
&lt;p&gt;If I do decide to pay the price and read the spec, I&amp;#x27;m greeted with a huge document because SQL is a huge complex language (and it&amp;#x27;s FAR from structured and FAR from declarative). I read part of the ANSI 1999 specification which is 23 chapters spread over a thousand pages. Every spec gets ever more complex.&lt;/p&gt;
&lt;p&gt;Sound familiar? C++ suffers the same fate. To the point where professional C++ programmers I know have told me their company just sticks with C++11 because the majority of the new &amp;quot;features&amp;quot; in 17 and 21 are superfluous.&lt;/p&gt;
&lt;p&gt;There are plenty of examples of attempts, some successful, to break away from status quos and build something better. Go, Rust and Deno are brilliant examples of these. Both Rust and Deno aim to not only provide languages but also ecosystems. Rust&amp;#x27;s Cargo and rustup tooling is far superior to the sparse landscape of C++ package managers and compilers. Deno throws out compatibility for a newer Go-inspired approach to dependency management. I&amp;#x27;d honestly like to see a similar movement in the database world.&lt;/p&gt;
&lt;h2&gt;Prior art&lt;/h2&gt;
&lt;p&gt;&lt;em&gt;some people are already trying to build better tooling for databases, most of this work builds on top of SQL similar to how languages build on top of JavaScript.&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;There are some great projects out there that are attempting to make working with databases easier. I do think all of these are just frankenstein&amp;#x27;s monster style abstractions on the ever still complexity that is SQL though.&lt;/p&gt;
&lt;h3&gt;EdgeDB&lt;/h3&gt;
&lt;p&gt;Back in 2019, &lt;a href=&quot;https://www.edgedb.com/blog/we-can-do-better-than-sql&quot;&gt;Elvis Pranskevichus wrote &amp;quot;We Can Do Better Than SQL&amp;quot;&lt;/a&gt; and it was received with a fairly decent sentiment across Hacker News and Lobsters. There&amp;#x27;s a lot of &amp;quot;don&amp;#x27;t fix what ain&amp;#x27;t broken&amp;quot; mentality and no desire to innovate on the HN side (which is to be expected...) but there&amp;#x27;s a clear desire between those replies for something novel in the database world.&lt;/p&gt;
&lt;p&gt;That being said, I don&amp;#x27;t think EdgeDB really solves the problem. It&amp;#x27;s still a string-literal oriented query language not an API. Sure, it proposes some more logical syntax but it&amp;#x27;s still a whole new language. See Part 1 of the follow-up posts for more details on this.&lt;/p&gt;
&lt;h3&gt;Prisma&lt;/h3&gt;
&lt;p&gt;I love this tool. It&amp;#x27;s really something useful that saves a ton of time while not succumbing to the usual downsides of traditional ORMs (the ones that map objects to relations). I think there&amp;#x27;s a lot the database world can learn from Prisma. It solves the type safety and schema source of truth problems (outlined in Part 2) by generating type-safe code.&lt;/p&gt;
&lt;p&gt;This is not without criticism though, some of the existing complaints behind ORMs are valid for Prisma. Such as the need to perform more complex queries not being satisfied by the generated code. Another issue is the code generator must support your language. Prisma users have already been burned by this &lt;a href=&quot;https://github.com/prisma/prisma-client-go/issues/707&quot;&gt;when they dropped support for Go&lt;/a&gt;.&lt;/p&gt;
&lt;h3&gt;Ent&lt;/h3&gt;
&lt;p&gt;Ent is the go-to replacement for Prisma for Go developers. It&amp;#x27;s another code generating, database-first tool for Go programs to talk to relational databases. I&amp;#x27;ve been using this on a few projects since 2021 and it&amp;#x27;s fantastic. I&amp;#x27;ve not had to write any raw SQL yet apart from one instance where I needed a recursive common table expression.&lt;/p&gt;
&lt;p&gt;Ent feels like the canonical database adapter for Go. I&amp;#x27;m using it for all my Go projects now and I have no real complaints except how the source-code-based schema definition is quite complex and requires frequent reading of the documentation combined with trial and error. Prisma&amp;#x27;s fully declarative schema format that also generated safe migrations is hard to beat.&lt;/p&gt;
&lt;h3&gt;sqlc&lt;/h3&gt;
&lt;p&gt;This is another Go tool (I&amp;#x27;m a Go programmer by profession so naturally a lot of my evaluations are in the Go ecosystem). This one parses .sql files and uses that to generate Go code that binds the arguments to the SQL statements.&lt;/p&gt;
&lt;p&gt;It&amp;#x27;s a neat idea, and definitely a solid choice if you don&amp;#x27;t mind writing raw SQL. One benefit of writing .sql files is you can get (sometimes) decent editor integration if your editor is hooked up to a live database (since SQL has no native way of writing declarative schemas, you have to connect to a running database.)&lt;/p&gt;
&lt;h3&gt;Visual Paradigm&lt;/h3&gt;
&lt;p&gt;This is an old-school business process modelling suite that also happens to provide code generation from database schema definitions! It&amp;#x27;s actually the only other tool I could find that does this. It works with Java only.&lt;/p&gt;
&lt;h3&gt;CockroachDB&lt;/h3&gt;
&lt;p&gt;I&amp;#x27;m throwing this in here because this is an example of a modern implementation of an SQL database that&amp;#x27;s PostgreSQL compatible. It&amp;#x27;s written in Go and has venture backing driving the development of the software. Cockroach Labs also provide a cloud offering which claims to be scalable across regions.&lt;/p&gt;
&lt;p&gt;Their blog is a brilliant resource for the internals and the database core is open source so it&amp;#x27;s been a great learning resource for me!&lt;/p&gt;
&lt;p&gt;But what I really think is impressive with CRDB is how they&amp;#x27;ve managed to disrupt the status quo. Being PostgreSQL compatible and horizontally scalable is a huge sell for large applications which need to store a ton of data and be fail resistant.&lt;/p&gt;
&lt;p&gt;Now one interesting detail is that CockroachDB isn&amp;#x27;t fully conforming of the SQL specification or even PostgreSQL&amp;#x27;s dialect and features. Yet it still rose to fame and became a fantastic tool. Why? Because a lot of applications literally just need four features: Create, Read, Update, Delete. What CockroachDB really shines in is providing an amazing overall experience all the way from deployment to querying to scaling out.&lt;/p&gt;
&lt;h2&gt;In Conclusion&lt;/h2&gt;
&lt;p&gt;there are some great tools out there but a lot of them, in my opinion, don&amp;#x27;t quite solve the true underlying problems with existing relational databases. I think there&amp;#x27;s a lot that can be learnt from CockroachDB, Rust, Go and Deno focusing on the ecosystem and toolchain side of things and understanding that they don&amp;#x27;t need to be perfect and satisfy every use-case. If a language has decent package management, decent performance, decent community and decent compile-time then it&amp;#x27;s far superior to a language that only has perfect performance and sucks everywhere else (Go vs C anyone?)&lt;/p&gt;
&lt;p&gt;So I think there&amp;#x27;s a huge gap in the market here for a database system that provides decent features, decent type safety via code generation, decent command line interface and a decent API. It doesn&amp;#x27;t need recursive common table expressions and windowing functions because the people who need those features will likely stick with existing databases anyway.&lt;/p&gt;
&lt;p&gt;If this article makes you feel things, &lt;a href=&quot;https://twitter.com/Southclaws&quot;&gt;@ me on Twitter&lt;/a&gt;!&lt;/p&gt;</description>
</item>
</channel>
</rss>