Bye-bye Weeds! Digital Gardening with Astro, SolidJS and MDX.

A presentation at JSDayIE in September 2023 in Dublin, Ireland by Kathleen McMahon

Slide 1

Bye-bye Weeds! Digital gardening with Astro, SolidJS, & MDX — Kathleen McMahon Senior Design Systems Engineer — JSDay IE

● Welcome everyone! I’m Kathleen McMahon and I’m here today to talk about a Bye-bye Weeds! Digital Gardening with Astro, SolidJS and MDX.

● Before we begin, let’s get some details out of the way.

Slide 2

JSDay IE — Thank you organizers

First, I want to give a huge thank you to Irene and Remo, the speakers, the event production crew, the volunteers, and everyone that worked so hard to create an excellent event!

Slide 3

https://noti.st/resource11

My presentation will be posted on Notist, that’s https://noti.st/resource11, after my talk. I’ll also post the full URL on Twitter sometime after my presentation

Slide 4

@resource11 Twitter | Instagram | GitHub

● You can follow me at. Resource11 on Twitter, GitHub, and Instagram.

● Let’s back up so I can introduce myself a bit better…

Slide 5

Kathleen McMahon | Engineer • Designer • Speaker

So I’m an engineer and a designer and I like to speak about things…

Slide 6

Cyclocross! [image] various pictures of me racing cyclocross

I’m an occasional cyclocross racer,

Slide 7

image: Me on a cyclocross bike, in Spam, Ninja Turtle, Nerds candy box, Medusa costumes

In costume of course.

Slide 8

image: a wide-screen view of the colorful lamps and lighting strips adorning my home office desk and bookcases

Lover of lights

Slide 9

image: A wide-planked boardwalk — with soft sand and sea grass surrounding its weathered wooden railing — leads toward the calm ocean during a cloudy afternoon low tide

Beach goer.

Slide 10

image: A montage of sand dollars of various sizes and colors, next to a tiny and medium sand dollar in the palm of my hand.

Sand dollar collector

Slide 11

image: Thor, resting on the windowsill of my kitchen window, enjoying the warm summer breeze and sunshine on his soft beige fur and dreamy blue eyes.

Lover of my cats Thor

Slide 12

image: Otis — my silky black haus panther — nestled between my purple bed pillows, gazing at me with calm golden eyes.

…and Otis.

Slide 13

image: A gathering of green aventurine, sodalite, rose quarts towers, and quarts diamond on the kitchen table

I’m a crystal collector

Slide 14

image: Otis, the black wonder cat, steps into the frame of my crystal collection

And I photograph them, but Otis…

Slide 15

image: Otis' paws walk through my crystal arrangement on the kitchen table

…interferes often

Slide 16

image: grouping of citrine, amethyst, and celestite glowing in the sun-washed windowsill

…with opinions…

Slide 17

image: Otis — sassy black cat — sits exactly on top of all my windowsill crystals, seeking attention.

…about my attention. Thanks, Otis

Slide 18

image: In pure art director fashion, Thor sits distinctly on one windowsill sand dollar. Ready to provide his ultimate design judgement.

Thor does the same…

Slide 19

image: Thor looks up from the windowsill to the camera with a very satisfied look. His blue eyes gaze hypnotically my way as his pink nose points upward, whiskers pridefully twitching.

He’s very satisfied with himself.

Slide 20

image: Otis looking very cute as he lays upside down on my bed, gazing at me.

Who could resist them?

Slide 21

Northwestern Mutual

I am also a senior Design Systems engineer at Northwestern Mutual.

Slide 22

Design Systems are ALWAYS the hotness [image]: Person in inflatable dinosaur costume flips into a raft floating on a pond and claps with glee.

And I love Design Systems! it’s exciting work! Especially if you like…

Slide 23

image: Woman attempting to arrange 10 squirming kittens in a straight line, with varied success

…herding kittens. Always fun, with many moving parts. Part of Design System work includes trying out different software stacks and choosing the best tool for your system, like Gatsby.

Slide 24

Image: Gatsby and MDX logo

Speaking of Gatsby and MDX, they’re what chose to build my Digital Garden site…

Slide 25

Image: KathleenMcMahon.dev homepage

kathleenmcmahon.dev back in 2020…

Slide 26

A digital what?

So… what is a digital garden?

Slide 27

What is a digital garden? [image]: Small potted plant next to a rake with caption, My blog is a digital garden, not a blog

This blog post by Joel Hooks, and this phrase makes sense to me: “What makes a garden is interesting. It’s personal. Things are organized and orderly, but with a touch of chaos around the edges.”

Slide 28

Image: Gatsby and MDX logo

● I latched on to the idea of creating a digital garden and using Gatsby and MDX as my stack for a few reasons…

● One because I tend to love trying…

Slide 29

image: ALL THE THINGS Hyperbole and a Half

All the things! All the latest software, but at the same time…

Slide 30

Perfection is the enemy of done

I struggle with making progress over seeking perfection, and if I’m not careful, lean towards making…

Slide 31

image: A Lexus with a big red bow juxtaposed next to a tiny floofy beige kitten with a red bow

● “Big Lexus bows” vs. “Tiny kitten bows”. Wow can I hyper-focus on the details, make that perfectly crafted piece of software before shipping. That’s heck on velocity, though.

● The digital garden format keeps me in the kitten bow mindset. This way, progress happens, and blog posts get written. New things get shipped.

Slide 32

There be weeds [image]: Two fluffy dandelion weeds in a green field

● Fast forward a few years and… a few talk listing and package updates later… I noticed that my Digital Garden got… weedy. And Gatsby had versioned up to 5.3, while my site was on 2.3

● I considering an upgrade and asked an industry colleague familiar with Gatsby how painful this upgrade would be. Of course I already knew the answer. 3 major versions. Ouch. But! After asking, and hearing the expected — yes it’ll be a pain — the advice leaned towards the obvious.

● “If it’s using JavaScript, it requires regular maintenance” (OK…) which turned into a suggestion to use Squarespace, since it didn’t require maintenance.

[image]: UnSplash — masaaki-komori—0M1TKzvr3Y-unsplash

Slide 33

JavaScript is hard

And that kinda sounded like JavaScript’s hard… and maybe you’re out of your league…

Slide 34

JavaScript is hard …maybe you should build a Squarespace site?

“…maybe you should create a Squarespace site?”

Slide 35

image: Judy Hopps from Zootopia, shakes her head in disgust

Did you just say something was hard? Hello… spite driven development. By golly I would upgrade this app three versions up. Squarespace my butt.

Slide 36

10 hours later…

Slide 37

image: Judy Hopps from Zootopia, shakes her head in disgust

Still shaking my head about that Squarespace suggestion.

Slide 38

image: Shrimp and lime jello mold, plated with apple slices

● Ten hours later, I come up for air and after fixing all the new GraphQL changes and wrestling with the Gatsby image API, I’m questioning life choices.

● Just like combining jello with shellfish. Not a great decision.

Slide 39

"if you want a static site, why are you using a whole JavaScript framework to render it?"

I thought “I have a four-page static site. why am I using a JavaScript framework to render four static pages in a blog, and…

Slide 40

Why use JSX to create HTML when you could just… use HTML?

● why am I using JSX to create HTML when I could write HTML?”

● Granted, I work on Design Systems. I love creating component APIs, so I’m the last person to say just throw it all out, but there are times where you need a four-page site without throwing all this JavaScript at it just to render something that’s small, lean, performant, and just doesn’t need to be a SPA, it needs to be a multi-page app.

Slide 41

I don't need a suite of combine machines. [image]: Large agricultural harvesting machines in a vast golden field

And the Gatsby of 2020 isn’t the same as it is today. That hot static site generator everyone wanted to use has evolved into this suite of industrial farming equipment.

[image] UnSplash — darla-hueske-SD18qQeXEg8

Slide 42

A hoe and rake will do. [image] Small rake, pronged fork and clippers in a modest garden

I don’t need a combine machine when a hoe and rake will do for my needs.

[image] UnSplash — diana-light-342WASC0aSQ

Slide 43

Weed out the Complexity [image]: Gloved hand digging weeds out of a garden

● It was time to weed out the complexity, and choose a new framework

● One that will compile right down to HTML CSS and only serve the minimal amount of JavaScript if I need it.

[image] UnSplash — ales-krivec-6UtxyuTdpQU

Slide 44

image: Astro.build homepage

So I looked around — and because there’s a bunch out there and… oh hai Astro… let’s take a look at you.

Slide 45

Why Astro?

● Why did I choose Astro?

● SolidJS Support

● I can try out different UI frameworks in Astro without going all in

● I can bring in components from my other app and convert them one at a time without have to completely convert every component over at a time (some here are React, some are Solid, I’m using pragmas)

● Content focused - fetch from a CMS or work locally with type-safe Markdown or MDX (which is the reason I want it)

● Content collections

● Type safety

Slide 46

Why Astro? [image] Astro documentation page

● Why did I choose Astro?

● Astro was designed for building content-rich websites. And I zeroed in on blogs, portfolios… I don’t need a logged-in dashboard, or complex native app interactions that NextJS would give me, so this seems like a safe bet.

Slide 47

MDX support

MDX support. I can add my MDX pages and move on.

Slide 48

PostCSS support

It supports PostCSS by default, so my current CSS setup will port over without much fuss.

Slide 49

Astro Islands

Astro Islands. These are interactive UI components on the page that render in isolation using partial/selective hydration

Slide 50

Convert some components or all components

So I can import my React components from my Gatsby project. I can choose to convert them to Astro components over time, or leave them as React components.

Slide 51

I can try out different UI frameworks in Astro

● I can try out different frameworks, like SolidJS, Vue without having to fully commit to a framework.

● And share state between them.

Slide 52

MPA Architecture

That’s pretty cool. Astro also uses MPA and server-side rendering vs a client-side Single-page app, so it’s performant.

Slide 53

Leaner configs

And the configs are much leaner. Check this out.

Slide 54

image: side-by-side comparison — gatsby-config.js 😀 astro.config.mjs 😀

Here the Gatsby’s config on the left versus Astros config on the right

Slide 55

image: side-by-side comparison — gatsby-config.js 😶 astro.config.mjs 😀

So you know Gatsby has all these PostCSS configs site metadata and everything else

Slide 56

image: side-by-side comparison — gatsby-config.js 🤔 astro.config.mjs 😀

In the Astro config we have the site deploy url, markdown, integegrations, image and build and image configs. All in a small list….

Slide 57

image: side-by-side comparison — gatsby-config.js 😐 astro.config.mjs 😀

I mean literally that’s the config and the Gatsby config keeps going…

Slide 58

image: side-by-side comparison — gatsby-config.js 😬 astro.config.mjs 😀

…and going…

Slide 59

image: side-by-side comparison — gatsby-config.js 😳 astro.config.mjs 😀

And. Going.

Slide 60

image: side-by-side comparison — gatsby-node.js 🫣 astro.config.mjs 😀

Here’s the Gatsby.node file for creating nodes because I didn’t want to have my blog posts under the source folder, so I could be really fancy and smart.

Slide 61

image: side-by-side comparison — gatsby-node.js 🙄 astro.config.mjs 😀

● Look and me go… and add unnecessary complexity!

● I had to create all these nodes and do GraphQL queries to make the absolute paths to create the posts. YAY

Slide 62

image: side-by-side comparison — gatsby-browser.js 🙃 astro.config.mjs 😀

…and a Gatsby browser file with this WrapRoot element so I could wrap styled components and pass them into MDX all at once for usage

Slide 63

Till the soil [image] Person digging with a spade into the soil

Once I ported my components over to an Astro project there were some differences

[image] UnSplash — jonathan-kemper-f6RoUmj4iiM

Slide 64

From React children to Astro slots

Slide 65

image: side-by-side comparison — layout.js Layout.astro

● Here the Gatsby’s layout page on the left versus Astros layout page on the right

● In the layout.js file, we’re importing React components and a CSS modules file

● In the Layout.astro file, the components are now astro components, and we’re using a CSS file and the Astro pageTitle prop.

Slide 66

image: side-by-side comparison — layout.js Layout.astro

And in the Gatsby layout we use the children prop, where in the Astro layout we now use slot

Slide 67

Add mulch [image]: Hands holding soil

Now that the layout is set, time to mulch some content.

[image] UnSplash —gabriel-jimenez-jin4W1HqgL

Slide 68

From GraphQL to Content Collections

● First, ditch those GraphQL queries, and add in Astro’s Content Collections

● Content collections are the best way to manage and author content in any Astro project. Collections help to organize your documents, validate your frontmatter, and provide automatic TypeScript type-safety for all of your content.

Slide 69

image: Astro config.ts

● Content Collections Added in: astro@2.0.0

● Organize your documents, validate your frontmatter, and provide automatic TypeScript type-safety for all of your content.

Slide 70

Dynamically generating routes

Slide 71

image: […slug].astro file

● By creating this […slug].astro file and use the getCollection function from astro:content and getStaticPaths functions to parse your data and pop it in your pages/posts folder.

● No more finagling post files. no more create pages nonsense

Slide 72

Type-safe Markdown & MDX!

The other great thing about content collections is Type safety in your MDX with Zod

Slide 73

Zod say what?

So what is Zod anyway?

Slide 74

Plant new starters [image] hand planting starters in soil

Now that your content is defined and validated, time to plant new starters. We need to pull in some Images.

Slide 75

Images

Let’s use the new Images API

Slide 76

image:assets

New Image assets was released as stable in Astro 3.0 replaces the original @astrojs/image integration

Slide 77

image: <Image /> example file

This API the allows you to import any any image from the src/assets folder, and if when you pop it in the source and add the required alt attribute… yay a11y!…