DEV Community: chantastic

A Universal Terminal alias for bun, pnpm, npm, and yarn.

chantastic — Wed, 27 Sep 2023 16:59:11 +0000

I've typed npm for the last time.

As JavaScript developers, we have four package managers to choose from. And between personal, work, and open source projects, I use every last one of them. This is a problem because typing the wrong command costs time and irritation.

Below is zsh function that I've used to eliminate package manager context switching heartache — typing npm start when we meant bun start or npm when I mean ::shudders:: yarn.

p() {
  if [[ -f bun.lockb ]]; then
    command bun "$@"
  elif [[ -f pnpm-lock.yaml ]]; then
    command pnpm "$@"
  elif [[ -f yarn.lock ]]; then
    command yarn "$@"
  elif [[ -f package-lock.json ]]; then
    command npm "$@"
  else
    command pnpm "$@"
  fi
}

What this command does

zsh functions can be used like fancy aliases with the addition of a runtime check. This function checks for the existence of a lock file and runs the stated command with the correct package manager.

What this command does not do

This function does not create a universal interface around the varied package managers. I don't find universal interfaces helpful.

And I enjoy utilizing the subtleties in each package manager. My problem is the muscle memory around common commands (start, install, and test) and those actions inadvertently spawn confusion.

Learn more

Check out these references if you want to learn more about zsh functions.

Intro to zsh functions
How to define and load your own shell function in zsh

Storybook Actions in Action

chantastic — Fri, 25 Aug 2023 00:53:59 +0000

Let's talk about console.log-driven development. We all do it. So, instead of fighting it, let's upgrade it with Storybook Actions.

Feature instability and mitigations

Storybook actions are a feature of Storybook 6 and 7.

There's an active design proposal to make them work like conventional testing mocks. This would be a welcome change, imo.

Knowing that a change is on the horizon, let's focus on the features of the current API that will remain (or migrate easily with codemods).

Feature Overview

In a fresh Storybook 7 installation (sandboxes here), we find two example components configured to use Storybook actions.

The included Button stories log the common event — onClick — when clicked. Logs can then be expanded to show full event details.

Heading stories also log events but this time with custom events onLogin and onCreateAccount. These events are logged when the respective buttons are clicked.

Actions pair perfectly with Storybook interactions. Interactions are a way to document component states thru simulated user input. Interactions trigger their corresponding actions.

Add actions with argTypes

Let's define actions for the example Button component.

Open the story file and locate component meta.
Add an argTypes property if one doesn't exist.
Add an onClick property (this needs to match the component prop name).
Set the value to { action: "clicked" }. (The logged text can be anything we like.)

// Button.stories.tsx
// (surronding code omitted)
const meta = {
  title: "Example/Button",
  component: Button,
  tags: ["autodocs"],
  argTypes: {
    backgroundColor: { control: "color" },
    onClick: { action: "onClick" },
  },
} satisfies Meta<typeof Button>;

Now click your button in Storybook and watch the Actions log!

Test actions with interactions

Let's add an interaction to the example Button component.

Create or find a new story.
Add a play function to the story object.
Within the canvasElement, find the button.
then simulate a click event.

// Button.stories.tsx
// (surronding code omitted)
export const Primary: Story = {
  args: {
    primary: true,
    label: "Button",
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = await canvas.getByRole("button", {
      name: /Button/i,
    });
    await userEvent.click(button);
  },
};

Now the story will run the interaction when it loads. Logging both the interaction and the action — in their respective tabs.

Lessons learned

console.log-driven development is something I do when driving out a component implementation. It's a quick, cheap way to ensure that events are hooked up (early in the process).

But log statements has one huge drawback: they live in component code. And I'm guilty of pushing a log (or a few dozen) into production.

Storybook actions let you validate implementation in story files, leaving component code alone.

Polymorphic as prop in Astro

chantastic — Wed, 23 Aug 2023 00:00:00 +0000

Astro has dynamic tags — a way to take an element or component as a prop.

I had trouble finding the feature because the React community calls this pattern the "polymorphic as prop". Because we enjoy our pseudo-computer-science bullshit artisinally.

Dynamic tags are simple to implement in Astro.

No-fuss implementation

Take a capitalized Element prop as a local variable.
Render that prop as a template tag.
Take and spread rest-props.
Render children using Astro's un-named <slot />.

---
const { Element, ...props } = Astro.props;
---

<Element {...props}><slot /></Element>

Destructure and rename the element prop (for convenience or convention)

Uppercase prop names can look out of place in templates. Destructure and rename the Element prop in one to provide a more ergonomic/conventional authoring experience.

---
const { as: Element, ...props } = Astro.props;
---

<Element {...props}><slot /></Element>

Astro templates require that dynamic tags be capitalized. Renaming the element prop is a convent way to follow that requirement while providing a more conventional API to consumers.

Accept and de-duplicate classes with `class:list`

Astro has a class:list directive for orchestrating dynamic classes. Provide the class:list directive an array with both provided and component classes.

class:list is smart and automatically removes duplicate classes.

---
const {
  as: Element = "div",
  class: providedProps,
  ...props
} = Astro.props;
const componentClasses = "prose prose-slate dark:prose-invert";
---

<Element {...props} class:list={[componentClasses, providedProps]}>
  <slot />
</Element>

Note: class needs to be renamed when destructured because values can not be assigned to reserved words.

Complete with TypeScript interface

This is my completed component, with the TypeScript interface.

Yours needs will likely vary.

---
interface Props {
  as?: "body" | "main" | "article";
  class?: "string";
}

const {
  as: Element = "div",
  class: providedProps,
  ...props
} = Astro.props;
---

<Element {...props} class:list={[componentClasses, providedProps]}>
  <slot />
</Element>

BEWARE: dynamic tags don't honor hydration client directives

Astro provides client directives for hydrating client-side UI. Those don't work with dynamic tags.

If you're using dynamic tags for static layouts — like me — this isn't an issue.

Takeaways

Astro supports the "polymorphic as prop" pattern popular in React. And the additional standard tooling of TypeScript and class:list directive make it even easier to consistently implement.

Doc blocks for design system documentation

chantastic — Thu, 10 Aug 2023 04:09:59 +0000

If you document design systems, I'm about to save you a ton of time.
Because Storybook comes with lesser-known components for organizing colors, typography, and icons.

ColorPalette

Display color systems with the ColorPalette component.

Import "@storybook/blocks".
Then render a ColorPalette with a single ColorItem inside.

// system/colors.mdx
import { ColorPalette, ColorItem } from "@storybook/blocks"

<ColorPalette>
  <ColorItem />
</ColorPalette>

Create an object with a key and color value.
And pass it to the ColorItem component via the color prop.

Both key and value are displayed in the UI.

<ColorItem colors={{ Apple: "#66bf3c" }} />

Describe ColorItems with title and subtitle props.

<ColorItem
+  title="Apple"
+  subtitle="A delicious brand color."
  colors={{ Apple: "#66bf3c" }}
/>

Add as many colors to the colors prop as needed.

<ColorItem
  title="Apple"
  subtitle="A delicious brand color."
  colors={{
    Apple: "#66bf3c",
+    AppleDark: "#46991f",
+    AppleLight: "#83da5a"
  }}
/>

Use any CSS-supported color value.

ColorItem adds gray cross-hatches to indicate translucency — where color functions with non-1 alpha values are used.

<ColorItem
  title="Apple"
  subtitle="A delicious brand color."
  colors={{
+    Apple: "rgba(102,191,60,1)",
+    Apple60: "rgba(102,191,60,.6)",
+    Apple30: "rgba(102,191,60,.3)",
  }}
/>

See full ColorPalette API reference.

Typeset

Display typography systems with the Typeset component.

Import the Typeset component from @storybook/blocks.

// system/typography.mdx
import { Typeset } from "@storybook/blocks";

<Typeset {/* required props */} />

Typeset requires four props to render: fontSizes, fontWeight, sampleText, and fontFamily.

fontSizes and fontWeight support any supported CSS value (and numbers).

<Typeset
+  fontSizes={["2.875em", "2em", "1.375em", "1em"]}
+  fontWeight="900"
+  sampleText="Lorem ipsum dolor sit amet, consectetur adipiscing elit."
+  fontFamily='"Nunito Sans", "Helvetica Neue", Helvetica, Arial, sans-serif'
/>

Create a new Typeset block for every discrete typographical subset.

## Code

<Typeset
  fontSizes={[16]}
  fontWeight={400}
  sampleText="let var = 'const';"
  fontFamily='ui-monospace,
             Menlo, Monaco,
             "Cascadia Mono", "Segoe UI Mono",
             "Roboto Mono",
             "Oxygen Mono",
             "Ubuntu Monospace",
             "Source Code Pro",
             "Fira Mono",
             "Droid Sans Mono",
             "Courier New", monospace;'
/>

See full Typeset API reference.

IconGallery

Display icons with the IconGallery component.

Import "@storybook/blocks".
Then render a IconGallery with a single IconItem inside it.

// system/icons.mdx
import { IconGallery, IconItem } from "@storybook/blocks"

<IconGallery>
  <IconItem></IconItem>
</IconGallery>

Place an icon inside IconItem.
Then display that icon's name with the name prop.

+ import * as Icons from "@storybook/icons";

<IconGallery>
  <IconItem name="Accessibility">
+    <Icons.Accessibility />
  </IconItem>
</IconGallery>

Take this further — in React — by dynamically generating all available icons.

## Storybook icons

<IconGallery>
  {Object.entries(Icons)
    .filter(([name]) => name !== "iconList")
    .map(([name, Icon]) => (
      <IconItem name={name}>
        <Icon />
      </IconItem>
    ))}
</IconGallery>

See full IconGallery API reference.

Learn more…

Find in-depth references for each component on the Storybook docs page and Chromatic YouTube channel.

Add Lucide Icons to Astro

chantastic — Tue, 01 Aug 2023 16:57:01 +0000

There's no first-class Lucide integration for Astro. But making a custom one isn't too hard.

This is the component I made to do the job:

---
const { icon, ...props } = Astro.props;

const [, attributes, children] = icon;

const componentChildren = children
  ?.map(
    ([shape, attributes]) =>
      `<${shape} ${Object.entries(attributes)
        .map(([k, v]) => `${k}="${v}"`)
        .join(" ")} />`
  )
  .join("");

const componentAttributes = {...attributes, ...props}
---

<svg
  {...componentAttributes}
  set:html={componentChildren}
/>

If this component looks reasonable to you,
copy it and go forth.

If you'd like to learn how it works, let's get it!

Our goal

For this build, our goal is to render icons directly into an Astro site — converting Lucide's JSON files to inline <svg>s at build time.

This is just one of many ways to add Lucide icons to a site — the one that fits my needs best.

Initial setup

Add the lucide package.

pnpm install lucide

In the standard lucide package, icons are exported as JSON arrays with the following contents:

[0]: "svg"
[1]: element attributes
[2]: children

[
  "svg",
  {
    xmlns: "http://www.w3.org/2000/svg",
    width: 24,
    height: 24,
    viewBox: "0 0 24 24",
    fill: "none",
    stroke: "currentColor",
    "stroke-width": 2,
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  [
    ["circle", [Object]],
    ["path", [Object]],
    ["path", [Object]],
    ["path", [Object]],
    ["path", [Object]],
  ],
];

We need to import these JSON files and render their data as HTML.

Render a single icon

To render a single Lucide icon:

Import any lucide icon
Destructure attributes and children array items from that icon
Reduce children nodes to HTML string
Render an <svg> component
- Spread attributes directly on the element
- Apply childElements with the set:html directive

// 1. Import any `lucide` icon
import { Accessibility } from "lucide";

// 2. Destructure the `attributes` and `children` array items
const [, attributes, children] = Accessibility;

// 3. Reduce children nodes to HTML string
const componentChildren = children
  ?.map(
    ([child, attributes]) =>
      `<${child} ${Object.entries(attributes)
        .map(([k, v]) => `${k}="${v}"`)
        .join(" ")} />`
  )
  .join("\n");
---

<!-- 4. render svg element -->
<svg
  {/* 4.1. Spread `attributes` directly on the element */}
  {...attributes}
  {/* 4.2. Apply `childElements` with the `set:html` directive */}
  set:html={childrenElements}
/>

Extract `LucideIcon` component

Now that we can render icons, let's extract this code as a reusable component.

Move the relevant code to src/components/lucide-icon.astro
Refactor to icon as a prop
Take rest ...props so HTML and SVG attributes can be applied at the call site
Merge icon attributes and component props
Apply munged attributes-props to exported svg element

---
// 1. Take `icon` as a prop
// 2. Take rest `props`
- import { Accessibility } from "lucide";
+ const { icon, ...props } = Astro.props;

const componentChildren = children
  ?.map(
    ([child, attributes]) =>
      `<${child} ${Object.entries(attributes)
        .map(([k, v]) => `${k}="${v}"`)
        .join(" ")} />`
  )
  .join("\n");

// 3. Merge `attributes` and `props`
+ const componentAttributes = {...attributes, ...props}
---

<svg
  {/* 4. Apply munged `componentAttributes` to svg */}
-  {...attributes}
+  {...componentAttributes}
  set:html={childrenElements}
/>

Use the `LucideIcon` component

To use our new LucideIcon component, import it along with any lucide icon.
Provide the icon JSON to LucideIcon using the icon prop.

---
import LucideIcon from "@components/lucide-icon.astro";
import { Accessibility } from "lucide";
---

<LucideIcon icon={Accessibility} />

Apply attributes to `LucideIcon`

The LucideIcon receives props that it merges with the default lucide values.
Use these to change SVG attributes like height, width, fill, and stroke-width.
Or apply common attributes like class and id.

---
import LucideIcon from "@components/lucide-icon.astro";
import { Accessibility } from "lucide";
---

<LucideIcon icon={Accessibility} width="56" height="56" stroke-width="4" />

Taking it further

My preference is to keep icon importing and SVG rendering separated.
But you may find this cumbersome.

If so, create a facade for LucideIcon that exposes your favorite icons via string interface.

This could look something like this:

---
import {
  Github as github,
  Youtube as youtube,
  Twitter as twitter,
  Instagram as instagram
} from "lucide";

const icons = {
  github,
  youtube,
  twitter,
  instagram
}

const { name = "github", ...props } = Astro.props;

if !(icons[name]) { return null }

const [, attributes, children] = icons[name];

const componentChildren = children
  ?.map(
    ([child, attributes]) =>
      `<${child} ${Object.entries(attributes)
        .map(([k, v]) => `${k}="${v}"`)
        .join(" ")} />`
  )
  .join("\n");

const componentAttributes = {...attributes, ...props}
---

<svg
  {...componentAttributes}
  set:html={childrenElements}
/>

Go further with TypeScript

lucide does not expose its IconNode type for external use.

So, if you want to use my code above in TypeScript, you'll need to get clever:

Import just the type of any component.
Infer the IconNode for that icon in the LucideIcon type declaration.
Add any optional svg attributes you'd like to support. (e.g., height, width, fill, stroke-width, etc.)

---
// 1. Import just the type of any component.
import type { Accessibility } from "lucide";

type Props = {
  // 2. Infer the `IconNode` for that icon in the `LucideIcon` type declaration
  icon: typeof Accessibility;
};
---

That's it!

I hope that you found this useful in building an Astro site.
If you'd like to see more Astro tips and tricks, bug me on Twitter/X or Discord. 😄

Fix VS Code Explorer for Content Projects

chantastic — Tue, 25 Jul 2023 16:48:23 +0000

The VS Code explorer displays folders at the top of a directory.
This is a common hierarchy that I like in most cases.

But I hate it for content.

For content sites — like chan.dev — I prefer alphabetical order.
I want to see my files and folders all mixed up together.

How to change the setting

To change the default behavior, open Settings and find the option for Explorer: Sort Order.

With this option enabled, files and folders are interwoven in the explorer.

Why I prefer mixed sort order

On chan.dev, I have lots of markdown files.
Some of them have images.
And I want to keep those images in a folder nearby.
I ain't tryna faff with Cloudinary or hunt down shared /assets/images folder.
I want them right next to my post.

This makes it easy to keep my place on the file system.

Take it further with workspaces

As mentioned, I prefer the default sort order for most projects.
So, I keep this setting stored in my chan.dev workspace.
And only this project is impacted by the setting.

// chan.dev/.vscode/settings.json
{
  "explorer.sortOrder": "mixed"
}

Embed YouTube videos responsively

chantastic — Thu, 13 Jul 2023 19:10:17 +0000

YouTube makes it easy to copy-paste a video embed.
LOVE THAT!

But, the default embed isn't responsive so it is guaranteed to look shit wherever you embed it.

I've drug this snippet around the internet with me for years.

/* youtube embed wrapper */
[data-responsive-youtube-container] {
  position: relative;
  width: 100%;
  height: 0;
  padding-bottom: 56.25%;
  margin: 1em 0;
}

[data-responsive-youtube-container] > iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

I adapted it to use AVO 🥑 CSS, my data attributes specification of BEM.
But I didn't write the styles.
I hate magic numbers like 56.25%, and I would have tried to avoid it until giving up 😆

Usage

Copy a YouTube embed from the share sheet.
Paste that embed in an HTML or markdown file.
Wrap it in a block-element container with the data-responsive-youtube-container selector.
Enjoy cointainer-aware responsive videos!

<div data-responsive-youtube-container>
  <iframe
    width="560"
    height="315"
    src="https://www.youtube.com/embed/u63pOK6Zyog"
    title="YouTube video player"
    frameborder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowfullscreen
  ></iframe>
</div>

Embed responsively!

Bonus

This works with layouts as well.
Around chan.dev, you'll see this paired with a flex and grid layout.

Help me attribute this

If you know where I originally swiped this from, let me know so I can give the author credit here.

I'm @chantastic on twitter and discord.

Concurrent Mode is Dead. Long live Concurrent React

chantastic — Wed, 09 Jun 2021 00:00:00 +0000

Three years ago Dan Abramov introduced Suspense and Async Rendering with React at JSConf Iceland 2018.

In the three years since, terminology took some twists and turns.

"Suspense" was limited to React.lazy in versions 16 and 17.

"Async React" became "Concurrent Mode" — a top-down rendering mode that could be enabled for Strict Mode-compatible applications.

React 18 has new-new language. And I'd like to start my tour of React 18 changes by rebasing on new terminology used in the ReactWG (React Working Group).

Concurrent Mode => Concurrent everything

"Concurrent Mode" is no more. Bye 👋. We barely knew ya!

Instead of a concurrent mode, concurrency is possible in all React 18 apps.

React 18 adds a set of new features, sometimes called "concurrent features" or "concurrent APIs". These features rely on a new mechanism called "concurrent rendering" that weren't possible before it.

It's a subtle but important change.
Concurrency is no longer something that you opt into at the root of your application. It's an enrichment that happens as you use "Concurrent features and APIs" like startTransition.

Concurrent rendering is not a mode.
Concurrent rendering is React.

New-new, React 18 terminology

Here's the state of React 18 terminology shifts I've seen in ReactWG discussions:

Fired:

❌ Concurrent Mode

Hired:

✅ Concurrent React
✅ Concurrent rendering
✅ Concurrent features and APIs

Takeaway

In React 18, Concurrent React is React. Concurrent features and APIs — like startTransition — expose controls for opting into concurrent rendering.

Acknowladgements

This post was reviewed and improved by the fantastic folks in the reactwg. Lessons learned while writing this post are available via the reactwg GitHub discussions.

Comprehending YAML

chantastic — Thu, 11 Feb 2021 00:00:00 +0000

YAML is a little clever for my taste but I'm starting to get it.

Before yesterday's post, I had no idea how it related to JSON. In that post I personalized a few examples from the YAML docs and manually converted them.

And after sleeping on my exercise, I have a better picture of what's going on.

YAML infers complex types
YAML infers simple types
YAML shorthand can be confusing
YAML patterns
- Arrays of arrays
- Arrays of objects
- Objects of arrays
- Objects of objects
All mixed up

YAML infers complex types

As much as possible, YAML infers complex data structures by the data it composes.

- Evermore
- Folklore
- Lover

This is a sequence and the containing Array structure is implied.
Here's how it looks in JSON:

["Evermore", "Folklore", "Love"]

Compare this to a YAML mapping, where the root structure is implied to be an object.

Evermore: 2020
Folklore: 2020
Lover: 2019

Again, here's what that looks like in JSON.

{
  "Evermore": 2020,
  "Folklore": 2020,
  "Lover": 2019
}

So what happens if we try to mix sequences and mappings at the root level?

-Evermore
Folklore: 2020
Lover: 2019

It breaks:

YAMLException: end of the stream or a document separator is expected at line 2, column 9: Folklore: 2020

This tracks because something can't be both an object AND an array.

Understanding inference

Indentifying when you're describing an Array (sequence) and when you're describing an Object (mapping) is critically important. And it's not always clear.

Can you guess what the JSON equivalent for this YAML is?

- Evermore: 2020
- Folklore: 2020
- Lover: 2019

The dashes - indicate that the root structure is an array (sequence). But each array item comprises a descrete object (mapping) with a key-value pair. This is inferred from the colon : between values in each array item.

So the JSON output for the YAML above is this:

[
  {
    "Evermore": 2020
  },
  {
    "Folklore": 2020
  },
  {
    "Lover": 2019
  }
]

An array of objects (or "sequence of mappings").

Now that I understand it, I see the dash (-) like list-items in Markdown.

YAML infers simple types

Let's take an array (sequence) of objects (mappings).

- Evermore: 2020
- Folklore: 2020
- Lover: 2019

The keys are strings and the values are numbers.

Evermore becomes "Evermore".

2020 stays 2020.

Taylor Swift becomes "Taylor Swift".

Takeaways

After looking at so much JavaScript and JSON, this is a little unsettling but — in simple examples like this — there's a simplicity to the representation.

YAML shorthand can be confusing

Below we have an array (sequence) of objects (mappings).

- name: Taylor Swift
- name: The National

JSON looks like this.

[
  {
    "name": "Taylor Swift"
  },
  {
    "name": "The National"
  }
]

What does it look like to add more properties to the these objects?

YAML allows us to use JSON object syntax.

- { name: Taylor Swift, album_count: 9 }
- { name: The National, album_count: 8 }

But it's not super YAML-y. So there's an alternative that uses newlines.

- name: Taylor Swift
  album_count: 9
- name: The National
  album_count: 8

This is challenging for me to interpret. Because the dash (-) is separating discrete objects (mappings) in the array (sequence). So it feels like the dash (-) is a directive for the object (mapping). But it's not, it's communicating that the containing structure is an array.

Pressing into the confusion, consider this array (sequence) containing a string, number, object, and array.

- Taylor Swift
- 1989
- album_count: 9
  nationality: American
- - Big Machine
  - Republic

This is that same file in JSON.

[
  "Taylor Swift",
  1989,
  {
    "album_count": 9,
    "nationality": "American"
  },
  ["Big Machine", "Republic"]
]

Takeaways

The presence of dash (-) and colon (:) describe the surrounding structure.

In the case of arrays (sequences) of objects (mappings), with multiple key-value pairs, this terseness can be unclear. At least until you've trained ourselves to see the invisble structures that (-) and (:) represent.

- name: Taylor Swift
  album_count: 9

For me, learning to interpret the above line as an object in an array has made the biggest difference in my ability to quickly parse YAML.

YAML patterns

Identifying patterns is helpful.

Here are a few complex handoffs that I had trouble with.

Array of arrays : sequence of sequences

- - Evermore
  - Folklore
  - Lover
- - I Am Easy to Find
  - Sleep Well Beast
  - Trouble Will Find Me

This YAML file is an array (sequence) containing two arrays (sequences) each with three strings (scalars).

Array of objects : sequence of mappings

- name: Taylor Swift
  album_count: 9
- name: The National
  album_count: 8

This YAML file is an array (sequence) referencing two objects (mappings) each with two key-value pairs.

Object of arrays : mapping of sequences

Taylor Swift:
  - Evermore
  - Folklore
  - Lover
The National:
  - I Am Easy to Find
  - Sleep Well Beast
  - Trouble Will Find Me

This YAML file is an object (mapping) with two key-value pairs, each key referencing an array (sequence) of strings (scalars).

Object of objects : mapping of mappings

Taylor Swift:
  album_count: 9
  label: Republic
The National:
  album_count: 8
  label: 4AD

This YAML file is an object (mapping) with two key-value pairs, each key referencing another object with two key-value pairs with mixed strings and numbers (scalars) as values.

All mixed up

Parse isolated patterns is a good start but the big game is reading entire YAML files.

Look at this GitHub Actions workflow.

name: Netlify Rebuild
on:
  schedule:
    - cron: "0 21 * * MON-FRI"
jobs:
  build:
    name: Netlify Rebuild
    runs-on: ubuntu-latest
    steps:
      - name: Curl request
        run: curl -X POST -d {} https://api.netlify.com/build_hooks/601321b7879709a8b8874175

Here's what we can evaluate.

The root structure is an object with three properties
name references a string
on references an object with one property
- schedule references an array with one object containing one property
- cron references a string
jobs referencs an object with one property
- build references an object with three properties
- name references a string
- runs-on references a string
- steps references array with an object containing two properties
  - name references a string
  - run references a string

Conclusion

I think I understand YAML enough to move on with my life. I hope you feel the same way.

Learning how to identify the implied structures has made all the difference.

A Non-Comprehensive Guide to YAML for Folks Who Like JSON Just Fine

chantastic — Wed, 10 Feb 2021 00:00:00 +0000

YAML is a human friendly data serialization standard for all programming languages.
— https://yaml.org

I don't know precisely which humans YAML is friendly to but I'm not one of them.

And it looks like the people who run in my circles are also excluded.

// Detect dark theme var iframe = document.getElementById('tweet-1359601176434544640-859'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1359601176434544640&theme=dark" }

Mapping to JSON

Between Eleventy, GitHub Actions, and a recent foray into serverless, I'm using a more YAML. And I don't understand it.

This is mapping for my JSON-acquainted brain.

Comments
Array of strings
Array of objects — one value
Array of objects — many values
Object of keyed arrays of strings
Object of keyed objects with mixed values
Array of arrays with mixed values
Nodes (variables)
Sample GitHub Action
Takeaways
Resources and further reading

Comments

YAML

# you can put these p much anywhere

JSON

JSON doesn't support comments.

Array of strings

Sequence of Scalars

YAML

- Evermore
- Folklore
- Lover

JSON

["Evermore", "Folklore", "Love"]

Array of objects — single value

Mapping Scalars to Scalars

YAML

- Evermore: 2020
- Folklore: 2020
- Lover: 2019

JSON

[
  {
    "Evermore": 2020
  },
  {
    "Folklore": 2020
  },
  {
    "Lover": 2019
  }
]

Array of objects — many values

Sequence of Mappings

YAML

- name: Taylor Swift
  album_count: 9
  label: Republic
- name: The National
  album_count: 8
  label: 4AD

JSON

[
  {
    "name": "Taylor Swift",
    "album_count": 9,
    "label": "Republic"
  },
  {
    "name": "The National",
    "album_count": 8,
    "label": "4AD"
  }
]

This syntax confused the shit out of me.

This code is auto-formatted by prettier putting the dash and the first property on the same line.

YAML docs show the dash and first property on different lines which is much more legible.

-
  name: Taylor Swift
  album_count: 9
  label: Republic
-
  name: The National
  album_count: 8
  label: 4AD

Object of keyed arrays of strings

Mapping Scalars to Sequences

YAML

Taylor Swift:
  - Evermore
  - Folklore
  - Lover
The National:
  - I Am Easy to Find
  - Sleep Well Beast
  - Trouble Will Find Me

JSON

{
  "Taylor Swift": ["Evermore", "Folklore", "Lover"],
  "The National": [
    "I Am Easy to Find",
    "Sleep Well Beast",
    "Trouble Will Find Me"
  ]
}

Object of keyed objects with mixed values

Mapping of Mappings

YAML

Taylor Swift:
  album_count: 9
  label: Republic
The National:
  album_count: 8
  label: 4AD

JSON

{
  "Taylor Swift": {
    "album_count": 9,
    "label": "Republic"
  },
  "The National": {
    "album_count": 8,
    "label": "4AD"
  }
}

Array of arrays with mixed values

Sequence of Sequences

YAML

- [name, album_count, label]
- [Taylor Swift, 9, Republic]
- [The National, 8, 4AD]

JSON

[
  ["name", "album_count", "label"],
  ["Taylor Swift", 9, "Republic"],
  ["The National", 8, "4AD"]
]

Nodes

YAML

Folklore:
  # Following node labeled TS and AD
  - &TS Taylor Swift
  - &AD Aaron Dressner
  - Jack Antonoff
Lover:
  - *TS # Subsequent occurrence
I Am Easy to Find:
  - *AD

JSON

No JSON equivalent.

But this is the output from the above YAML.

{
  "Folklore": ["Taylor Swift", "Aaron Dressner", "Jack Antonoff"],
  "Lover": ["Taylor Swift"],
  "I Am Easy to Find": ["Aaron Dressner"]
}

Sample GitHub Action

YAML

name: Netlify Rebuild
on:
  schedule:
    - cron: "0 21 * * MON-FRI"
jobs:
  build:
    name: Netlify Rebuild
    runs-on: ubuntu-latest
    steps:
      - name: Curl request
        run: curl -X POST -d {} https://api.netlify.com/build_hooks/601321b7879709a8b8874175

JSON

{
  "name": "Netlify Rebuild",
  "on": {
    "schedule": [
      {
        "cron": "0 21 * * MON-FRI"
      }
    ]
  },
  "jobs": {
    "build": {
      "name": "Netlify Rebuild",
      "runs-on": "ubuntu-latest",
      "steps": [
        {
          "name": "Curl request",
          "run": "curl -X POST -d {} https://api.netlify.com/build_hooks/601321b7879709a8b8874175"
        }
      ]
    }
  }
}

Takeaways

Complex types are inferred

The structures of complex types are hidden in YAML.

They get inferred by the structure of included data.

Keep a look out for - and : which indicate the containing structure.

Dash `-`

If you see a dash -, it means you're describing a single array item.

This means you're in an array.

Colon `:`

If you see a color : separating two values, it means your describing a key-value pair.
This means you're in an object.

In the wild

Since YAML is used often for configuration, it's likely that your root type is object.

At least that's the case for Markdown Frontmatter, GitHub Actions, and CloudFormation templates.

Resources and further reading

Official YAML 1.2 Documentation at yaml.org
YAML to JSON web converters
- https://jsonformatter.org/yaml-to-json
- https://onlineyamltools.com/convert-yaml-to-json

Import Both Default and Named Exports

chantastic — Sat, 06 Feb 2021 16:21:15 +0000

We can mix and match import styles to keep code tidy and direct.

The code below imports both the default export (as cheesburger) as well as all named exports.

import { default as cheeseburger, bun, cheese, patty,} from "./cheeseburger.mjs";

We can tidy it up a smidge by splitting the default export and named export import statements — using a comma.

- import {
- default as cheeseburger,
- bun,
- cheese,
- patty,
- } from "./cheeseburger.mjs";
+ import cheeseburger, { bun, cheese, patty } from "./cheeseburger.mjs";

This eliminates the need to rename the default on import with as.

What mixed imports are not #

The import position of default and named exports cannot be swapped. When mixing the two, it's always default first then named exports.

When I first saw this syntax, I assumed that every comma was like a repeaet — a new opportunity to assign local variables. That's not how it is. One comma, after the default, and before the named.

Go pro #

This is part of a course I'm building on modules at lunch.dev.

When live, members get access to this and other courses on React.

Join lunch.dev for videos

Import Default From Named Export

chantastic — Thu, 04 Feb 2021 07:48:02 +0000

Importing default can be nuanced. There are just so many ways to do it.

I like to think of default as a named export with a fixed (non-customizeable) name.

Check out how we can import default like a named export.

import { default as Highlander } from "./highlander.js";

The lines below yield identical results.

- import Highlander from "./highlander.js";
+ import { default as Highlander } from "./highlander.js";

Unlike named exports, you can't import default and use it directly. It must be remaned at import. This is why the more ergonomic option of import MyAlias from "…"; exists.

Use default thru a module alias #

We've discussed module aliases in past posts. And they have some overlap with the default export.

Check out this totally valid use of Module aliases and default.

import * as Highlander from "./highlander.js";

Highlander.default();

Technically, you're not using the default keyward because we're accessing the reference as a property.

Of course, this looks a little strange when used in frameworks like React.

<Highlander.default>…<Highlander.default />

My take #

I don't use default as or ModuleAlias.default() import styles in practice. I just find it helpful to remember how default is exported from modules.

In future posts, we'll cover two, more ergonomic alternatives capturing both default and named exports.

Go pro #

This is part of a course I'm creating on modules at lunch.dev.

When live, members get access to this and other courses on React.

Join lunch.dev for videos

DEV Community: chantastic

A Universal Terminal alias for bun, pnpm, npm, and yarn.

What this command does

What this command does not do

Learn more

Storybook Actions in Action

Feature instability and mitigations

Feature Overview

Add actions with argTypes

Test actions with interactions

Lessons learned

Polymorphic as prop in Astro

No-fuss implementation

Destructure and rename the element prop (for convenience or convention)

Accept and de-duplicate classes with class:list

Complete with TypeScript interface

BEWARE: dynamic tags don't honor hydration client directives

Takeaways

Doc blocks for design system documentation

ColorPalette

Typeset

IconGallery

Learn more…

Add Lucide Icons to Astro

Our goal

Initial setup

Render a single icon

Extract LucideIcon component

Use the LucideIcon component

Apply attributes to LucideIcon

Taking it further

Go further with TypeScript

That's it!

Fix VS Code Explorer for Content Projects

How to change the setting

Why I prefer mixed sort order

Take it further with workspaces

Embed YouTube videos responsively

Usage

Bonus

Help me attribute this

Concurrent Mode is Dead. Long live Concurrent React

Concurrent Mode => Concurrent everything

New-new, React 18 terminology

Takeaway

Acknowladgements

Comprehending YAML

YAML infers complex types

Understanding inference

YAML infers simple types

Takeaways

YAML shorthand can be confusing

Takeaways

YAML patterns

Array of arrays : sequence of sequences

Array of objects : sequence of mappings

Object of arrays : mapping of sequences

Object of objects : mapping of mappings

All mixed up

Conclusion

A Non-Comprehensive Guide to YAML for Folks Who Like JSON Just Fine

Mapping to JSON

Comments

Array of strings

Array of objects — single value

Array of objects — many values

Object of keyed arrays of strings

Object of keyed objects with mixed values

Array of arrays with mixed values

Nodes

Sample GitHub Action

Takeaways

Complex types are inferred

Dash -

Colon :

In the wild

Resources and further reading

Import Both Default and Named Exports

What mixed imports are not #

Go pro #

Accept and de-duplicate classes with `class:list`

Extract `LucideIcon` component

Use the `LucideIcon` component

Apply attributes to `LucideIcon`

Dash `-`

Colon `:`