DEV Community: ryanfiller

Blackletter Logo

ryanfiller — Thu, 13 Apr 2023 05:00:00 +0000

When I started my website from scratch in 2020, I always intended to create a new logo as one of the first things I would work on. However, other tasks took priority, and now more than three years later, I still only have my name typed out in a font at the top of the site serving as a makeshift logo. This has made it difficult to make big design decisions elsewhere on the site, as I was afraid I would put a lot of work into a design element, only to have it clash with whatever I eventually settled on for a logo. This time around, I made sure to do things in a different order when starting over.

To check out the finished logo, feel free to jump straight to the end.

What is Blackletter

"Blackletter," according to Wikipedia, "is a script used throughout Western Europe from approximately 1150 until the 17th century." Despite its wide usage during the European Middle Ages, the style eventually fell out of favor due to the rising popularity of less ornate and more readable styles, in addition to having a complicated relationship to one of the 20th century's worst events.

The style of this lettering is characterized by tall and narrow letters formed by straight, angular lines that often end in sharp final shapes that "bite," or overlap, other letters. Due to its prominent historical usage in the European Middle Ages it still lives on as a sort of shorthand for the "medieval period" for works set in the time period, especially the fantasy fiction genre.

Inspiration

I began the project by researching everything I personally associated with this style of font. Surprising to me, many of the things I thought of as using "blackletter" actually use a different type of lettering like antiqua, a rotunda or minuscule style, or even a more generic Roman style font. I found this interesting because I guess I wasn't aiming to reference any specific historic period precisely, rather I wanted to capture the general "vibe" these projects had.

Rough Sketch

I actually had this initial idea a while back and jumped directly into Adobe Illustrator to rough it out. According to the file created time, I started experimenting with this logo in April 2021.

I took a lot of inspiration from the Textura form because I thought its inherent geometry fit the best with my personal design style. I also really wanted to avoid the WWII connotations I mentioned above so I did my best to stay away from directly referencing the Fraktur style. The logo is made up only of straight lines, with each letter constructed using a combination of a square diamond shape and a vertical rectangle.

Refining

I lost interest in this logo for a while, but then something happened earlier last year that really got me back into the "medieval fantasy aesthetic" mindset.

After months of adventuring around The Lands Between, battling all sorts of knights, wizards, and monsters, I felt compelled to find a way to make this logo work.

Letter Stems

One of the first changes I made was to slim down all of the vertical letter stems. In the original sketch each stem had the same width as one of the diamonds rotated 45°, but for the updated version I reduced the width to only half of the width of one of the serif finals. This added some visual contrast to the logo and made it more realistic in terms of what a calligraphy pen could produce.

X-Height

From the start, I had envisioned a version of the logo that could work as a monogram with only my initials. While working on the lockup, I realized that it would work best if it fit inside a square so it could be used for various favicon images that my site would eventually need.

This ultimately ended up deciding the final height of the letters so that the ascender and descender of the "f" would line up with the imagined outline, as would the bottom bottom terminal of the "r". To fit into the square the overall x-height and body height of the letters was reduced a decent amount from the original sketch.

[[clearfix]]

With the x-height, body height, stem width, and terminal size were established, I reworked the rest of the letters for consistency with the updated "r" and "f."

Grid Layout

I had two main goals while creating each individual letter form: to use the minimum number of shapes necessary, and to strictly adhered to a 6x6 grid system created from the size of the base diamond shape.

I also decided to combine the "f" and "i" characters into an "ﬁ" ligature was both for consistency in the letter spacing of my last name and also just because I am a fan of ligatured letters in general.

When I was in design school I remember a professor telling me -

Once An Accident, Twice A Coincidence, Three Times A Pattern

I looked this quote up and expected it to have been said by a famous designer, but apparently this is actually an Ian Flemming quote from the James Bond novel Goldfinger. Regardless of who coined the phrase, I made sure to repeat the small, diagonal spacing at least three times — once between the "r" and "y", once in the "ﬁ" ligature, and once in the open counter of the "e".

With that spacing nailed down I designed the remaining letters to create as much diagonal alignment among their ascenders, descenders, and terminals as possible. Because of the previous constraints around x-height and overall letter height not every element could align perfectly.

The Finished Logo

Progress on the New Site

Follow along with my redesign at beta.ryanfiller.com (which may or may not currently match what is shown at the time of publishing this blog post.)

Building an Alert Component in Svelte

ryanfiller — Wed, 30 Jun 2021 00:00:00 +0000

If you were on the internet in the 90s then you probably remember what life was like before pop-up blockers. Even the person who invented pop-up ads regrets doing it. Using the internet today can feel the same as 30 years ago, with alerts and banners everywhere. With things like GDPR cookie warnings starting in 2018 and COVID alerts in 2020 the web looks more and more like this parody site with every passing year. What's worse is that according to this accessibe.com article the large majority of these pop-ups don't pass basic WCAG accessibility guidelines. These modals and alerts often contain agreements that need acceptance before proceeding. This means that people with different browsing needs can often be blocked from the entire site.

All that said, sometimes, there are things you still want to show a user before they proceed. I needed such an alert to warn users that there's most likely unexpectedly broken code in the "lab" section of my site.

This post will walk through how I used Svelte to build an accessible alert that also won't annoy users too badly. It also incorporates a cache-busting mechanism in case the content ever changes and users need to see it again.

The Basic Component

The <Alert /> component markup is pretty straightforward. It accepts a few props — show for defining when the alert is visible, a title to display as an internal header, and a close function.

Since this is going to be a reusable component, I'm using the Svelte <slot /> element to pass content into the main body of the component.

<!-- alert.svelte -->
<script>
  export let show
  export let close
  export let title
</script>

{#if show}
  <div>
    <section>
      <header>
        <strong>
          {title}
        </strong>
        <button on:click={close}>
          Close
        </button>
      </header>

      <div>
        <slot />
      </div>
    </section>
  </div>
{/if}

The HTML `<dialog>` Element

When trying to make accessible content, people tend to reach for adding ARIA attributes to their HTML elements. But, the first rule of thumb for ARIA is actually to try not to use ARIA.

Many of these widgets were later incorporated into HTML5, and developers should prefer using the correct semantic HTML element over using ARIA, if such an element exists.

HTML5 introduced the <dialog> element for content like this, so it will be the foundattion for my component. The <dialog> element will be understood by modern screen readers and also comes with built-in conveniences like an open attribute to toggle visibility and a ::backdrop pseudo element to handle the overlay on the content behind it.

<!-- alert.svelte -->
<script>
  export let show
  export let close
  export let title
</script>

{#if show}
  <dialog open on:click={close}>
    <section>
      <header>
        <strong>
          {title}
        </strong>
        <button on:click={close}>
          Close
        </button>
      </header>

      <div>
        <slot />
      </div>
    </section>
  </dialog>
{/if}

It might seem weird to be attaching a click event to fire the close function to the actual <dialog> element, but there's a reason for that I'll cover in a bit.

Unfortunately, Safari doesn't fully support the <dialog /> tag. For now, that means ARIA is required, although maybe as browser support improves this could one day be removed.

The good news is that rather than render nothing, Safari will still render the element but instead treat it like a normal <div>. Because it will be rendered as a non-semantic element, I can mark it with the ARIA role='dialog' so that any Safari screen reader will still treat it correctly.

<!-- alert.svelte -->
<script>
  export let show
  export let close
  export let title
</script>

{#if show}
  <dialog
    open
    on:click={close}
    role='dialog'
  >
    <section>
      <header>
        <strong>
          {title}
        </strong>
        <button on:click={close}>
          Close
        </button>
      </header>

      <div>
        <slot />
      </div>
    </section>
  </dialog>
{/if}

In order to be fully accessible, any role element needs to meet two other criteria:

The dialog must be properly labeled
Keyboard focus must be managed correctly

To address the first point, two more attributes can be added to the <dialog /> tag — aria-labelledby and aria-describedby — and pointed to their corresponding elements using a generated id. aria-labelledby should point to the primary identifier of the element, the <header />. aria-describedby needs to identify additional context, which in this case is the main <div />.

I'll get back to the second criteria later in the post.

<!-- alert.svelte -->
<script>
  export let show
  export let close
  export let title

  const id = slugify(title)
</script>

{#if show}
  <dialog
    open
    on:click={close}
    role='dialog'
    aria-labelledby={`${id}-title`}
    aria-describedby={`${id}-content`}
  >
    <section>
      <header id={`${id}-title`}>
        <strong>
          {title}
        </strong>
        <button on:click={close}>
          Close
        </button>
      </header>

      <div id={`${id}-content`}>
        <slot />
      </div>
    </section>
  </dialog>
{/if}

Stacking Context

Visually, one of the most important features of a modal or alert is that it appears on top of the rest of the site content. It might seem sufficient to just add a very high z-index, like 9999, but because of how stacking context works this sometimes still isn't enough to get an element to the forefront of the page. Josh W Comeau has a good article that explains why z-index is more complicated than just assigning the highest number.

Instead of relying on only CSS, I wanted my modal to take advantage of the fact that the HTML document will stack elements according to DOM source order. This means that the closer to the end of a document an element is, the higher it will appear by default on the z-axis.

My site is already set up in such a way that each page is created with a <Page /> Svelte component that I use to include shared page elements like the header and the footer. Adding a place for the alert to render at the end of the pages is as easy as adding a named <slot />. Because I don't want errant HTML to render on pages that don't need it, I'm also checking to see if an alert is present using the $$slots object that Svelte provides.

<!-- page.svelte -->
<SEO {...$$props} />

<div id='site'>
  <Header />

  <main>
    <slot />
  </main>

  <Footer />
</div>

{#if $$slots.alert}
  <slot name='alert' />
{/if}

The particular alert I'm building needs to go on any pages in the /lab section of my site, so I need to add the code for the actual alert to the <Lab /> component that serves as the template for those subpages. To learn more about how exactly templates on my blog work, I have another post that goes into depth, or there are the official mdsvex docs. Either way, just know that anything added to the <Lab /> component outside of the default <slot /> will appear on every page that matches the url /lab/[slug]. The <Lab /> template is also responsible for managing the showAlert and closeAlert props.

<!-- lab.svelte -->
<script>
  import Page from './page.svelte'
  import Alert from '../components/misc/alert.svelte'

  let showAlert = true

  const closeAlert = () => { 
    showAlert = false
  }
</script>

<Page {...$$props} >

  <slot />

  <Alert
    title='Caution!'
    show={showAlert}
    slot='alert'
  >
    <p>
      Some features in the section require JavaScript, 
      might not work great on mobile, 
      and may not have been thoroughly tested.
    </p>

    <button on:click={closeAlert}>
      That's okay.  
    </button>
  </Alert>

</Page>

Using the slot='alert' prop on an element inside of the <Page /> component will render it inside of the <slot name='alert' /> in the parent component and add it to the bottom of the page.

Basic CSS

Many of the styles applied to the alert will vary depending on the site, but there are a few positioning styles that I wanted to cover.

The first thing to do is to make the <dialog /> element cover the entire screen using position: fixed. position: fixed works similarly to position: absolute, but instead of using the closest position parent like absolute does, fixed will position the element relative to the browser window. By combining this position with height and width of 100% and a top, right, bottom, and left of 0, the <dialog /> box will be stretched to cover the entire viewport. Just to be safe, I gave it an incredibly high z-index as well, even though we shouldn't need it because of the document ordering from earlier.

dialog {
  position: fixed;
  top: 0;
  right: 0;
  left: 0;
  bottom: 0;
  z-index: 9999;
  height: 100%;
  width: 100%;
  display: flex;
  justify-content: center;
  align-items: center;
  background: transparent;
}

The page-height element is also set to display: flex with both align-items and justify-content set to center to keep the content in the center of the screen.

At first it might seem odd to set background: transparent; on the element, since usually these types of alerts show a dark overlay while covering the site. This, again, has to do with the <dialog /> element not being supported in Safari. Instead of using its native ::backdrop I have to fake this functionality with a normal ::after pseudo element, stretched to cover its entire parent with position: absolute. It also has a z-index: -1 to make sure that it stays behind the <section /> element that will contain the main content of the alert.

dialog::after {
  content: '';
  display: block;
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  background: black;
  opacity: .5;
  z-index: -1;
  pointer-events: none;
}

section {
  width: 100%;
  max-width: 50rem;
  background: white;
}

It is entirely possible to set a background color directly on the <dialog /> itself, but I wanted to use the opacity property to adjust the alpha value to make a transparent version of one of my site's existing colors.

One other important note here is to make sure and set pointer-events: none; on the ::after element that is covering the <dialog />. Setting the pointer-events property to none will let any clicks pass through the ::after element and activate the on:click event attached to the background <dialog />.

Stacking elements like this can quickly get confusing, so I highly recommend using the new 3D View DevTools in Microsoft Edge. This screenshot shows the <dialog /> element covering the viewport, the <section /> at the forefront of the site, and the rest of the site content being covered by the alert and it's overlay.

[[clearfix]]

Managing `tabindex`

tabindex is an HTML attribute that describes the order in which the browser will focus on elements when a user navigates the page using the Tab key. Browsers will automatically assign based on document order, but the HTML spec allows for manipulation in some scenarios. Much like ARIA, it is usually best practice to leave this alone unless you have a very good reason to manually change it.

I have to manually swap a few tabindex attributes to make everything else on the page inert to someone tabbing through the site while the alert is open.

<!-- page.svelte -->
<SEO {...$$props} />

<div
  id='site'
  tabindex={$$slots.alert ? -1 : 0}
>
  <Header />

  <main>
    <slot />
  </main>

  <Footer />
</div>

{#if $$slots.alert}
  <slot name='alert' />
{/if}

To make everything within the main body of the site in the <Page /> component non-focusable when the alert is active, I set a tabindex of -1 to remove it and its children from the native document tab flow. Because the only two things on the page are the #site and the <Alert />, a user shouldn't be able to focus on any element in the background. When $$slots.alert is empty, the ternary will return falsy and set tabindex='0', which will return the element to its original, unset tab order.

tabindex='-1' means that a user can't focus on the element using their keyboard, but it also makes any element, even things like a regular <div>, focusable with JavaScript.

A negative value (usually tabindex="-1") means that the element is not reachable via sequential keyboard navigation, but could be focused with JavaScript or visually by clicking with the mouse. It's mostly useful to create accessible widgets with JavaScript.

<!-- alert.svelte -->
<script>
  export let show
  export let close
  export let title

  const id = slugify(title)
</script>

{#if show}
  <dialog
    open
    on:click={close}
    role='dialog'
    aria-labelledby={`${id}-title`}
    aria-describedby={`${id}-content`}
    tabindex='-1'
  >
    <section>
      <header id={`${id}-title`}>
        <strong>
          {title}
        </strong>
        <button on:click={close}>
          Close
        </button>
      </header>

      <div id={`${id}-content`}>
        <slot />
      </div>
    </section>
  </dialog>
{/if}

By also adding tabindex='-1' to the <dialog /> element inside the alert, JavaScript can make sure a user's focus is set when it is opened.

Trapping Focus

Another accessibility requirement for modal content is that it "traps focus," meaning that a keyboard user cannot navigate outside of the area, analogous to how an overlay on the rest of the site prevents a mouse user from clicking on background elements. This is the second rule from the role element guidlines. The ARIA dialog best practices guide explain what this means pretty explicitly:

Key	Function
`Tab`	Moves focus to next focusable element inside the dialog. When focus is on the last focusable element in the dialog, moves focus to the first focusable element in the dialog.
`Shift + Tab`	Moves focus to previous focusable element inside the dialog. When focus is on the first focusable element in the dialog, moves focus to the last focusable element in the dialog.
`Escape`	Closes the dialog.

To handle the escape key the special <svelte:window /> component can accept an event listener to create a global way to exit the modal.

The main component can use a Svelte Action to attach and remove the events listeners for trapping focus.

<!-- alert.svelte -->
<script>
  export let show
  export let close
  export let title

  const id = slugify(title)

  import focusTrap from 'actions/focus-trap.js'
</script>

<svelte:window on:keydown={event => {event.key === 'Escape' ? close() : null}}/>

{#if show}
  <dialog
    open
    on:click={close}
    role='dialog'
    aria-labelledby={`${id}-title`}
    aria-describedby={`${id}-content`}
    tabindex='-1'
    use:focusTrap
  >
    <section>
      <header id={`${id}-title`}>
        <strong>
          {title}
        </strong>
        <button on:click={close}>
          Close
        </button>
      </header>

      <div id={`${id}-content`}>
        <slot />
      </div>
    </section>
  </dialog>
{/if}

An action is just a function that will be passed the node on which the use: directive was called. The function is called as soon as the element is created, which in the case of my alert means whenever the show prop becom true.

The first thing I want to do when an alert is created is focus on it, which I can do with the .focus() method thanks to the tabindex='-1 from earlier.

// focus-trap.js
function focusTrap(element) {
  element.focus()
}

The next step is to get a list of every element that should be focusable within the <dialog /> box. Taking inspiration from this article by Zell Liew, I used a list of natively focusable elements and created a focusableElements array, filtering out any that should be skipped.

// focus-trap.js
const elements = [
  'a',
  'button',
  'input',
  'textarea',
  'select',
  'details',
  '[tabindex]'
]

function focusTrap(element) {
  element.focus()

  const focusableElements = [...element.querySelectorAll(elements.join(', '))]
    .filter(element => !(element.hasAttribute('disabled') || element.tabIndex === -1))
}

Next, borrowing more logic from this article by Hidde de Vries, the <dialog /> can listen for all keydown events and check if they were the Tab key.

If a user has pressed the Tab key, I want to prevent the default response and implement my own. The two things I need to know for this custom behavior are which element is currently in focus, which I can do by checking the document.activeElement against my focusableElements array, and whether the user intends to move forwards or backwards through the DOM, which I can do by checking whether or not they have included the shiftKey. The idea is to call .focus() on the next focusableElements item when the user presses just Tab, and on the previous element if they have pressed Shift + Tab.

// focus-trap.js
const elements = [
  'a',
  'button',
  'input',
  'textarea',
  'select',
  'details',
  '[tabindex]'
]

function focusTrap(element) {
  element.focus()

  const focusableElements = [...element.querySelectorAll(elements.join(', '))]
    .filter(element => !(element.hasAttribute('disabled') || element.tabIndex === -1))

  element.addEventListener('keydown', event => {
    if (event.key === 'Tab' || event.keyCode === 9) {
      const currentElementIndex = focusableElements.indexOf(document.activeElement)
      event.preventDefault()

      if (event.shiftKey) {
        currentElementIndex === 0
          ? focusableElements[focusableElements.length - 1].focus()
          : focusableElements[currentElementIndex - 1].focus()
      } else {
        currentElementIndex === focusableElements.length - 1
          ? focusableElements[0].focus()
          : focusableElements[currentElementIndex + 1].focus()
      }
    }
  })
}

Navigating the focusableElements array is slightly more complicated because the user needs to loop through the elements if they move forwards from the last element or backwards from the first.

Dealing with focus trapping can get much more complicated than what I need to account for in my fairly simple alert. Luckily, there are existing libraries out there to help deal with these complicated situations. If I were dealing with this again, I might reach for something like focus-trap, or maybe even svelte-focus-trap which takes this same logic and pre-packages it into an action.

Persisting data with `localStorage`

The very last thing to do is make sure that users don't see the same alert over and over, every time they re-visit the site. Since this data is going to be specific to a user and I want it to persist between visits, localStorage is a good candidate.

When a user closes the alert, instead of just toggling the showAlert variable, the function also needs to write to the browser's storage. localStorage will store key-value pairs, so the function can set false for 'labAlert' and this will exist until a user manually clears their browser data.

When the page loads, the component also needs to look into localStorage and see if the user has closed the modal in the past. Svelte component code runs in both the client, where the window object exists, and on the server, where window will be undefined. Before trying to access window.localStorage the component needs to check if typeof window !== 'undefined' to avoid erroring on the server. This check isn't necessary inside of closeAlert since running that function can only be triggered by a user in their browser and not ever on the server. It's also important to check if the returned value is equal to a string value of 'false' rather than the boolean false because localStorage will coerce any set value to a string.

<!-- lab.svelte -->
<script>
  import Page from './page.svelte'
  import Alert from '../components/misc/alert.svelte'

  let showAlert = true
  if (typeof window !== 'undefined' && window.localStorage.getItem('labAlert') === 'false') {
    showAlert = false
  }

  const closeAlert = () => { 
    showAlert = false
    window.localStorage.setItem('labAlert', false)
  }
</script>

<Page {...$$props} >

  <slot />

  <Alert
    title='Caution!'
    show={showAlert}
    slot='alert'
  >
    <p>
      Some features in the section require JavaScript, 
      might not work great on mobile, 
      and may not have been thoroughly tested.
    </p>

    <button on:click={closeAlert}>
      That's okay.  
    </button>
  </Alert>

</Page>

But wait... what if the content in the modal changes and a user needs to see new, important data before they proceed? This can be accomplished by storing the content of the alert in localStorage instead of only a one time boolean value.

The text content of the alert can be abstracted to a variable that will hold the HTML as a string. It can then be used in the body of the component using Svelte's @html template syntax. When a user calls the closeAlert function, instead of storing 'false', the function can use the browser's btoa method to convert the alertContent to a base64 string and store it. Since btoa(alertContent) will return a different string given new content, when the component checks localStorage.getItem('labAlert'), showAlert will be set only if a user has seen this exact content before.

<!-- lab.svelte -->
<script>
  import Page from './page.svelte'
  import Alert from '../components/misc/alert.svelte'

  const alertContent = `
    <p>
      Some features in the section require JavaScript, 
      might not work great on mobile, 
      and may not have been thoroughly tested.
    </p>
  `

  let showAlert = true
  if (typeof window !== 'undefined' && window.localStorage.getItem('labAlert') === btoa(alertContent)) {
    showAlert = false
  }

  const closeAlert = () => { 
    showAlert = false
    window.localStorage.setItem('labAlert', btoa(alertContent))
  }
</script>

<Page {...$$props} >

  <slot />

  <Alert
    title='Caution!'
    show={showAlert}
    slot='alert'
  >
    {@html alertContent}

    <button on:click={closeAlert}>
      That's okay.  
    </button>
  </Alert>

</Page>

btoa, just like localStorage only exists in the browser so it will need the same window check to not error on the server. Since btoa (which stands for "binary to ASCII") returns a string, it can be used directly in the === check, unlike a boolean that needs to be coerced.

The Final Product

The final component should be something that has both an ergonomic experience for the developer, and a non-intrusive experience for the site user. Hopefully I managed to accomplish both.

As usual, thanks to the Svelte discord for helping me figure out a few aspects of the code, particularly kursus75 and c-bandy with help around localStorage and Svelte stores and GrygrFlzr for help with my deploy.

I hope this walkthrough helps people build their own inclusive version of this component. If this does help you build something cool, shoot me a link on Twitter because I'd love to see it! Reach out with any questions or concerns too, especially if there are any errors I need to fix with this component's accessibility.

Also head over to the /lab section of my site to see this component in action, as well as all the weird experiments I've got there.

Why My Blog Stopped Using Deploy Previews

ryanfiller — Mon, 31 May 2021 00:00:00 +0000

I love Netlify. I think it's a wonderful service that provides tremendous value to many developers and teams. But, like so many things in the modern world, I think it’s easy to overlook some of the behind-the-scenes consequences of convenience. This post examines the cost of what some of those conveniences, how to change some default settings to lessen their impact, and what some situational alternatives can be.

What are Deploy Previews?

One of the core tenants of JAMstack is that a site builds, then it deploys. Netlify, like any other host for statically built sites, makes use of "immutable deploys."

While a "mutable" item can change (be mutated) over time, an "immutable" item cannot. Once created, an immutable deploy of a website becomes an artifact which will not change. Instead, deploys result in new versions or instances of the site, and traffic is routed to them accordingly.

When paired with atomic deploys, immutable builds make it possible for sites to enjoy abilities such as instant rollbacks and versioning, and help to ensure that the code and assets of a website can be maintained in a known state.

jamstack.org

A Preview Deploy is something special that Netlify adds to atomic deployment.

Deploy Previews work by deploying every pull request from your Git repository to a unique URL; completely different from the one your main site uses. You and your team can see how those changes look before they’re merged into the main branch and deployed to production.

Preview Deploys are useful because they let you test a new feature in a production-like environment, share a url to get feedback before a release, or easily cross-browser check a site.

The Deploy Preview settings for a site live at Settings > Deploys > Deploy Contexts, and the defaults look like this:

The different options for each setting look like this:

One interesting thing is that the Any pull request against your production branch option will still build a preview even for a draft pull request.

With Great Power... Comes Great Responsibility

I can’t find a source for the first person who said this, but it is a well known best practice to “commit small; commit often.” While this is generally the best way to use version control, this could cause a lot of builds using Netlify’s default settings.

This is a habit I picked up at my day job where I work on a team, but I usually open a pull request fairly soon after I create a new branch. I know most people probably don’t work this way, but I make heavy use of git’s rebase functionality and keeping an open PR is a good safety net when changing the commit history.

Any pull request regardless of open, closed, or merged status, keeps a history of commits that have been force pushed to it. This PR, merged months ago, still lets me access code from the commits 23555ed, d58c989, and 9022382. If you mess up during a rebase and push something you didn't mean to, having an open PR can be a much easier way of recovering code than trying to fish it out of the local reflog.

Though once this PR is open, Netlify's pipeline will become aware of it and will start building a preview deploy any time you push code.

Also, some tools, like dependabot, might automatically come with a starter project and keep making PRs after you've forgotten about a project.

Even Netlify's own CMS might be creating deploys without you realizing it. NetlifyCMS is a git-based CMS, so of course it will be making commits as content is added or changed. But, even with the editorial_workflow option enabled, the CMS will open a draft PR and still create a deploy.

None of this is meant to knock these tools at all! I've written in the past about how much I enjoy NetlifyCMS and I still use it for small freelance sites that need to be editable by clients. That point I'm trying to make is that it is important to know how a tool works when you use it. In this case creating a post will create a pull request, and then every subsequent save of that page will create a commit, and thus a deploy.

This is not something I always knew I needed to be careful about. One of my posts alone generated almost 40 separate deploys.

Some Downsides to "Single Use Deploys"

One thing that might make someone start paying attention to how many deploys they are creating is Build Minute usage. Netlify's plans only offer so many minutes per month before the next tier of billing kicks in. I'm sure everyone wants to avoid incurring any unexpected costs for a site, but I wanted to look at the other cost - the deploys themselves.

Because of the nature of how Netlify's roll backs work, deploys never go away.

When paired with atomic deploys, immutable builds make it possible for sites to enjoy abilities such as instant rollbacks and versioning, and help to ensure that the code and assets of a website can be maintained in a known state.

jamstack.org

I reached out to Netlify about how exactly their deploy process works. Their customer service rep told me this was getting close to "technical secrets territory," but was able to link me to this helpful blog post by Cassidy Williams. The section about what happens when you deploy a JAMstack project demonstrates (with gifs!) how the deploy process happens.

Netlify's deploys work a little bit like git commits — each one builds on previous ones, which is why you're able to easily "roll back" to a previous atomic state. In order to maintain the ability to always and instantly revert to a previous deploy, Netlify doesn't let you remove them.

And this isn't just production deploys, this applies to preview deploys as well. To be honest, I'm not sure why this is and I couldn't find a definitive answer anywhere. It could be that these deploys are cached or reused in some way to support production builds, or it could just be that there is no meaningful technical distinction between build types in Netlify's system.

As far as I can tell, unless you delete a site from Netlify altogether, once you create a deploy it exists forever. Here is the first draft of the first post for this blog from December 31, 2019 at 7:42am. It's probably riddled with typos. Here is my first commit to my first Gatsby project while I was working through their tutorial, deployed January 23, 2018 at 10:02pm. Here is my very first deploy ever to Netlify, from September 16, 2017 at 1:54pm, just called "refactor."

It might seem cool that these sites exist forever, but ask yourself how often you really need to go back and look at the state of a site from over a year ago? Or even a few months ago? Also, consider this tweet from Gerry McGovern -

Last year I read Gerry's book, World Wide Waste. The gist of the book is to try and get everyone to consider the physical world ramifications of their digital world choices. One series of facts really stood out to me -

Around 90% of data is never accessed three months after it is first stored.

80% of all digital data is never accessed or used again after it is stored.

Businesses typically only analyze around 10% of the data they collect.

90% of unstructured data is never analyzed.

90% of all sensor data collected from Internet of Things devices is never used.

from Gerry McGovern's website

For a lot of people, myself sometimes included, these Deploy Previews are artifacts that are never even looked at.

Estimating the Cost of This Site

After seeing Gerry's tweet I wanted to try to calculate a number for the amount of CO2 my blog has generated via hosting my deploys. I really want to stress that this is a ballpark number. I'm not an expert on things like compression and bandwidth and I'm working with a lot of assumptions and averages. Hopefully I'll get fairly close.

The first thing I did is determine how big each deploy is. This is kind of a tough number to get for a few reasons. First, the site gets bigger as I add more content and features to it, so I know I'll be looking at some kind of average. Second, roughly halfway between relaunching in 2020 and now I changed frameworks from Gatsby to Sapper which definitely changed the overall bundle size of my site.

I looked around in Netlify to see if they had any info on storage size but the closest metric I could find was bandwidth used per month. Again, I'm not an expert in this, so the best way I could figure out the size of a site was to use SiteSucker to download it and check its size on my local disk. After getting a rough estimate for month and averaging them, these are the numbers I got.

	Gatsby	Sapper
Average Size	79759.73 kb (0.08 gb)	33000.00 kb (0.03 gb)

I use Netlify Large Media to handle hosting media assets and those should be versioned outside of site deploys and then only pulled in by url reference. However, for the demonstration here I'm going to leave them in the calculation.

Now that I knew about how big each deploy is, the next step was to figure out how many times the site has deployed. This number was pretty easy to get. For each project I went to the Project > Deploys tab, counted the number of deploys per page then multiplied by the number of pages. I did this both for my Production and Preview deploys since neither can be removed.

	Gatsby	Sapper
Preview Deploys	73	205
Total Deploys	319	261

The extremely large number of Sapper deploys vs Gatsby deploys seems to be because I was working with a feature I needed to test against a bot crawler, and this wouldn't work running the site locally.

To get a final number for each, I multiplied these totals by the average size of each deploy.

	Gatsby	Sapper	Total
*Average Size Preview Deploys**	5.84 gb	6.15 gb	11.99 gb
*Average Size Total Deploys**	25.52 gb	7.83 gb	33.35 gb

If I were to hypothetically stop working on my site and leave it with its current number of deploys for an entire year, that means I can take this total number and multiply it by Gerry's calculation of 30 grams per 1gb of stored data. That comes out to 910.5 grams, or just over two pounds. Based on this random nasa.gov link I found, that's about one 10th of a gallon of burned gasoline.

About a third of that overall number comes from Deploy Previews, and I want to reference two of the numbers from World Wide Waste again -

Around 90% of data is never accessed three months after it is first stored.

80% of all digital data is never accessed or used again after it is stored.

These are deploys I simply do not need to keep forever. And because these deploys are out there and can't be removed, they'll compound this storage cost every year that they continue to exist. There is an argument to be made that a lot of those Production Deploys aren't needed either, but theoretically Netlify should keep them around in case I ever need to roll back to one of them.

This might seem insignificant, but keep in mind this is only one project of mine. Granted I don't actively work on them nearly as much as I do my blog, but I currently have two dozen sites hosted on Netlify. Multiply this across Netlify's over 1,000,000 devs and the scope is anything but insignificant.

If every Netlify user has only one site that they have deployed as much as this blog, that means the equivalent 100,000 gallons of gasoline burned just for one year of storage alone. According to epa.gov, that's the same as driving 2,233,479 miles in a car in the same amount of time. To offset this amount of C02 you would need to plant 14,695 trees and let them grow for ten years!

What Can You Do?

I'm certainly not suggesting that anybody not use Netlify. On the other hand, I have made some changes to how and why I use Netlify by tweaking my Deploy Settings.

First, I have Deploy Previews set to Don’t deploy pull requests. This makes sure that my "make a PR as a rebase safety net" workflow doesn't create deploys, and neither do things like dependabot. Second, instead of Branch Deploys set to Deploy only the production branch I use Let me add individual branches where I set up a dedicated staging branch that I can merge into any time I want to manually generate a preview.

I've also made a conscious effort to only use my staging branch when I'm trying out a new feature that needs to be tested in as close to the actual production environment as possible. For things like getting a blog post proofread or trying to do a quick check of some styles on a mobile device I've switched over to using surge.sh.

surge.sh

surge.sh is not a new tool. It, along with CodeShip, is what I used to use to host and deploy my site before I moved to using Netlify. surge.sh and Netlify are similar in some ways, with surge.sh being a more stripped down version of the same type of static hosting service. After installing the surge cli, any directory can be instantly deployed to a surge.sh url.

The CLI accepts a number of configuration flags for options such as which directory to publish and which url to publish use. To make this all a little more automatic, I added a surge script to the scripts section of my package.json file.

"surge": "npm run export && surge --project ./ __sapper__ /export --domain beta.ryanfiller.com"

This lets me run npm run surge which will export the static version of my site and push it to the subdomain beta.ryanfiller.com.

One nice thing about this is that by pushing to the same url over and over again, I can overwrite the version of the site that was previously hosted there. I like this because it means that when I link someone to a preview of a blog post they don't have to sift through different versions of hashed urls. They can visit the beta subdomain and see the draft that I most recently pushed.

I reached out about how surge.sh works behind the scenes, and they were actually nice enough to let me in on a semi-secret upcoming version of the CLI. This version was described as "unreleased but actually quite stable", and I've had no issues using it. A preview of it can be found (at the time of me writing this, anyways) by bumping your version up to the current release candidate.

npm install -g surge@edge

After this version of surge is installed you can run surge --help and see a list of all the new available commands. There's a ton of good stuff here, but I wanted to highlight a few that are relevant to the topic of website size.

bash
$ surge -h

Surge.sh ⚡ Static Web Publishing 0.24.0-rc.6

surge list list all project revisions
surge discard remove revision from system
surge audit audit edgenode state
surge teardown tear down a published project


To be honest, until seeing this new list of commands and running some of them, I had a pretty big misconception about how surge.sh actually works. I was under the impression that when you push to an existing url the old site was gone and replaced with the new one. Running `surge list` against some of my old deploys actually showed me that every version of them was still around, similar to Netlify. The big win here, to me, is being able to run `surge discard` against a particular deploy and remove it once you're done with it. And of course, if you want to remove a project entirely you can run `surge teardown`. `surge audit` was also super cool, it shows a list of deploys with their unique `id`, total file count, and how many megabytes of space they're taking up on the surge.sh servers.

$ surge audit beta.ryanfiller.com

sfo-15 1619787001755 255 files 55.35 MB
sjc-00 1619787001755 255 files 55.35 MB
jfk-01 1619787001755 255 files 55.35 MB




This makes surge.sh an awesome tool, and one that puts more power back in your hands as far as managing what artifacts from your site persist forever. Netlify is a pretty big ecosystem at this point, with [SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), Large Media, Functions, Auth, Analytics, and so much else, but for some simple projects in the future I think I'm going to look at hosting them solely on surge.sh

## My Netlify Wish List

This isn't meant to be a list of _demands_, only a list of things I'd do if I had some magic wishes and could make changes. I'm sure that some of these are a _lot_ more technically challenging than they seem on the surface. In no particular order:

### Don't Automatically Deploy Draft PRs

[GitHub added draft pull requests](https://github.blog/2019-02-14-introducing-draft-pull-requests/) pretty recently, but it does seem like this data is available in their [REST API](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-for-draft-pull-requests). It looks like GitLab also already supports [draft merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/drafts.html) and Bitbucket [is working on a similar feature](https://jira.atlassian.com/browse/BCLOUD-12503).

Maybe in the future Netlify could add an additional configuration knob to decide whether or not a draft should create a build?

This would also solve the issue where NetlifyCMS accidentally creates a deploy on every save of the page.

### Add More Information to Outgoing Webhooks

I didn't even touch on this in this post, but it would be nice to customize [Deploy Notifications](https://docs.netlify.com/site-deploys/notifications/) and [Build Hooks](https://docs.netlify.com/configure-builds/build-hooks/) a little more. My main blog uses these to [syndicate posts](https://www.ryanfiller.com/blog/getting-data-in-and-out-of-gatsby) to [another domain](https://ryan.beardedrobots.com/), and builds of the secondary site are currently triggered by both Production and Previews Deploys of the main site.

There are already a lot of options around Deploy Preview in `Settings > Deploys > Deploy Notifications`, maybe somehow loop these into the `Outgoing Webhook` option?

### Change The Default Settings

I know that within the last few weeks Netlify has announced a [cool, new feature for Deploy Previews](https://www.netlify.com/products/deploy-previews/). Honestly, I'm kind of jealous that such an integrated tool didn't exist when I worked at an agency and needed to gather client feedback. But, especially since, as of now, every deploy is forever, is an automatic deploy for every PR something that every site needs turned on by default?

Previews are a useful feature for a lot of people, but I'd love to know if the number of deploys created that were never even looked at would go down if this was an opt-in rather than opt-out setting.

### Let Me Remove Deploy Previews

I know this one is a stretch, but I would _love_ to be able to remove all of the one-off previews of my sites that I either didn't mean to make or don't need anymore. I have a feeling that of all my list this is the most technically complex — I understand that granting users this power makes the stack of deploys a bit like a [game of Jenga](https://en.wikipedia.org/wiki/Jenga) where you hope you're not removing a deploy you might need to roll back to later.

## Some Final Thoughts on Netlify

[Incremental Static Regeneration](https://www.netlify.com/tags/incremental-static-regeneration/) is an up-and-coming Netlify feature, and is the actual topic of [Cassidy's article](https://www.netlify.com/blog/2021/03/08/incremental-static-regeneration-its-benefits-and-its-flaws/#what-happens-when-you-deploy-a-jamstack-project) that I linked to earlier. [Jason Lengstorf](https://twitter.com/jlengstorf) and [Phil Hawksworth](https://twitter.com/philhawksworth) were recently guests on two podcasts that I listen to ([ShopTalk Show #464](https://shoptalkshow.com/464/) and [Toolsday #130](https://spec.fm/podcasts/toolsday/wKcuYe6l)) to talk about this feature. ISR is mostly unrelated to the topic of this post, but in both podcast episodes the phrase "burn the electricity to build a bunch of rarely visited pages" was used and it caught my attention both times. This post isn't meant to disparage Deploy Previews in any way. It sounds like Netlify already has put some thought into servers doing needless work during the build process, I would love to see them adopt a similar train of thought about "burning electricity" with hosting as well.

## Acknowledgments and Disclaimers

Thank you to [Gerry McGovern](https://twitter.com/gerrymcgovern) for writing both the book and the tweet that inspired this post. _World Wide Waste_ really has changed how I approach most everything I do online. Also, thank you to [Scott Parker](https://mobile.twitter.com/scottpieparker) and [Brock Whitten](https://twitter.com/sintaxi) from Netlify and surge.sh respectively for doing their best to answer my cryptic "hey, but how does your product _really_ work?" emails. The resources they provided me with helped to fill in a lot of details I was missing about how these technologies work.

I'm wouldn't be surprised there's holes in my math or overall logic. There's probably some type of server-side compression or way to use [gzip](https://www.gzip.org/) I'm not accounting for. Or I didn't factor in how Large Media works correctly. I also didn't account for redundancy with Netlify's [CDN](https://jamstack.org/glossary/cdn/) or the fact that [some of these servers are powered by renewable energy](https://www.netlify.com/sustainability/). This wasn't meant to be a hard breakdown of the numbers, just some quick math to show how much things we tend to not think about can add up at scale.

If you have questions, comments, or concerns about the numbers I showed and how I came up with them, please let me know! Math is not always my strong suit and I'd love to update this post with more correct information.

If this post was meaningful to you in any way, share it! I really want to emphasize that my goal isn't to shame anyone for the tools they use, but instead to get more people to think through the long-term consequences of their short-term actions, especially online in digital spaces.

Building a Color Scheme Toggle

ryanfiller — Fri, 30 Apr 2021 00:00:00 +0000

In my last post I covered how to choose a flexible set of colors and use prefers-color-scheme to switch them out depending on a user's color preference. This post is about taking that a step further and build a toggle so a user can set and save a color theme.

My site is built using Sapper, so some of the code will be Svelte-specific. However, most of these concepts are broad enough that they should be applicable other frameworks, or even plain JavaScript. I'll make sure to point out anything that is relying on a Svelte-specific API.

Setting up Colors

Using css-in-js is a hotly topic debated, with some valid pros and cons. I've gone back and forth on whether or not to use it, I currently think you should separate your concerns. This method isn't a css-in-js set up, but I think it's helpful to have a single source of truth for any configuration.

The color chart component I used to build my light and dark themes needs data from JavaScript. I want this chart to work as an server-side rendered component, so I need to be able to pass it an array of colors without needing to query them from the DOM. In my project I have a styles.js configuration file that looks like this:

const colors = {
  black: '#080025',
  white: '#fefdf2',
  ...
}

const themes = {
  light: {
    text: colors['black'],
    background: colors['white'],
    ...
  },
  dark: {
    text: colors['white'],
    background: colors['black'],
    ...
  }
}

The two themes also live in this same file, and are constructed by choosing colors from the larger colors object.

The mechanics of getting and setting css custom properties is kind of verbose, so I created two helpers methods:

function getCustomProperty(property) {
  if (typeof(window) != 'undefined') {
    return getComputedStyle(document.documentElement).getPropertyValue(`--${property}`).replace(/(\"|\')/g, '').trim()
  } else {
    return ''
  }
}

function setCustomProperty(property, value) {
  if (typeof(window) != 'undefined') {
    document.documentElement.style.setProperty(`--${property}`, value)
  }
}

Svelte will error if it tries to access the window object during server-side rendering, so it's important to make sure window exists before trying to access any document properties. I'm doing this because I specifically know I have to account for server-side rendering, but this catch is a best practice to keep the function from throwing any unexpected errors.

The last helper method is one that will take an array of theme colors, map through and apply the setCustomProperty() function, then join them into a string of CSS variables.

const setTheme = (theme) => {
  return Object.entries(theme).map(color => {
    const [name, value] = color
    return `--color${capitalize(name)}: var(--color${capitalize(value)});`
  }).join('\n')
}

This might all seem like a lot of legwork just to set some color variables, but these helper functions will be super useful later, I promise.

Designing the Toggle

Josh W Comeau has a great post about how he built The Peferct Dark Mode for his site. I thought the section about requirements was especially helpful, and is the general plan I'm going to follow for my toggle. My goals were mostly the same as his, but I chose to tackle them in a different order:

The site should respect the user's Operating System preference if it is set and supported, if not it will default to light theme.
The user should be able to click a button to toggle themes.
If the user has disabled browser JavaScript, the toggle should not appear.
The site should remember the theme the user toggled to, and should use this over their OS preference.
The site should not show a flash of the wrong theme while loading.
It should not be possible to mismatch the state between the theme and the toggle button.

Some Prerequisites

This post by Andy Bell (who for some reason goes by Hank Chizljaw sometimes) puts together a pretty clever way to handle user color preferences. To borrow some of the scaffolding from his post, there are a few constants we need to set.

// what we will store this in local storage as
const LS_KEY = 'user-color-scheme'

// an HTML data-attribute to keep track of user preference
const DOM_ATTR = `data-${LS_KEY}`

// the name of the CSS variable we'll be reading and overwriting
const CSS_PROP = LS_KEY

1. Reading a User's OS Preference

In part two of this series I briefly showed how to put colors behind prefers-color-scheme. That feels like the most obvious tool to reach for to accomplish goal #1. Using this media query will read a user’s configured preference from their browser, but there’s some nuance to consider knowing that we’ll be making a button to manually toggle this. There isn’t a way for any code from a browser to change a user’s Operating System level preferences, so we need to use a different method to toggle the theme.

Because it isn't possible to call any JavaScript inside of the special Svelte <style> tag we have to get creative. We can call the setTheme() function inside of a template string combined with the Svelte @html interpolation to build out the contents of a regular <style> tag. This entire section needs to be wrapped in a <svelte:head> tag so that the framework will hoist it to the appropriate place in the document <head>.

<svelte:head>
  {@html `
    <style>
      :root {
        --${CSS_PROP}: 'light';
        ${setTheme(themes.light)}
      }

      @media (prefers-color-scheme: dark) {
        :root {
          --${CSS_PROP}: 'dark';
          ${setTheme(themes.dark)}
        }
      }
    </style>
  `}
</svelte:head>

If you're not using Svelte, you can do the same thing by calling document.getElementsByTagName('head') and then using the appendChild() method to add a <style> tag.

Since we also want to track this OS preference in JavaScript later, we’re going to borrow another idea from Andy’s post and set another variable to flag OS preference. In order to easily find and change this later, we want to use the CSS_PROP variable from earlier.

The site will render the light theme by default, if a user has no OS level preference, or if their system does not support prefers-color-scheme at all. If the OS signals to the browser that the user prefers a dark color scheme we can use this CSS variable later to provide the right set of colors. By tracking the theme with a single value, this also makes it easier to set up the toggle button later.

2. Clicking the Toggle Button

The click event logic for the toggle button starts pretty straightforward. I abstracted it into several smaller functions that will have more complexity added later.

const getOpposite = (currentMode) => {
  return currentMode === 'dark'
    ? 'light'
    : 'dark'
}

const setPreference = (newPreference) => {
  if (window) {
    document.documentElement.setAttribute(DOM_ATTR, newPreference)
    setCustomProperty(CSS_PROP, newPreference)
  }
}

const toggleColorScheme = () => {
  let currentPreference = getCustomProperty(CSS_PROP)
  const newPreference = getOpposite(currentPreference)
  setPreference(newPreference)
}

A user clicks the button and a chain of helper functions will fire. The first will read the --user-color-scheme variable we set in step #1. This functions call a second function to get the opposite value, and then calls setPreference(). setPreference() overwrites the CSS variable and sets the data-user-color-scheme attribute on the page’s <html> element. To know what state we’re toggling from we’ll look to the CSS_PROP custom property we set in the <style> tag. If it is equal to 'dark' we know the user has an OS level preference and getOpposite() will return 'light'. If it’s 'light' or undefined, then getOpposite() will return 'dark'.

We need to update our :root CSS logic a little to allow the chosen theme to take precedence over any OS level theme.

<svelte:head>
  {@html `
    <style>
      :root {
        --${CSS_PROP}: 'light';
        ${setTheme(themes.light)}
      }

      @media (prefers-color-scheme: dark) {
        :root {
          --${CSS_PROP}: 'dark';
        }

        :root:not([data-user-color-scheme]) {
          ${setTheme(themes.dark)}
        }
      }

      [data-user-color-scheme='dark'] {
        ${setTheme(themes.dark)}
      }
    </style>
  `}
</svelte:head>

We can use the CSS :not pseudo selector to check if the <body> attribute has been set by the toggle button. If it does not exist we can rely on the wrapping prefers-color-scheme media query.

This might seem a little confusing, but the logic works like this:

The site will always default to the light theme.
If the OS is set to dark theme and the user has not made a choice, the site will show the dark theme because of the prefers-color-scheme setting.
If the user has chosen dark theme with the toggle, the site will show that because of the <body> attribute.
If the user has chosen light theme with the toggle, there is no explicit state for this so the site will fall back to the default light theme.

The last step in setting up the toggleColorScheme() function is to deal with how Svelte optimizes code for SSR. Because toggleColorScheme() and getCustomProperty() both make calls to the window object, this code breaks when it runs server-side. To work around this, we can use a trick from the Svelte docs and reassign them after the window object exists. If you aren't using Svlete this shouldn't be an issue, but if it is in your framework there's likely a similar workaround out there.

<script>
  let currentColorScheme
  let toggleColorScheme
  onMount(() => {
    toggleColorScheme = () => {
      const currentPreference = getCustomProperty(CSS_PROP)
      const newPreference = getOpposite(currentPreference)
      setPreference(newPreference)
    }
  })
</script>

3. Intentionally Blocking JavaScript

Putting blocking JavaScript in the <head> of a website is something that typically should be avoided. The page rendering process is complicated, but this is the most relevant concept to understand:

<script> tags — particularly those without an async or defer attribute — block rendering, and pause the parsing of HTML.

You wouldn't want to load, say, all of jquery at the top of your page before you even need to use it. Since we don’t want this toggle to appear for users who don’t allow JavaScript and therefore can't interact with it, we need to run a script that intentionally blocks the rest of the page from loading. The <body> element needs to have a data-no-js attribute added by default, and a quick script will run before loading the rest of the page to remove it.

Just like with the CSS block earlier, the trick here is to again use the @html interpolation. Rather than hook into the regular Svelte <script> tag, we want to render a string so that when the page is rendered at build time this code gets baked into the actual page source. This means it will execute as soon as the browser comes across it and not be optimized by Svelte to be non-blocking.

<svelte:head>
  {@html `
    <script>
      document.body.removeAttribute('data-no-js')
    </script>
  `}
</svelte:head>

Since any user with JavaScript will immediately have this attribute removed, we can now target a CSS class of .needs-js only when this attribute is present. This temporarily blocks rendering and happens before the rest of the page loads, so neither type of user should get a blip of the toggle when they should or shouldn’t see it.

body[data-no-js] .needs-js {
  display: none;
}

4. Keeping Data in LocalStorage

localStorage is a browser API that can be used to store a list of key value pairs per website. These values will persist even after a user leaves a website, making this the perfect place to store a user's color scheme preference after they set it.

We can add a line to our setPreference() function and use the LS_KEY constant we added earlier.

const setPreference = (newPreference) => {
  if (window) {
    document.documentElement.setAttribute(DOM_ATTR, newPreference)
    setCustomProperty(CSS_PROP, newPreference)
    window.localStorage.setItem(LS_KEY, newPreference)
  }
}

Now, when a user clicks the button, this script will modify the <body> tag attribute, update the CSS variable, and save either 'light' or 'dark' in localStorage so we can read it again when they come back to the site later.

The actual logic for clicking the button needs a slight update as well. We want data persisted in localStorage to override any OS preference. We can use window.localStorage.getItem and our LS_KEY to check and see if a user has any existing data. If they do, we need to pass it to setPreference() instead of their CSS_PROP value.

toggleColorScheme = () => {
  const currentPreference = window.localStorage.getItem(LS_KEY) || getCustomProperty(CSS_PROP)
  const newPreference = getOpposite(currentPreference)
  setPreference(newPreference)
}

If existingUserPreference is undefined the function will fall back to their OS preference and setPreference() will save this new value in localStorage.

5. Reading Data Without Flashes

In order to check the stored value whenever a user visits the page, it might seem like the best way to do this is an onMount function as soon as the page loads.

onMount(() => {
  const existingPreference = window.localStorage.getItem(LS_KEY)
  setPreference(existingPreference)
})

If you've been coding along you likely see the problem here. If you haven't, here's an example of the issue we're facing.

Sorry, your browser doesn't support embedded videos.
a flash of the wrong theme, brief light theme on the right, brief dark theme on the left

onMount fires after the component loads, which means that if the user's OS preference doesn't match the value they have saved in localStorage they will see a flash of that theme before setPreference() can fire and sort out the appropriate classes on the <body> tag. That's no good.

We're actually going to use the same trick here that we did to remove data-no-js before the page fully loaded.

<svelte:head>
  {@html `
    <script>
      document.body.removeAttribute('data-no-js')
      var existingUserPreference = window.localStorage.getItem('${LS_KEY}')
      var setPreference = ${setPreference.toString()}
      var getCustomProperty = ${getCustomProperty.toString()}
      var setCustomProperty = ${setCustomProperty.toString()}
      setPreference(existingUserPreference, getCustomProperty, setCustomProperty, '${LS_KEY}', '${DOM_ATTR}', '${CSS_PROP}')
    </script>
  `}
</svelte:head>

This might look slightly strange, but there are two things going on here.

First, just like with the removeAttribute('data-no-js') script, we need everything to be self-contained. This means we need a complete string that creates a new function and not just a reference to an existing assignment from the Svelte <script> tag. Luckily, the function prototype contains a .toString() method that will stringify and return the entire function block. By combining this with Svelte’s @html interpolation we can redefine the same functions in the inline script.

The second caveat is that in order to stay properly encapsulated, setPreference() will need to accept a few more arguments. We can stringify setCustomProperty() the same way, but we'll need to pass that instance of setCustomProperty() into setPreference() in order for it to work correctly. The same is true with the stringified and interpolated versions of all of our getters, setters, and constants.

const setPreference = (newPreference, setCustomProperty, LS_KEY, DOM_ATTR, CSS_PROP) => {
  if (window) {
    document.documentElement.setAttribute(DOM_ATTR, newPreference)
    setCustomProperty(CSS_PROP, newPreference)
    window.localStorage.setItem(LS_KEY, newPreference)
  }
}

We’ll also need to update the calls to setPreference() inside of toggleColorScheme(). It needs to accept and use the instances of those functions and constants from the Svelte instance rather than the inline <script>.

toggleColorScheme = () => {
  const currentPreference = window.localStorage.getItem(LS_KEY) || currentColorScheme
  const newPreference = getOpposite(currentPreference)
  setPreference(newPreference, setCustomProperty, LS_KEY, DOM_ATTR, CSS_PROP)
}

It might seem like putting this many blocking scripts on a page could start to get into performance-harming territory. Josh has a note on his post where he tested this. I also did my own test here using console.time() and found that the entire block of scripts runs in less than 1ms.

6. Keeping Everything in Sync

The last concern is making sure that a user is never able to load a page or click the toggle in such a way that they see the wrong theme with the wrong button.

The best way to keep things as in-sync as possible is to try to rely on a single source of truth and let everything read from there. For me, the CSS_PROP on :root is the single source of truth. It reads from localStorage if it exists and then falls back to being set by the initial media-query. JavaScript then adds it to the <body> tag and updates the value in localStorage if it has changed. This very specific set of dominos is why I avoided using something like window.matchMedia to read the user's prefers-color-scheme value directly.

In order to fire off this chain of events correctly, we need to make one more change to the setPreference() function to correctly update the <body> tag during the blocking period. When setPreference() is called from the inline script, it may or may not find an existing preference in localStorage. We need to add an else condition to read the CSS_PROP value and update the rest of the page accordingly.

const setPreference = (newPreference, getCustomProperty, setCustomProperty, LS_KEY, DOM_ATTR, CSS_PROP) => {
  if (window) {
    if (newPreference) {
      document.documentElement.setAttribute(DOM_ATTR, newPreference)
      setCustomProperty(CSS_PROP, newPreference)
      window.localStorage.setItem(LS_KEY, newPreference)
    } else {
      const OS = getCustomProperty(CSS_PROP)
      document.documentElement.setAttribute(DOM_ATTR, OS)
      setCustomProperty(CSS_PROP, OS)
    }
  }
}

Making sure the button never shows the wrong state also means looking to a single source of truth. We can actually style the toggle button based directly off of the inline style that the setCustomProperty helper class applies. For Svelte we'll have to use the :global() style modifier to escape the style encapsulation if everything isn't in the same file.

:global([style*='light'] .color-scheme-toggle-button) {
  ...
}

:global([style*='dark'] .color-scheme-toggle-button) {
  ...
}

The selector [style*='...'] is using a matcher to target any element with an inline style attribute that contains either version of the set --user-color-scheme value. Since we've gone through steps to make sure all other logic checks this same source, styling based directly on this is much safer than using another JavaScript function to try to toggle CSS classes on the button element.

Final Code

The final code for the entire component should look something like this.

The actual code as it exists on my site is a bit more abstracted, but you can find the data-no-js functionality in my template.html file, the setting of my CSS variables from JSON in my styles.svelte file, the rest of the theme and button logic in the component file.

As always, reach out on Twitter or GitHub with any questions, comments, or concerns. Happy theming!

Building a Better Svelte Data Flow

ryanfiller — Sun, 28 Mar 2021 00:00:00 +0000

This blog has been running as a Svelte-powered Sapper app since October 2020. Before changing frameworks from Gatsby I put together a test site and wrote a blog post about what I learned about configuring Sapper. I found a set up that worked for me, so I switched my site over.

The data flow I explored on my test site worked perfectly enough until I ran into a snag — I wanted to compose a post with information from two different sources without having to load data client side and rerender. I built a solution that I think combines the best of Sapper’s native data flow with mdsvex’s powerful preprocessing.

This post is a somewhat deep dive, so if it's confusing checkout the original Sapper/mdsvex post and come back after that.

If you want to skip the technical explanations of Sapper and mdsvex and get right to how I solved the problem, start here.

How does Sapper work?

Sapper uses file based routing where files and folders are used to build out the page structure of the final site. The Sapper documentation has a section about how this works, but if you're new to the framework I think it's more informative to look at the /routes directory in the sapper-template starter repo.

Each file in /routes corresponds to a url endpoint on the site. So /routes/about will produce /about.html, /routes/about/me produces /about/me.html and so on with no limit for how deep nesting goes. This post is mostly about routes that use dynamic parameters, examples of which can be found in the sapper-template's blog directory.

The sapper-template skips over this step for brevity, but normally a site will contain a collection of markdown files containing the content for each post. In order for Sapper to use this content, two dynamic routes need to exist — index.json.js and [slug].json.js.

index.json.js will use the node file system API to look through the markdown files and build a list. [slug].json.js needs to use something like unified to turn the markdown into valid HTML.

.svelte files inside the /routes directory get access to a special preload() function that can be called from the <script context='module'> tag. Inside this function pages can access any params captured via the brackets in their file name. [slug].svelte can use params.slug and fetch() to make a call against the corresponding /[slug].json route and get data.

If the app is being run in sapper build mode, [slug].svelte will fetch data and generate a page whenever a user visits a url that corresponds to an existing markdown file. Building a site with sapper export will crawl any links on a site and pre-build and statically export any pages it finds.

One final important Sapper concept is layouts. A file named _layout.svelte will automatically be rendered for any page within that route, with the component passed into the _layout's default <slot />. This is helpful for any elements that will be repeated on every final page, like a header and footer or navigation. One very important consideration, however, is that because of how data flows from parent to child, a _layout does not have access to the $$props object that its child receives.

How does mdsvex work?

mdsvex is a tool that lets you embed functional Svelte components right into Markdown files. It also hooks into Sapper's call to svelte.preprocess to take away some of the manual work of creating pages. mdsvex is a preprocessor for Sapper, so all of the same rules for the Sapper /routes directory still apply.

Instead of having to deal with dynamically named [slug].svelte files, mdsvex will take any files with a given extension and create Svelte components. Because these files live within the /routes directory Sapper will see them as pages and create routes for them.

!chart that shows blog/[slug].md - svelte.preprocess([ mdsvex() ]) - blog/[slug].svelte - npm run sapper export - blog/[slug].html](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u11gr370ryjegmejf6ax.png)

Under the hood, mdsvex fetches data similarly to Sapper, but uses the markdown's frontmatter to create a data object and pass it into the component as props. This takes the place of manually running fetch inside of the preload function. mdsvex will parse markdown into HTML, and can be given a Svelte layout component that will function similar to a Sapper _layout. Unlike a _layout, an mdsvex layout will be passed the $$props object.

Once these Svelte pages are created, the same flow for Sapper applies. In order for mdsvex to work with Sapper, all scripts need to be run with the --ext flag. This flag will allow Sapper to treat non .svelte files as routes and pick them up during the sapper export process. This is an important distinction — instead of relying on Sapper to crawl and generate each page, mdsvex will always create a Svelte file and corresponding route. Another important caveat here is that mdsvex-generated components will not run a preload function. These genreated components are regular Svelte components and don't work the same as Sapper page routes.

Shortcomings

Locking in to a workflow usually comes with a series of tradeoffs. By far the largest benefit of using mdsvex is the ability to put components directly into markdown files. I was able to write over a dozen posts this way before running into any complications. mdsvex is great at taking data from one .md file and transforming it into one .svelte file, but what if data needs to come from two sources?

My real world example of this popped up when I was adding the post-as-a-series feature to my blog. Each series would have a .json file containing a name and short description. Each post in that series contains a frontmatter series field. The posts' series field would need to correspond to a series name in order to link to extra data. This would function similar to a primary key and foreign key database relationship.

One way to link between this data would be to do the work in the node code that runs to generated each post.json file.

A different way to do this would be to run fetch() against multiple endpoints and return one final data object to the component.

Because I'm set on using components in my markdown, I have to use mdsvex. It works a little differently as it's data sources are one-in, one-out. Getting extra data from the blog/series.json route would need to be done inside of an onMount() callback. This would happen moments after a user loads the page and wouldn't happen during server side prerendering at all. This would trigger a flash of content loading, which I really want to avoid. "Cumulative Layout Shift," or "CLS" is one of Google's new Web Vitals, so this would hurt my Lighthouse scores and SEO page rankings.

Fetching data in other places

The other option is to run fetch() from a Sapper _layout file that wraps each page, but this presents an interesting problem. Because of the way that Svelte "surgically updates the DOM," the _layout.svelte file is actually mounted and rendered once and its <slot /> content is dynamically changed out when Sapper changes routes.

You can force a refetch of a data here using a reactive statement and pass it down, but because of the way Svelte's lifecycle works this will result in the same problem where data is loaded after initial render.

Combining both page composition methods

Let's review what we know at this point —

Sapper can use a dynamic component to take slug from a url, turn it into a file path, then fetch and preload data.
fs can make a list of files, then sapper export can crawl it to produce HTML pages.
mdsvex will generate a component from any file in a directory, even if the routes are not crawled by Sapper.
In order to get data at the right time, it needs to be fetched from the preload method of a page.
Anything done in a preload() from a route can be server rendered by sapper export.

So what would an ideal data flow look like?

A browser (or the Sapper crawl process) would visit a url and load a dynamic [slug].svelte route. This route would then be able to call a preload function and fetch any json data, as well as find the .md content that's been transformed by mdsvex.

Getting data

This is pretty much the default Sapper workflow, but we need a way to loop in components generated by mdsvex without letting it take over as the de facto route generator. There are three important features that can work together to do this —

Sapper files and directories with a leading underscore do not create routes.
mdsvex can import { metadata } from any file's frontmatter, but it also exports the generated default transformed page body.
mdsvex will generate these components even if a route is not created.

If a .md file lives directly inside routes/blog, mdsvex is going to turn it into a page and Sapper will load it for a given url instead of the generic [slug].svelte. The first thing to do is avoid this by moving all of the posts into a _content directory.

└─ blog/
  ├─ _content/
  │ ├─ post1/
  │ │ └─ index.md
  │ └─ post2/
  │ └─ index.md
  ├─ [slug].svelte
  └─ _series.json

The next step is to manually find these files from [slug].svelte's preload function. For this we need to add the @rollup/plugin-dynamic-import-vars package so we can use the slug to find and load the component that mdsvex generates. import statements won't usually work with dynamic template strings, but @rollup/plugin-dynamic-import-vars will let us import from a file path that includes a slug variable.

With the plugin installed, [slug].svelte can load this file, get the default export containing the .md content and the metadata export containing the frontmatter, and still make a fetch() call to /series.json and sync up the data.

<script context='module'>
  export async function preload(page) {

    const { slug } = page.params

    const component = await import(`./_content/${slug}/index.md`)

    const series = await this.fetch(`/blog/series.json`)
      .then(response => response.json())
      .then(series => logicToLinkUpPostToSeries(...))
    )

    return {
      page: component.default,
      metadata: component.metadata,
      series: series
    }
  }
</script>

Since all of this happens within an asynchronous preload function the page will wait to render until the data is resolved and we can avoid components loading in after initial render.

Rendering the page

There are two things to be aware of for rendering this data.

First, is component.default. If you console.log() the import it will show different two ydrthings depending on where it is logged.

// console.log(component.default) from <script context='module'> tag
{ render: [Function: render], '$$render': [Function: $$render] }

// console.log(page) from regular <script> tag
class Post { constructor(options) }

What's going on here is best explained in the Routing section of the Sapper docs:

When a user first visits the application, they will be served a server-rendered version of the route in question, plus some JavaScript that 'hydrates' the page and initialises a client-side router. From that point forward, navigating to other pages is handled entirely on the client for a fast, app-like feel.

In short, this means that the Sapper server will render the component using the render() function to return stringified HTML. Then the Svelte client will hydrate that HTML by instantiating the class at run time in the browser. Instead of sorting this out manually, the entire component can be passed into a special <svelte:component /> tag that will automatically take care of running each at the appropriate time.

The second concern is getting data to the correct component. Since some of the work is done behind the scenes by compilers, we can't always imperatively pass props down from one component to its direct children. Svelte provides a way around this with the context API. Rather than having to send a prop directly down the chain from parent to child, context provides a way to skip links in the chain and get data from a parent to any deeply nested child.

<App>
  <_layout>
    <mdsvexLayout>
      <[slug].svelte>
        <svelte:component this={Page} />
      </[slug].svelte>
    </mdsvexLayout>
  </_layout>
</App>

After getting the series.json data inside of [slug].svelte we can call setContext to store data inside of a context object. Since the <Page /> component generated by mdsvex will be a child component we can call getContext and check if the current page has a value for series and the UI can act accordingly.

 // [slug].svelte
<script context='module'>
  export async function preload(page) {
    ...
  }
</script>

<script>
  export let page
  export let series
  import { setContext } from 'svelte'
  setContext('series', series)
</script>

<svelte:component this={page} />

// page.svelte
<script>
  import { getContext } from 'svelte'
  const series = getContext('series')
<script/>

{#if series}  
  ...
{/if}

The final data flow works like this.

My `sapper-mdsvex-starter`

If this sounds cool or useful to you (and I hope it does!), I've put together a starter template repo that can be used to get a blog with this data flow up and running.

This data flow is weird. I couldn't find anything else online using a similar set up, or even a different tool chain to solve the same problem. This was able to solve my use case, but if there's a better way or just any feedback, feel free to let me know in the GitHub issues, on Twitter, or on the Svelte discord where I'm @ryfill.

Special thanks

Huge thank you to everyone in the Svelte discord for helping me rubber duck through this code, especially Jacob Babich. Also thank you to kev and pngwn for fact checking this post.

Choosing Theme Colors

ryanfiller — Thu, 25 Feb 2021 00:00:00 +0000

Choosing a color palette for a website is hard. Its even more complicated when trying to choose colors that will work with both a dark-on-light and light-on-dark theme. I recently re-themed my site and here are some things I learned along the way.

Choosing a color palette

Picking a color palette is something I have always struggled with, even as far back as college. There are plenty of tools online that use algorithms to help you choose colors, Coolors and Adobe Kuler are two favorites of my favorites.

A trick I learned in design school is to find an image with a vibe you like and sample colors from it as a starting point. Color theory is complicated, and I think it's okay to lean on experts who has already put in the work.

Good artists borrow, great artists steal.

~~Pablo Picasso~~ Ryan Filler

(Really I just wanted to make this joke, but the actual history of this quote was too ironic not to also share.)

Copyright law seems kind of fuzzy on if it's legal to lift a color palette from an established brand. For instance, I wouldn't recommend just copying, say, Google's red, yellow, green, and blue. Photographs, advertisements, fine art, comics, even film and video game stills, though, are fair game. colorpalette.cinema is a great Instagram account that posts color pallets made from scenes of popular movies.

The color palette for my 2020 re-theme was built by selecting colors from Starwatcher II, an illustration by Jean "Moebius" Giraud.

[[clearfix]]

Another pro-tip I learned in design college was to never use straight #000000 black or #ffffff white in a design. A design, even in print, will look much more intentional with a slightly desaturated black and a slightly temperature-shifted white instead of using the default colors. I try to keep this in mind when sampling colors from images and try to instead grab any dark color to stand in for "black" on my site. In fact, the color I chose for "black," #080025, is actually a very deep purple and "white," #fefdf2, is a very pale yellow.

Keeping accessibility in mind

One of the hardest parts about choosing colors for the web is finding the right balance between what looks good and what is high contrast enough for all users. I've built a tool to help with this (learn how I built it in this post), but finding a combination that works can still be hard work.

Something that worked out well for me is to focus on making sure the first two rows and first two columns of this chart are all passing scores. In most scenarios, text will either appear as black or white on a colored background, or as a color on a black or white background. If there are other specific color combinations you know you want to use, make sure they also pass the WCAG color contrast ratio.

Naming colors

In modern web development, you're probably storing these color values in some kind of variable. I was a user of SCSS variables for a long time, but I've switched over to using native CSS custom properties.

Naming these variables can be challenging because you want to pick a name that's meaningful, unique, and searchable. I'm a fan of prefixing every variable with color- to help my text editor give me a tab completion list when I start typing the word color.

For more complex color palettes I like to name my colors with the Crayola naming convention so that each variant of, say "blue" has a unique name. These name variations can be tricky to choose out on your own, so I like to use this site to generate them. My friend Josh wrote an article that goes more in depth on this strategy.

My color list is pretty simple so I named each color with a dark and light variant and stored them as CSS variables on the :root element.

:root {
  --colorBlack: #080025;
  --colorWhite: #fefdf2;
  --colorPurpleLight: #a176b6;
  --colorPurpleDark: #5651a7;
  --colorBlueLight: #4f81c0;
  --colorBlueDark: #155f91;
  --colorOrangeLight: #f16a1f;
  --colorOrangeDark: #ac284f;
  --colorGrayLight: #5e828f;
  --colorGrayDark: #4e6773;
}

Narrowing down a theme

I think there are six minimum colors required for any website color palette —

text - the main text color of the page
background - the main background color of the page
primary - a brand's primary color
highlight - a standout color, used to highlight buttons or other calls-to-action
active - another standout color, using to indicate a hover state or focused element
disabled - a muted color to show an element cannot be interacted with

That's not to say those are the only colors, but I personally think restraint is key to building consistent designs. Many design systems will use dark and light variations of each color for variety and increase the amount of accessible color combinations. I wanted my color palette to be sparse yet flexible and only have two versions of each color.

To set the theme colors I created a second set of variables. Each of these new variables describes how the color would be used and has one of the original named colors assigned to it.

:root {
  --colorText: var(--colorBlack);
  --colorBackground: var(--colorWhite);
  --colorPrimary: var(--colorPurpleDark);
  --colorHighlight: var(--colorBlueDark);
  --colorActive: var(--colorOrangeLight);
  --colorDisabled: var(--colorGrayLight);
}

Converting a palette to Dark Mode

I kept the same six utility colors from the default light mode theme, but reassigned new values for dark mode.

The closest color I have to an official "brand color" is #5651a7. This is the color I use for my page banners, and for the social media image that is generated for each post so for branding reasons I kept it as my primary color.

In addition to switching the text and background colors, I also picked brighter highlight and active colors that would stand out better on a dark background. I swapped disabled for the darker gray variant since light text would be appearing on it and I wanted to ensure it was still easy to read.

@media (prefers-color-scheme: dark) {
  :root {
    --colorText: var(--colorWhite);
    --colorBackground: var(--colorBlack);
    --colorPrimary: var(--colorPurpleDark);
    --colorHighlight: var(--colorOrangeDark);
    --colorActive: var(--colorBlueLight);
    --colorDisabled: var(--colorGrayDark);
  }
}

I’ll cover this much more in part three, but it’s worth noting that media queries don’t increase specificity. To make sure these variables are overwritten you’ll want to put the prefers-color-scheme: dark rules lower in the cascade.

Other considerations for Dark Mode

The first instinct to convert a theme to dark mode is to switch the foreground and background colors. This will get a design pretty far, but there's more to consider than only these two colors. When I started my site over in 2020 with the default Gatsby theme it came with some nice default colors. Beyond black and white there was also brand purple and several gray variants. When switching to a dark-background theme, some of the darker gray text is unreadable, and vice-versa with light grays on a light background.

This awesome article by Adhuhamism on CSS-Tricks talks about other things to consider beyond just colors — like modifying the contrast ratio of images and making modifications to text weights and other subtle UI elements like borders and shadows.

A Short History of Interface Colors

ryanfiller — Mon, 01 Feb 2021 01:23:54 +0000

In the last year or so, adding a dark mode toggle to websites is a trend that has exploded for personal blogs and big brands. Thanks to some browser features and system APIs dark mode has become easier than ever to implement. I recently added this feature to my own site, and here are some things I learned along the way.

What even is Dark Mode?

"Dark mode" refers to a light-on-dark color scheme, or one where the background is a dark color with light text and graphics. This aesthetic has always been popular for applications like terminals and code editors, but has been making a comeback in more mainstream user interface design.

Where did Dark Mode come from?

If you look back on the history of computer interfaces, light text on a dark background is originally how computer interfaces initially appeared. This had to do with the physical hardware limitations of computer monitors — cathode-ray tube displays were black in the off position and would use beams of colored RGB light to "paint" text and graphics onto a screen. Some of the earliest computer displays used only a single color to paint vector graphics on to primitive screens.

As computers became more powerful and interfaces more sophisticated it was easier to fill entire screens with light. The first consumer graphical user interface (or GUI) was introduced by Xerox in 1973 and light themed interfaces have been the norm in home computing ever since. My best guess for why this trend is that with the rise of home desktop publishing users were more comfortable working with an interface that resembled paper.

By the early 90s, computers were becoming a fixture in most homes almost all GUIs were in full color. Many of these operating systems allowed users to pick from predefined lists of themes to recolor their interfaces, some of which were light-on-dark styles and some of which were dark-on-light styles.

Modern Dark Mode

What we think of as "dark mode" today really took off around the end of 2019. Apple introduced a system-wide preference for dark mode on desktops with their Mojave OS and for handheld devices with iOS 13, and Android did the same with Android 10.

It has always been possible to create a custom theme implementation for a website or application using some combination of CSS and JavaScript. A big change to web development came in 2020 when all major web browsers began supporting the prefers-color-scheme media query. This is a flag that is passed from a user's operating system level preference into the browser, and CSS could check to see what that preference was and make decisions based on it. Along with the addition of CSS variables, web developers were granted a powerful set of tools to dynamically change styles based on these user preferences.

Why should a site support Dark Mode?

For Eye Health

Although the facts seem to be debated, many users claim that using a dark theme reduces strain on their eyes. There does seem to be evidence that this is contextually true — light themes make sense for bright environments and dark themes for dark environments. There is also evidence to suggest that when using screens immediately before bedtime, a dark theme will reduce the amount of blue light the eyes take in and make it easier to fall asleep.

For Less Energy Consumption

Less debatable than the topic of eye strain is the fact that with certain screen types using a dark theme can conserve energy. This is because not having to light up background pixels with white light can lead to less battery usage. As more and more devices are built with OLED screens this can add up to huge savings over time and at scale. Users can consume less electricity, charge their phones less, replace their batteries with less frequency, and overall have a positive effect on the environment.

Just Because

The most important, in my opinion, is to honor a user's choice. In fact, that ethos is baked right into the design of CSS.

The user (or reader) of the web site can choose to override styles in many browsers using a custom user stylesheet designed to tailor the experience to the user's wishes.

While there may not be science to confirm that it is actually better for your eyes, many people prefer using sites with light text on a dark backgrounds. Letting users customize their experience is core to the web platform, and if a site can let them choose their color theme without having to write a custom style sheet, it should.

Dark Mode isn't for Everybody

Dark mode is certainly popular right now, but there are still a large number of people who prefer to read dark text on a light background — and that's okay! There are many medical reasons why a person might want to stick with what has been a more traditional color scheme.

With the tools currently available for the web platform it's certainly possible to let users make choices about how they want to view content.

Automatic Social Share Images

ryanfiller — Mon, 30 Nov 2020 14:13:05 +0000

Every time I write a new blog post, I share it to Twitter. And, if I'm being honest, these tweets usually look pretty boring. Here's the tweet for last month's blog post.

Happy Halloween! Here's a sPoOkY new blog post about.... transforming markdown with @unifiedjs tools? I don't know, its not really Halloween themed but hopefully its worth a read anyways! https://t.co/a3rgZf6MAl
— Ryan Filler (@ryanfiller_) October 31, 2020

When I built my post template I added the most basic <meta> tags like author, description, and keywords. Sites like Twitter are smart enough to use those tags and generate a basic preview card, but there are tools to augment the look of this card. The two most popular are Twitter's Card Components and Facebook's Open Graph Image. Hooking into these protocols is as easy as adding some extra <meta> tags to the page's <head>, but it's important to know the data type each tag is expecting.

Which Tags to Use?

Most of the data I needed was already on each page, but to make sure it was seen by each crawler I needed to duplicate it into some platform-specific meta tags. A few have special values that need to be filled in with keywords, such as which card style to use, but most can be reused from regular SEO tags.

  <title>...</title>
  <meta name='author' content='...' >
  <meta name='description' content='...' >
  <meta name='keywords' content='...' >

  <meta name='twitter:card' content='summary_large_image' />  
  <meta name='twitter:site' content='...' />
  <meta name='twitter:creator' content='...' />
  <meta name='twitter:url' content='...' />
  <meta name='twitter:title' content='...' />
  <meta name='twitter:description' content='...' />
  <meta name='twitter:image' content='...' />
  <meta name='twitter:image:alt' content='...' />

  <meta property='og:type' content='article' />
  <meta property='og:locale' content='en_US' />
  <meta property='og:image:height' content='630' />
  <meta property='og:image:width' content='1200' />
  <meta property='og:site_name' content='...' />
  <meta property='og:title' content='...' />
  <meta property='og:description' content='...' />
  <meta property='og:url' content='...' />
  <meta property='og:image' content='...' />
  <meta property='og:og:image:alt' content='...' />

Both Twitter and Open Graph have pretty good developer tools to test out their crawlers and debug any missing info. They also show a preview of how the final render will look so it’s a good opportunity to make sure the right data made it into the right tag.

Both services offer multiple card styles — small images, large images, videos, galleries — but I wanted to attach a simple image with my posts. This meant that for Twitter I needed name='twitter:card' content='summary_large_image' style, and property='og:type' content='article' for Open Graph. I put together a quick design for an image with baked-in text that I could use whenever I shared any of my posts.

Dynamically Constructing a Preview Image

Rather than making one-off images in Photoshop for each post like I have done in the past, I decided to create each image dynamically in HTML. To do this, I built a basic page and styled it with CSS to look like the card image I had designed.

<div id='wrapper'>
  <div id='preview'>
    <main class='content'>
      <h1>{TITLE}</h1>
      <ul class='tag-list'>
        <li>{CATEGORY}</li>
        <li>{TAG}</li>
        <li>{TAG}</li>
      </ul>
      <span class='url'>{URL}</span>
      <span class='author'>{AUTHOR}</span>
      <p class='attribution'>
        <span>Image Credit:</span>
        <span>{IMAGE CREDIT}</span>
      </p>
    </main>
    <img src='{IMAGE SRC}' />
  </div>
</div>

I used Svelte to build this template out, but all the tools used here are actually native browser APIs. Most of what I did can be accomplished using only HTML, CSS, and JavaScript DOM manipulation.

This page will live at the /generate-image route on my website.

Next, JavaScript needs to fill those tags in with dynamic data.

Passing Data with URL Search Parameters

Because I plan on making this page available after the site has been statically rendered, I need a way to pass around variable data without using POST or PUT requests. The best way to do this is to use the search portion of a URL. Wikipedia has a really good diagram of the anatomy or an entire URL, but in short search, or query, parameters are the section at the end of a URL following the ? character. These parameters are a special part of the URL that will not change which route the browser navigates to, and as many as needed can be chained together using the ?key1=value1&key2=value2 syntax.

One thing that search params don't do well is handle special characters. Since the & character denotes a new piece of data trying to include an ampersand in either the key or value string will be problematic. Luckily, JavaScript provides several useful built-ins for dealing with this scenario.

`encodeURI()`

encodeURI (and it's reverse function decodeURI) can be used to transform an entire query string. This means that it will ignore special characters that are meaningful, such as the ?, &, and # so that it does not break the structure of the URL.

  abc 123 #&? ABC {}[]"

  abc%20123%20#&?%20ABC%20%7B%7D%5B%5D%22

Notice that space characters were replaced with %20 and other symbols like brackets are also encoded but #&? were left as is. If you know for a fact that your data won't contain any special characters this method is the easiest to use, but I personally found it caused more problems than it solved.

`encodeURIComponent()`

encodeURIComponent (and it's reverse function decodeURIComponent) can be used to encode each individual part of a query rather than the entire query string. This means that they will encode special characters that are part of the meaningful data for either the key or value of a query.

  abc 123 #&? ABC {}[]"

  abc%20123%20%23%26%3F%20ABC%20%7B%7D%5B%5D%22

Each section of a query can be encoded this way, but the URL will still need to be manually constructed with the & and = syntax in order for a browser to understand it correctly.

`URLSearchParams`

The most helpful JavaScript built-in I found is the URLSearchParams interface. Constructing new URLSearchParams() and passing an entire query string will build a JavaScript class that provides set(), get(), and other methods for working holistically with queries.

Because most of what I was doing for this project was going back and forth between strings and objects, I wrote two helper methods that used URLSearchParams.

function objectToParams(object) {
  const params = new URLSearchParams
  Object.entries(object).map(entry => {
    let [key, value] = entry
    params.set(key, value)
  })
  return params.toString()
}

function paramsToObject(paramString) {
  const params = new URLSearchParams(paramString)
  const object = {}
  for (const [key, value] of params.entries()) {
    object[key] = value
  }
  return object
}

  {
    title: 'post title',
    categories: ['array', 'of', 'categories'].join(','),
    tags: ['array', 'of', 'tags'].join(','),
    imageSrc: 'image source',
    imageCredit: 'attribution',
    url: 'post url'
  }

  title=post+title&categories=array%2Cof%2Ccategories&tags=array%2Cof%2Ctags&imageSrc=image+source&imageCredit=attribution&url=post+url

A downside to this tool is that unlike encodeURI and encodeURIComponent it is not supported in any version of Internet Explorer. URLSearchParams also doesn't prepend the final string with the ? character, so this will need to be added between the returned string and the main URL manually.

Replacing Data on the Page

As I mentioned, my page is built using a Svelte template, which provides an easy way of getting query data and loading it into a page's HTML. Even with no framework some combination of window.location.search, document.querySelector, and element.innerHTML should work for getting data from a URL and injecting it into the page.

Using a Serverless Function to Capture the Page

Now that a page exists and we can pass dynamic data to it, the next step is to create a way to turn the page into an image. To do this, I wrote a Netlify Function that would use Puppeteer to visit the page and take a screenshot of it. In a browser I could visit the URL of the Netlify function and pass it a query to build the screenshot with the objectToParams function.

`${siteUrl}/.netlify/functions/generate-image?${imageParams}`

Netlify functions work by exporting a handler method which receives an event argument. event is an object that contains data about when and how the function was called, including the headers of the request and an object of queryStringParameters. The event.headers.host can be used to make sure the function is always called from the correct URL, even on preview deploys. We can also use the objectToParams helper from earlier to pass all the query parameters through to the screenshot template page.

One thing to note here is that testing this function locally using the Netlify CLI, it will run on http://localhost:8888. When the function is deployed, either to a preview or production version, it will run on https://. Puppeteer will require a full URL, including the protocol, so we can use an environment variable to make sure the function sees either http:// or https:// when needed.

exports.handler = async function(event) {
  const local = process.env.NODE_ENV === 'development'
  const url = local ? `http://${event.headers.host}` : `https://${event.headers.host}`
  const imageParams = objectToParams(event.queryStringParameters)
  const screenshot = await takeScreenshot(`${url}/generate-image?${imageParams}`)
}

takeScreenshot() will accept a url argument that contains the query parameters needed to construct the image and will open a headless version of a browser and return an encoded screenshot. The function is pretty straightforward — it will launch a browser, open a new page in that browser, resize the window, visit the given URL, take a screenshot, then return a base64 encoded version of the image.

const takeScreenshot = async function(url) {
  const browser = await chromium.puppeteer.launch({...})
  const page = await browser.newPage()
  await page.setViewport({ height: 630, width: 1200 })
  await page.goto(url)
  const buffer = await page.screenshot()
  await browser.close()
  return `data:image/png;base64,${buffer.toString('base64')}`
}

There are a couple nuances though. First, Netlify functions have limitations, including a 1024MB memory cap. If the function tries to install the full puppeteer-core package it will go over this memory limit and crash. Instead, the function needs to rely on a minimal version of puppeteer in the chrome-aws-lambda package. The second consideration is that since the function is now relying on a version of Chromium meant to run in a serverless context this function will not work when running it locally. There are several ways around this, but the one I had the most success with was to look at the local variable and point the browser.executablePath at the full install of Chrome on my computer. For this to work you need the full Chrome browser installed, and if you're not using a Mac the path will be different. When the function is not running locally it will use the default executablePath from the chrome-aws-lambda package.

const browser = await chromium.puppeteer.launch({
  executablePath: local 
    ? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
    : await chromium.executablePath,
  args: chromium.args,
  defaultViewport: chromium.defaultViewport,
  headless: chromium.headless,
})

Uploading the Screenshot to Cloudinary

Now that the function has a way to get a data version of a screenshot, it needs somewhere to put it. Rather than return an image directly to the browser, I decided to store these images on Cloudinary. Cloudinary is a great CDN, has a ton of extra functionality I could use in the future, and has a JavaScript API I can use in this serverless function.

The first thing to do was configure the cloudinary NPM package to work with my Cloudinary account. CLOUDINARY_KEY and CLOUDINARY_SECRET definitely should be kept as ENV variables and not shared, but I added my CLOUDINARY_CLOUD this way too for some extra security.

It is also important to use the v2 version of the cloudinary package to get the correct API interface.

const cloudinary = require('cloudinary').v2

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_CLOUD,
  api_key: process.env.CLOUDINARY_KEY,
  api_secret: process.env.CLOUDINARY_SECRET
})

The function needs to be able to know if this image already exists on Cloudinary. I don't want to overwrite existing images every time this function is loaded, and I also don't want to go through the process of starting up the screenshot tool if I won't need it. Since the queryStringParameters are passed to the function as an object, the title attribute for each post can be accessed and used as a unique identifier for each image.

exports.handler = async function(event) {
  const title = slugify(event.queryStringParameters.title)
  const existingImage = await getImage(title)

  if (existingImage) {
    return existingImage
  }

  const url = local ? `http://${event.headers.host}` : `https://${event.headers.host}`
  const imageParams = objectToParams(event.queryStringParameters)
  const screenshotBuffer = await takeScreenshot(`${url}/generate-image?${imageParams}`)
  const newImage = await putImage(title, screenshotBuffer)
}

Since I knew the structure for the final URL for each screenshot, I ran node-fetch against that URL. If it returned a 404 Not Found response I knew that the image didn't already exist and it was safe to run the screenshot function and start a new Cloudinary upload. If it did exist, I would return that URL in the handler method. Cloudinary does provide a version number in their URLs (the number string between /upload/ and the folder name), but this can be omitted from the URL and the image will still be found.

const getImage = async function(title) {
  const url = `https://res.cloudinary.com/${process.env.CLOUDINARY_CLOUD}/image/upload/social-images/${title}.png`
  return await fetch(url)
    .then(result => {
      if (result.status !== 404) {
        return url
      } else {
        return null
      }
    })
}

After the screenshot was generated, I passed it into yet another function to upload it to Cloudinary. cloudinary.uploader.upload requires two arguments — an encoded image and a configuration object. unique_filename: false is important because if Cloudinary appends generated numbers to each file to maintain uniqueness the getImage() function won't be able to properly find existing images with fetch.

const putImage = async function(title, buffer) {
  const cloudinaryOptions = {
    public_id: `social-images/${title}`,
    unique_filename: false
  }
  console.log(`uploading ${title} to cloudinary`)
  return await cloudinary.uploader.upload(image, cloudinaryOptions)
    .then(response => response.url)
}

If successful, cloudinary.uploader.upload will return the URL to which the image was uploaded. I should be able to assume the structure of this URL like I did in the getImage() function, but to be safe I grabbed it from the Cloudinary response and used it inside the final handler.

Forwarding to the Final URL in the Response

The last thing to do is make to sure the final Cloudinary URL makes it to the browser. To do this, I used a 308 Permanent Redirect in the response header returned from the function. This means that when a user visits the URL for the Netlify Function the process will run and automatically redirect them to either the existing or newly generated Cloudinary URL. The 308 redirect should also help SEO crawlers handle this link correctly.

const forwardResponse = imageUrl => {
  return {
    statusCode: 308, // Permanent Redirect
    headers: {
      'location': imageUrl
    },
    body: ''
  }
}

Because I was uploading each image with the same URL structure this meant that I could dynamically reconstruct it inside the <head> for each blog post.

socialImageUrl = `https://res.cloudinary.com/${process.env.CLOUDINARY_CLOUD}/image/upload/social-images/${slugify($$props.title)}.png`

<meta name='twitter:image' content={socialImageUrl} />
<meta property='og:image' content={socialImageUrl} />

Final Function

The final logic for the function without all of the abstracted helper methods included looked like this:

exports.handler = async function(event) {
  if (!event.queryStringParameters) {
    console.log(`no params given`)
    return
  }

  const title = slugify(event.queryStringParameters.title)
  console.log(`processing ${title}...`)

  const existingImage = await getImage(title)

  if (existingImage) {
    console.log(`yay, ${title} already existed`)
    return forwardResponse(existingImage)
  }

  console.log(`generating image for ${title}`)
  const url = local ? `http://${event.headers.host}` : `https://${event.headers.host}`
  const imageParams = objectToParams(event.queryStringParameters)
  const screenshot = await takeScreenshot(`${url}/generate-image?${imageParams}`)
  const newImage = await putImage(title, screenshot)
  console.log(`done with ${title}`)
  return forwardResponse(newImage)
}

To see the full function, with everything included, check it out on GitHub.

The final image generated with the metadata from this post should look something like this.

One added benefit is that even though the two protocols used here were created specifically by Twitter and Facebook, many other web-based services now tap into these tags and create custom preview cards as well.

Shoutouts

I looked at a lot of examples to pull all of this together, so I wanted to thank a few people who shared content examples or were nice enough to talk to me about issues I ran into.

Ire Aderinokun for writing an awesome Bits of Code article about how to take a serverless screenshot
Wes Bos for code examples on how to use local Chrome and talking through image caching with me on Twitter
Chris Biscardi for this free Egghead series on generating images, using the Cloudinary API, and using redirects and giving me advice on how to point to the correct domain for my functions
Darrik Moberg and Jason Lengstorf for code examples and helping me debug on Discord

Transforming Markdown with Remark & Rehype

ryanfiller — Sat, 31 Oct 2020 16:09:34 +0000

My blog, like a lot of JAMstack content, is written in Markdown. I've written about how I've used MDX as a parser to give my Markdown extra power. I've also written a bit about some of the shortcomings I've had trying to replicate the same MDX functionality in MDsveX. One thing that MDX and MDsveX have in common is that they are both built on top of the remark and rehype packages from the unified ecosystem. Both parsers use these dependencies and they each have the ability to use any plugin that would work with the raw remark or rehype processors. To make my workflow less coupled to a specific technology, I decided to move the transformations up a level of abstraction. Instead of using MDX I wrote a series of plugins to transform my markdown.

How do Markdown Parsers Work?

Markdown parsers work by taking a file, running it through a series of transformers, and then producing HTML for the browser. The transformation steps involve turning documents into a common shape that different tools can read and interpret, called an abstract syntax tree. Put shortly —

Abstract syntax trees are data structures widely used in compilers to represent the structure of program code. An AST is usually the result of the syntax analysis phase of a compiler. It often serves as an intermediate representation of the program through several stages that the compiler requires, and has a strong impact on the final output of the compiler.

Wikipedia

// Markdown
# Luminous beings are we, not this crude matter.

// AST
{
  type: "heading",
  depth: 1,
  children: [
    {
      type: "text",
      value: "Luminous beings are we, not this crude matter."
    }
  ]
}

// HTML
<h1>Luminous beings are we, not this crude matter.</h1>

It isn't necessary to understand the computer science behind an abstract syntax tree (AST) to work with plugins. All you need to know is that an AST is an intermediary step that a compiler takes between taking in a .md and outputting an .html file. To paraphrase heavily from the mdsvex docs, the source file is first parsed into a Markdown AST (MDAST), where remark plugins run. Then the data is converted into an HTML AST (HAST), where rehype plugins run. Finally the data is converted (stringified) into valid markup for the browser.

What is Remark?

remark is a unified processor to parse and serialize Markdown.: API by unified; Parses Markdown to a syntax tree with remark-parse; mdast syntax tree; Plugins transform the tree; Serializes syntax trees to Markdown with remark-stringify

What is Rehype?

rehype is a unified processor to parse and serialize HTML: API by unified; Parses HTML to the tree with rehype-parse; hast syntax tree; Plugins transform the tree; Serializes the tree to HTML with rehype-stringify

When to use Each?

I couldn’t find a hard and fast rule for when to use remark and when to use rehype. There are ways to get the same end result with either tool. My rule of thumb for this project had to do with the original format of the content I was manipulating. If the plugin would run on markdown syntax I used remark. If the plugin was running on any HTML used directly in the document, I used rehype. In either scenario the transformation is done by manipulating values in the syntax tree, so the process isn’t too different.

Manipulating the AST

This CSS-Tricks article by Jason Lengstorf goes into deep detail about how ASTs work and best practices for editing them. Here are a few key points I wanted to highlight.

ASTs are the best way to make programmatic changes to HTML. HTML is hard (maybe even impossible) to parse with RegEx, so trying to change it without using an AST is often error prone.
Contrary to usual best practices, ASTs should be treated as mutable. Because AST documents can be very large, making copies of the data and making changes to those copies can be detrimental to performance. Manipulations are best made directly to the original AST.
AST transformations work recursively, so if new nodes are added the transformer will find them and try to transform them too. This is important to be aware of to avoid accidental infinitely deep loops.

Basic Plugin Structure

A plugin works by creating a JavaScript function that returns a transformer method. That transformer will be run on each node that is found by the unist-util-visit package's visit method. The plugin will be called by the unified process and will be passed the AST tree. There are many ways to directly mutate the tree, but I found the easiest was to use Object.assign to overwrite the existing tree nodes with new values.

import visit from 'unist-util-visit'

function transformer(ast) {
  visit(ast, 'TYPE', visitor)

  function visitor(node) {
    newNode = 'do work here'
    return Object.assign(node, newNode)
  }
}

function plugin() {
  return transformer
}

export default plugin

The second argument for the visit method is a node type that the transformation will be applied to. The unist ecosystem comes with a predefined list of literal types, but plugins can define their own custom ones. I found that copy / pasting HTML into this AST Explorer tool was a super helpful way to find the exact string that each node type matched against. For HTML elements that don't have an explicit type, visit can find raw nodes and then match them with RegEx. If, like me, you're not that great at RegEx, I found a RegeEx testing tool to be invaluable while I was working.

Reworking Attributes on an Existing Element

It is a controversial opinion, but I prefer to use target='_blank' on links external to my site. I cite a lot of sources via links, and I don't want readers to lose their place on my page after clicking on an external resource. There are two things this plugin needs to do — apply the correct target attribute, but more importantly it needs to add some other attributes to fix a security concern. One nice thing about adding these with a plugin is that I do not have to write these extra attributes manually on every link. Also if I ever change my opinion on where links should open I can remove them all at once by editing the plugin.

The original AST tree for a link node looks roughly like this:

{
  type: 'link',
  title: 'string,
  url: 'string',
  children: [
    {
      type: 'text',
      value: 'string',
    }
  ],
}

In short, this plugin visits link nodes and uses RegEx to determine if they linked to external sites, then if it does, assign some extra hProperties to the node. Nodes of different types come with different default data values (for instance, a link node has a data.url value), and hProperties are sort of a catchall for all other attributes.

function transformer(ast) {
  visit(ast, 'link', visitor)

  function visitor(node) {
    const data = node.data || (node.data = {})
    const props = data.hProperties || (data.hProperties = {})
    const url = node.url


    if(url.includes(siteUrl)) {
      return
    } else {
      props.target = '_blank'
      props.rel = 'noopener'
      return
    }
  }
}

function links() {
  return transformer
}

export default links

The transformer function will look at all links, determine if their data.url contains the url of the current site, and assign data.hProperties of target = '_blank' and rel = 'noopener' to links that do not. Again, these values need to mutate the tree directly, so that's why the new values are set on the original node rather than creating a copy.

// Markdown
[an intneral link](https://www.ryanfiller.com/about)
[an external link](https://developer.mozilla.org)

// HTML
<a href="https://www.ryanfiller.com/about">
  an intneral link
</a>
<a target="_blank" rel="noopener" href="https://developer.mozilla.org">
  an external link
</a>

See the full code for the plugin on GitHub.

Inserting New Child Elements

This plugin reads any heading element and automatically converts it to a linkable hash. It also creates an <a> tag that a user can click to easily copy the hash out of the url bar.

The original AST tree for a heading node looks roughly like this:

{
  type: 'heading',
  depth: number,
  children: [
    {
      type: 'text',
      value: 'string'
    }
  ]
}

This plugin needs to take the original text children of the element and convert it into a url hash. Then it replaces the original child elements with a new anchor tag that contains both the original text and the hashed text. To handle some edge cases this plugin uses another plugin, remark-stringify, to convert the entire element into one string. This will catch scenarios where headings contain bold or italic text without accidentally stringifying a <strong> or <em> tag.

function transformer(ast) {
  visit(ast, 'heading', visitor)

  function visitor(node) {
    const data = node.data || (node.data = {})
    const props = data.hProperties || (data.hProperties = {})
    const slugId = slugify(toString(node))

    data.id = slugId
    props.id = slugId

    const originalChildren = [...node.children]

    node.children = [{
      type: 'link',
      url: `#${slugId}`,
      children: originalChildren
    }]
  }
}

function headings() {
  return transformer
}

export default headings

In order to wrap the original text element, the ...spread operator can be used to create a new array filled with the data from the original heading. Then a new children array that contains a single link type node can be assigned to the heading. The new link node will have all the elements of the original heading.

// Markdown
### It was a dark and stormy night.

// HTML
<h3 id="it-was-a-dark-and-stormy-night">
  <a href="#it-was-a-dark-and-stormy-night">
    It was a dark and stormy night.
  </a>
</h3>

See the full code for the plugin on GitHub.

Wrapping an Element with a New Element

In a previous post I explained how I was using Netlify LFS to host and resize images using url parameters. This is something I wanted to automate using remark. I also wanted to augment the native Markdown image syntax using the remark-attr plugin to pass a data-caption attribute. If this attribute exists I want to take that element and wrap it in a <figure> tag with the caption inside of a <figcaption>.

The original AST tree for a image node looks roughly like this:

{
  type: 'image',
  url: 'string',
  alt: 'string',
  data: {
    hProperties: {
      data-caption: 'string'
    }
  }
}

The most important part of this transformation is to mutate the children array in a way that doesn't cause an infinite loop. Since the visit function will work recursively, if the number of children changes then the new nodes will also be visited. If a transformer creates a node that can itself be transformed, this will go on forever and crash the build process.

function transformer(ast) {
  visit(ast, 'image', visitor)

  function visitor(node) {
    const data = node.data || (node.data = {})
    const props = data.hProperties || (data.hProperties = {})
    let src = node.url
    const alt = node.alt
    const caption = props['data-caption']

    const skipSrcSet = ['.gif', '.svg'].some(ext => src.includes(ext))

    if (!skipSrcSet) {
      src = `srcset="${src}?nf_resize=fit&w=500 500w, ${src}?nf_resize=fit&w=800 800w"
        sizes="100vw"
        src="${src}?nf_resize=fit&w=1000"
      `
    }

    let newNode = null
    if (caption) {
      newNode = {
        type: 'html',
        value: `<figure>
          <img src=${src} alt="${alt}" />
          <figcaption>${caption}</figcaption>
        </figure>`
      }
    } else {
      newNode = {
        type: 'html',
        value: `<img src=${src} alt="${alt}" />`
      }
    }

    Object.assign(node, newNode)
  }
}

function images() {
  return transformer
}

export default images

Since Netlify Large media will only offer transforms for certain types of images I created an array of extensions that I wanted my function to ignore. If the file type wasn't a .gif or a .svg, I would apply a series of query parameters to get back resized images. To decide between creating a <figure> or an <img> an if() statement checks whether the node contains hProperties['data-caption]. In either scenario, a new node is created with type html and a value is passed with a string literal for what will be rendered in the DOM.

In order to keep this plugin from infinitely creating and visiting new image type nodes is to used Object.assign to overwrite the current node and never create new ones. By doing this we preserve the original index in the AST tree and the transformer will understand that it's already seen this node and not visit it again.

// Markdown
![alt text](/images/picture.jpg)
![alt text](/images/picture.jpg){data-caption='a caption'}

// HTML
<img
  alt="alt text"
  src="/images/picture.jpg?nf_resize=fit&w=1000"
  srcset="/images/picture.jpg?nf_resize=fit&w=500 500w,
    /images/picture.jpg?nf_resize=fit&w=800 800w"
  sizes="100vw"
/>
<figure>
  <img
    alt="alt text"
    src="/images/picture.jpg?nf_resize=fit&w=1000"
    srcset="/images/picture.jpg?nf_resize=fit&w=500 500w,
      /images/picture.jpg?nf_resize=fit&w=800 800w"
    sizes="100vw"
  />
  <figcaption>
    a caption
  </figcaption>
</figure>

See the full code for the plugin on GitHub.

Hijacking Existing Syntax to Create New Markup

Markdown supports shorthand for a limited number of elements, and to the best of my knowledge no more are being added. For elements with no shorthand you can always use HTML directly in a .md file. For some elements this can be very verbose. Wouldn't it be nice to steal some of the concise syntax for, say, an image but use it instead for a video file?

![a video]('./video.mp4)

Since linking to a video with the image syntax doesn't create a working element, remark can change the markup to work for video. Be very careful with this idea and make sure you're not overwriting any valid usecases. I think I'm fine in this scenario since pointing an <img> tag to a video file will always result in a broken image. Inside the image transformer, the function can check the file type of the src attribute and return a new Object.assign with completely different markup depending on the extension.

function transformer(ast) {
  visit(ast, 'image', visitor)

  function visitor(node) {
    const data = node.data || (node.data = {})
    let src = node.url
    const alt = node.alt

    // escape hatch into video component
    if(node.url.includes('.mp4')) {
      const video = {
        type: 'html',
        value: `
        <video title="${alt}" controls loop autoplay>
          <source src="${src}" type="video/mp4" muted />
          Sorry, your browser doesn't support embedded videos.
          <track kind="descriptions" label="${alt}" />
        </video>`
      }
      return Object.assign(node, video)
    }

    // else, original image transformation
    ...
  }
}

function images() {
  return transformer
}

export default images

// Markdown
![alt text](/videos/video.mp4)

// HTML
<video title="alt text" controls loop autoplay>
  <source src="/videos/video.mp4" type="video/mp4" muted />
  Sorry, your browser doesn't support embedded videos.
  <track kind="descriptions" label="alt text" />
</video>

See the full code for the plugin on GitHub.

Transforming HTML

So far all of the examples I’ve covered have taken in markdown content and looked at the MDAST tree to make changes. rehype plugins will look at HTML content in the HAST tree and work almost exactly the same as remark MDAST plugins. Nodes can have different types than the MDAST tree, but all of the same rules apply.

Even though rendering an <iframe> in Markdown requires using the full HTML syntax, I still want to be as terse as possible and add extra values like loading='lazy' programmatically. Also, until the CSS aspect-ratio property officially lands, I still need to wrap <iframes> in a <div> and use the padded box trick to maintain a responsive aspect ratio.

Like remark, rehype only recognizes a handful of default types. Also like remark, custom types can be created, but I found it was still easier to visit the default HTML raw nodes and use RegEx to filter out the ones I wanted.

The RegEx matcher I used looks like this:

new RegExp(/<iframe(.*)<\/iframe>/g)

And the matching AST node looks roughly like this:

{
  type: 'raw',
  value: '<iframe>...</iframe>'
}

A downside to working directly with the raw node type is there is no concept similar to hProperties. The only information the node has is its string literal value, so any HTML attributes will need to be filtered out of that string with RegEx. I made a helper function that would take a source string and attribute name and fish them out.

function transformer(tree) {
  visit(tree, 'raw', visitor)
  function visitor(node) {
    const iframeRegex = new RegExp(/<iframe(.*)<\/iframe>/g)

    if (node.value && node.value.match(iframeRegex)) {
      const value = node.value.match(iframeRegex)[0]
      const title = fishAttr(value, 'title')
      const src = fishAttr(value, 'src')
      const aspectRatio = fishAttr(value, 'data-aspect-ratio')

      const newValue = `<div class="embed" data-aspect-ratio="${aspectRatio}">
        <iframe src="${src}" title="${title}" loading="lazy"></iframe>
      </div>`

      node.value = node.value.replace(iframeRegex, newValue)
    }
  }
}

function embed() {
  return transformer
}

export default embed

Another difference between rehype and remark is that only the node's value property matters, so we can actually use String.replace() instead of Object.assign. This does as little modification as possible to the HAST tree and can prevent unintentionally assigning over important values, like whitespace, that the RegEx matcher may have accidentally grabbed.

// Markdown
<iframe
  src='https://ryan-responsive-iframe.netlify.com/'
  title='wide screen'
  data-aspect-ratio="16/9"
></iframe>

// HTML
<div class="embed" data-aspect-ratio="16/9">
  <iframe
    src="https://ryan-responsive-iframe.netlify.com/"
    title="wide screen"
    loading="lazy"
  ></iframe>
</div>

See the full code for the plugin on GitHub.

Doing Work Asynchronously

Since these plugins are just node functions, they have the ability to fetch out to other sources and get dynamic data at build time. An issue with this workflow is that the visit method provided by unist-util-visit is not an async function and cannot be used with the await keyword.

For this particular plugin, I wanted to take the Twitter provided HTML embed code, strip off the <script> tag that would load the JavaScript from Twitter, and instead use rehype to format the HTML in a way I could style myself. I used the same strategy as matching <iframe> elements, but looked for <blockquote>s that had a class of "twitter-tweet".

new RegExp(/<blockquote class="twitter-tweet">(.*)<\/blockquote>/)

And the matching AST node looks roughly like this:

{
  type: 'raw',
  value: '<blockquote class="twitter-tweet">...</iframe>'
}

To build my own Twitter component, I needed the url of a user's avatar from the Twitter website. If fetch visits Twitter's regular homepage and cannot load client side JavaScript Libraries it will triggers the "you need to load React" warning screen. The only way (that I could think of, anyways) to get a parsable page that contains an avatar url is to fetch against mobile.twitter.com.

Transforming the HTML from the Twitter blockquote works almost exactly the same as the embed plugin. I used my fishAttr function to get values from the original markup and then plug them into a string literal template. The difference is that instead of using String.replace() to create new markup, I created a render() function that could be called inside of a Promise and passed the returned url for the avatar.

const twitter = () => async (tree) => {
  const createTweet = node => {
    const tweetRegex = new RegExp(/<blockquote class="twitter-tweet">(.*)<\/blockquote>/)

    if (node.value && node.value.match(tweetRegex)) {
      const value = node.value.match(tweetRegex)[0]

      const render = avatarUrl => (`
        <div class="twitter-tweet">
          // new markup here
        </div>
      `)
    }
  }

  visit(tree, 'raw', createTweet)
}

export default twitter

As I previously mentioned, visit can’t be used directly with async/await. Instead, the createTweet method passed to visit needs to await the result of the fetch Promise. This can be done by storing that Promise inside of a variable and pushing it to an array of pending Promises. Then, using Promise.all, we can make sure everything pushed to that array is done before the final return from the plugin happens.

const twitter = () => async (tree) => {

  const promises = []

  const createTweet = node => {
    const tweetRegex = new RegExp(/<blockquote class="twitter-tweet">(.*)<\/blockquote>/)

    if (node.value && node.value.match(tweetRegex)) {
      const value = node.value.match(tweetRegex)[0]
      const user = value.match(/&mdash(.*)\)/)[0]
      const handle = user.match(/\((.*)\)/)[1]
      const name = user.match(/&mdash; (.*) \(/)[1]

      const render = avatarUrl => { ... }

      const promise = fetch(`https://mobile.twitter.com/${handle}`)
        .then(response => response.text())
        .then(html => {
          const imageUrlRegex = new RegExp(`<img alt="${name}" src="(.*)" \/>`)
          const imageUrlMatch = html.match(imageUrlRegex)
          return imageUrlMatch[1]
        })
        .then(avatarUrl => {
          const newNodeValue = render(avatarUrl)
          return node.value = node.value.replace(tweetRegex, newNodeValue)
        })
        .catch(() => {})

      promises.push(promise)
    }
  }

  visit(tree, 'raw', createTweet)
  await Promise.all(promises)

  return
}

export default twitter

A nice thing about rehype plugins is that if they return an error, they do not transform the node and move on. If, for whatever reason, the plugin gets into the .catch() block of the fetch Promise, the original blockquote will still exist as it originally was in the AST tree.

// Markdown
<blockquote class="twitter-tweet">
  <p lang="en" dir="ltr">
    I need to make a tweet embed component for my blog.
  </p>
  &mdash; Ryan Filler (@ryanfiller_)
  <a href="https://twitter.com/ryanfiller_/status/1259280535421140998?ref_src=twsrc%5Etfw">
    May 10, 2020
  </a>
</blockquote>

// HTML
<div class="twitter-tweet">
  <div >
    <a href="https://twitter.com/ryanfiller_" title="RyanFiller" >
      <img
        alt="Ryan Filler"
        src="https://pbs.twimg.com/profile_images/1038060989147766784/8P25vCc6_normal.jpg"
      >
    </a>
    <div>
      <a href="https://twitter.com/ryanfiller_">
        Ryan Filler
      </a>
      <a href="https://twitter.com/ryanfiller_">
        @ryanfiller_
      </a>
    </div>
    <a
      href="https://twitter.com/ryanfiller_/status/1259280535421140998?ref_src=twsrc%5Etfw"
      title="View on Twitter"
    >
      <svg>...</svg>
    </a>
  </div>
  <div >
    I need to make a tweet embed component for my blog.
  </div>
  <div >
    <span >
      May 10, 2020
    </span>
    <a href="/uses/#embedded-tweets">
      <svg>...</svg>
    </a>
  </div>
</div>

See the full code for the plugin on GitHub.

Huge thank you to Chris Biscardi for being available in the Party Corgi Discord group and pointing me to this async example, again by Jason Lengstorf.

Using the Plugins

I've found two situations to use these plugins on my own site — to pass to a build tool to create pages, or to call from the unified method directly for RSS.

For compiling pages, an array of plugins can be passed as part of the configuration object to both MDX (and its Gatsby implementation) and MDsveX.

// gatsby-config.js
plugins = [
  {
    resolve: 'gatsby-plugin-mdx',
    options: {
      extensions: ['.md'],
      remarkPlugins: [
        require(`remark-attr`),
        require(`${__dirname}/plugins/remark/blockquote`),
        require(`${__dirname}/plugins/remark/headings`),
        require(`${__dirname}/plugins/remark/images`),
        require(`${__dirname}/plugins/remark/links`),
      ],
      rehypePlugins: [
        require(`${__dirname}/plugins/rehype/embed`),
        require(`${__dirname}/plugins/rehype/twitter`)
      ],
    }
  }
]

// rollup.config.js
svelte({
  mdsvex({
    extension: '.md',
    remarkPlugins: [
      [attr, { scope: 'every' }],
      blockquote,
      headings,
      images,
      links,
    ],
    rehypePlugins: [
      embed,
      twitter
    ]
  })
})

The entire purpose of this refactor was to make my content more portable. The best part of this is that these plugins can be run outside of a framework. Like any other remark or rehype plugins, they can also be called as chained methods from the parent unified function. I use this in a helper method to create json and rss endpoints of my content.

  unified()
    .use(remarkParse)
    // use remark plugins here
    .use(remarkStringify)
    .use(remarkToRehype)
    // use rehype plugins here
    .use(rehypeStringify)
    .process(file, (err, file) => {
      // ...
    })

Plugins will need to run at certain points during the transformation life cycle, and going from a markdown file to a final HTML document requires a particular set of parse and stringify functions depending on the data.

For now, these plugins only live in a directory in my project. If your project could benefit from similar transformations, feel free to copy and paste them into your own project or reach out on Twitter and let me know — I can look into abstracting these and open sourcing them on NPM.

Svelte, Sanity, and Severless Functions

ryanfiller — Sun, 27 Sep 2020 00:00:00 +0000

Last month I wrote about creating an NPM package with Svelte. This month I built a basic CRUD site that would let other people use the color-contrast-table package tool I made.

The sitemap for the project was pretty basic.

HOMEPAGE
 - A list of all the site's users
 - New Users can be created here.
  └─ /OWNER 
   - A user's list of palettes that they own.
   - New Palettes can be created here.
    └─ /PALETTE
     - A specific color palette that contains an array of color data.
     - New Colors can be created here.
     - A user can go into edit mode to live edit and save existing colors.
     - A user can view and edit JSON for the color data.

For the final product, check out the code on GitHub or the live site.

The Tech Stack

Svelte

Because I wrote the same NPM package in three frameworks, I had three options to choose from for this project. I've mentioned in several previous posts that I'm interested in learning more about Svelte. Svelte is also a great fit for this project becase, as their homepage says Svelte is -

Truly reactive. No more complex state management libraries — Svelte brings reactivity to JavaScript itself.

Built-in, easy reactivity is ideal since the main feature of this site are users changing color values and viewing information in real time.

Sorry, your browser doesn't support embedded videos.
a user using the edit feature on the site

Routify

Because I already used Sapper on a few other projects, I started this one out using it too. However, I quickly ran into a big issue.

Sapper works best in two scenarios:

as a node.js app running on a server and dynamically generating pages
as a statically served site with a predetermined URL structure

Serving the site statically meant that I would need to trigger a build and a re-deploy any time a user added any new data. While it is possible to deploy a Sapper project in Node-mode to Vercel, I wanted to host this site on Netlify to avoid trying too many new things at once. Maybe next time I'll give Vercel a shot.

Luckily, Routify exists as an entirely client-side routing solution for Svelte apps. This means that the site could still deploy statically to Netlify, and instead of running a Vercel server to create dynamic pages, I could do all the work in a user's browser. As a bonus, Routify has a very similar API to Sapper so it wasn't a huge lift to refactor.

Routify has three main concepts.

File Structure

Routify and Sapper both use file system naming conventions to organize the site's final page heirarchy. The file structure within the /pages directory roughly translates to how the site will be built.

/pages/index.svelte/ becomes the homepage and /pages/page-name.svelte/ would become /page-name. Routify can also translate index files from directories into routes so /pages/nested/index.svelte/ would live at /nested on the live site. Files, or folders, can be named with square brackets surrounding them to pass dynamic parameters — /pages/nested/[name].svelte/ would catch any direct subpage of the /nested url, and would pass the name value into that page as a parameter.

My site structure was pretty shallow and my /pages directory looked like this:

/pages
 ├─ index.svelte
 ├─ [owner]
 │ ├─ index.svelte
 │ └─ [palette].svelte

`<Router>` Component

Routify interacts with the browser's window.url API by wrapping an entire app in the <Router> component. The dev, serve, and build commands in the package.json file will need to be changed to use the routify command instead of rollup.

// app.svelte

<script>
  import { Router } from '@sveltech/routify'
  import { routes } from '@sveltech/routify/tmp/routes'
</script>

<Router routes={routes} />

This looks sort of magical as the routes object doesn't need to be manually defined anywhere. Instead it's imported from a file generated by Routify based on the file structure I outline above. This handles pushing the correct url to the browser when a user clicks a link, as well as catching a nested URL that a user might visit directly and loading the correct internal page.

Passing Url Parameters

Routify will link between pages with regular <a href='...'> tags, but to actually pass dynamic data into the special [name].svelte file you need to use the $url helper. The $url() function accepts a URL string, using colons to denote variables, and also a 'params' object.

For my site, each owner contains a name and slug property.

{
  name: 'Ryan Filler',
  slug: 'ryan-filler'
}

In order to create a link that would read correctly and take the user to the correct page, the anchor tag looks like this.

<a href={$url('/:owner', {owner: owner.slug})}>
  {owner.name}
</a>

sanity.io

Now that the site could dynamically access data, that data needed somewhere to live.

Sanity describes itself as a "fast, flexible platform for delivering structured content," which sort of means that it functions as a database as a service. Sanity works as a hosted store for data that can be easily retrieved via their HTTP API and their GROQ language. GROQ, which is short for _Graph Oriented Query Language_, is very similar in syntax to GraphQL but without the need to write your own database resolvers. Sanity lets you post to a url, or use one of their language client interfaces to fetch and post data.

I started my project with the official Sapper Starter, but I wouldn't actually recommend doing this. This starter comes with a Sapper site (that I ended up replacing with Routify), and a way to locally run the backend Sanity Studio. If you're using Sanity more as a CMS this probably makes sense, but since I really just needed a data store I found it much easier to skip the local development and work on my database directly in the hosted version on sanity.studio.

The "structured" aspect of Sanity's approach to data comes from the schema.js file. A schema is a description of each data type and what fields, or accessible values, will be collected on each type. Each field is given a "schema type" which defines what someone querying the data can expect to get back.

The schema.js file isn't technically required since the Sanity API will accept any data and store it, but filling out this file helps make sure any posted data conforms to expectations.

Since each page would need to be backed by a corresponding data type the schema for my site was roughly the same as the site map. The homepage would be a collection of owners, each of which is defined in the schema like this:

{
  title: 'Owner',
  name: 'owner',
  type: 'document',
  fields: [
    {
      title: 'Name',
      name: 'name',
      type: 'string',
    },
    {
      title: 'Slug',
      name: 'slug',
      type: 'string'
    }
  ]
}

What makes Sanity and other services like it so awesome is the ability to define relationships between data without having to deeply understand the complexities of data model relationships. I used to work at an agency that used a custom PHP CMS, and having to decide between belongs-to, belongs-to-many, has-one, or has-many was hands down the hardest part of working on any site.

Since an Owner would be creating Palettes, I used the reference type in my Palette schema to create this association relationship.

{
  title: 'Color Palette',
  name: 'palette',
  type: 'document',
  fields: [
    {
      title: 'Title',
      name: 'title',
      type: 'string'
    },
    {
      title: 'Slug',
      name: 'slug',
      type: 'string'
    },
    {
      title: 'Owner',
      name: 'owner',
      type: 'reference',
      to: [{type: 'owner'}]
    },
    {
      title: 'Colors',
      name: 'colors',
      type: 'array',
      of: [{type: 'color'}]
    },   
  ]
}

Each Palette would hold a list of Colors so I used the of key to specify which other data type each element of the array would need to conform to.

{
  title: 'Color',
  name: 'color',
  type: 'object',
  fields: [
    {name: 'name', type: 'string', title: 'Name'},
    {name: 'value', type: 'string', title: 'Value'}
  ]
}

Getting Data

In order to make the next steps easier, I went ahead and seeded some data via the Studio hosted on sanity.io.

{
  "name": "Ryan",
  "slug": "ryan",
  "_id": "b524755a-25b6-4619-b92d-fb23779ea709",
  "palettes": [
    {
      "title": "CMYK",
      "slug": "cmyk",
      "_id": "a8659824-ebcd-4afe-a099-fffee9018024",
      "owner":{
        "_ref": "b524755a-25b6-4619-b92d-fb23779ea709",
      },
      "colors":[
        {
          "name": "cyan",
          "value": "#00FFFF"
        },
        {
          "name": "magenta",
          "value": "#FF00FF"
        },
        {
          "name": "yellow",
          "value": "#FFFF00"
        },
        {
          "name": "black",
          "value": "#000000"
        }
      ]
    }
  ]
}

Assuming we have data in the Sanity backend, the next step is to get it to the frontend. The easiest way to do this is to use the JavaScript @sanity/client package. This package provides an interface that can be called in other JavaScript files that, among other things, makes it much easier to work with GROQ queries. It needs a little bit of configuration to hook it up to your specific Sanity data.

// sanityClient.js

import sanityClient from '@sanity/client'

const client = sanityClient({
  projectId: process.env.SANITY_ID,
  dataset: 'production'
  useCdn: false
})

export default client

Sanity says that the projectID isn't sensitive data and is fine to expose over network calls, but I went ahead and put it in an ENV variable using the dotenv package just to be safe (more on this in the Sending Data section). Also, because of the live editing aspect of this project, the useCdn: false option is actually super important in this scenario to make sure that users aren't seeing cached data after making updates to their colors.

Getting All Data

Once the Sanity client is configured it can be imported and used in any component. To retrieve data, the client.fetch() method must be passed a GROQ query as the first argument. It can also accept an optional second arguement, a params object containing dynamic variables.

// index.svelte

<script>
  import client from '../sanityClient.js'

  const query = '*[_type == "owner"]'

  const getData = async () => {
    return client.fetch(query)
    .then(response => {
      ...
    })
    .catch(err => this.error(500, err))
  }
</script>

This paragraph from the GROQ documentation explains how a simple query works.

* returns all documents in the dataset that the current user has permissions to read. The documents are passed to a filter, which retains documents for which the expression evaluates to true.

Since this query fetches the data for the homepage, which will show a list of all Owners, the query will use the * selector to return all documents, then filter out ones that do not pass the [_type == "owner"] check and return only Owners.

Because the client.fetch() returns a Promise, Svelte's await blocks make it super easy to handle the different loading states in the UI.

// index.svelte

<script>
  const getData = async () => {...}
</script>

{#await getData()}
  <Loading />
{:then}
  ...
{:catch error}
  <Error />
{/await}

Getting Some Data

Once someone is on a specific Owner's page it makes sense to only load the data relevant to that Owner. To do this, we can use the client.fetch() params argument to pass variables to the GROQ query. Because part of the Routify link data includes the owner.slug data, that can be used to look up a Sanity owner with matching slug value.

// [owner]/index.svelte

<script>
  import { params } from '@sveltech/routify'
  import client from '../../sanityClient'

  const { owner } = $params

  const query = `
    *[_type == 'owner' && slug == $owner] {
      ...
    }
  `

  const queryArgs = { 
    owner: owner
  }

  const getData = async () => {
        return client.fetch(query, queryArgs)
        .then(response => {
       ...
    })
    .catch(err => this.error(500, err))
  }
</script>

$params (not to be confused with the Sanity params argument) is a Svelte store imported from the @sveltech/routify package. It allows information to be pulled from the <Router /> and used inside other components.

Inside the GROQ query, the $ identifier can be used to interpolate a dynamic value. I did some abstracting in the block above to make the component a little easier to read, but the end client.fetch() call will look like this:

client.fetch(`
  *[_type == 'owner' && slug == $owner] {
    // projection here
  }
`, {owner: $params.owner})
.then(response => {
    ...
})

Once we've looked up the owner that matches the current page, we can use Sanity's projections on that filter and get more data from it. The query can be expanded to look up a specific owner, get their _id attribute, then use that _id to look up all documents of the palette type that have a _ref value matching the Owner's _id.

const query = `
  *[_type == 'owner' && slug == $owner] {
    name,
    slug,
    _id,
    'palettes': *[_type == 'palette' && owner._ref == ^._id] {
      title,
      slug
    }
  }
`

Projections are similar to GraphQL fields and can be used to shape the data that will come back in the HTTP response. The query above would return JSON data in the shape built out in the Projection. In a Projection, you are able to ask for any field that exists on a type.

{
  "result": [
    {
      "name": "Ryan",
      "slug": "ryan",
      "_id": "b524755a-25b6-4619-b92d-fb23779ea709",
      "palettes": [
        {
          "slug": "website-2020",
          "title": "website 2020"
        },
        { ... },
        { ... },
        { ... },
        { ... }
      ]
    }
  ]
}

Filters and projections can be nested as deep as necessary (though keep in mind this might slow a query down), and as many params as needed can be passed. That means that on the page for a specific color palette, the query looks like this:

const { owner, palette } = $params

const query = `
  *[_type == 'owner' && slug == $owner] {
    name,
    slug,
    _id,
    'palettes': *[_type == 'palette' && owner._ref == ^._id && slug == $palette] {
      title,
      slug,
      _id,
      colors
    }
  }
`

const queryArgs = { owner, palette }

const getData = async () => {
  return client.fetch(query, queryArgs)
  .then(response => {
    ...
  })
  .catch(err => this.error(500, err))
}

... and would return data like this:

{
  "result": [
    {
      "name": "Ryan",
      "slug": "ryan",
      "_id": "b524755a-25b6-4619-b92d-fb23779ea709",
      "palettes": [
        {
          "title": "website 2020",
          "slug": "website-2020",
          "_id": "NOuiz2BuYnd9zvcp3ofESs",
          "colors": [
            {
              "name": "primary",
              "value": "#0f3287"
            },
            {
              "name": "dark",
              "value": "#151d43"
            },
            {
              "name": "light",
              "value": "#eee9d5"
            },
            {
              "name": "highlight",
              "value": "#da4181"
            },
            {
              "name": "active",
              "value": "#df5909"
            },
            {
              "name": "disabled",
              "value": "#6577a6"
            }
          ]
        }
      ]
    }
  ] 
}

The GROQ language can be a little confusing at first, and making a malformed query doesn't always return a super helpful error message. One helpful tool that Sanity provides is the Vision Plugin. This plugin can be added to the project's Studio, either locally or hosted on sanity.studio, and used to try out queries and see their potential response data.

Moving data around with Stores

Cool, so, once we have data, we need to move it around to the correct places. To do this I relied heavily on Svelte's stores.

On each page, there are two main data concerns — the Sanity data that needs to be shown, and the actions that a user can take to interact with that data. In a stores.js file, I set up two writables that could hold this data.

// stores.js

import { writable } from 'svelte/store'

export const data = writable({
  loading: false,
  error: null,
  response: [],
  owners: [],
  owner: null,
  palettes: [],
  palette: null,
  colors: []
})

export const actions = writable({
  buttons: [],
  current: null,
  error: false
})

To keep page data in sync, every time I made a call to the Sanity client I then took the response from the fetch call and set the page's $data store accordingly.

// index.svelte

<script>
  import client from '../sanityClient.js'
  import { data } from '../stores.js'

  const query = '*[_type == "owner"]'

  const getData = async () => {
    return client.fetch(query)
    .then(response => data.set({
      ...data,
      owners: response
    })
    ).catch(err => this.error(500, err))
  }
</script>

{#await getData()}
  <Loading />
{:then}
  {#if $data.owners.length}
    {#each $data.owners as owner}
      <a href={$url('/:owner', {owner: owner.slug})}>
        {owner.name}
      </a>
    {/each}
  {:else}
    uh oh, there are no users.
  {/if}
{:catch error}
  <Error />
{/await}

$data holds multiple types of page information, so I used the ...spread to copy the existing data and set a new value that only overwrites new data for the current page. On pages that had complicated data, it makes sense to use destructuring assignment to grab data off of the response object.

// [owner]/palette.svelte

const getData = async () => {
  return client.fetch(query, queryArgs)
  .then(response => {
    const {
      name,
      slug,
      _id: ownerId,
      palettes
    } = response[0]

    const {
      title,
      slug,
      _id: paletteId,
      colors
    } = response[0]

    return data.set({
      ...data,
      owner: { 
        name: name,
        slug: slug,
        id: ownerId
      },
      palette: {
        title: title,
        slug: slug,
        id: paletteId
      },
      colors: colors.map(color => ({
        name: color.name,
        value: color.value
      }))
    })
  }
  ).catch(err => this.error(500, err))
}

To load the specific actions for each page, I called the writeable.set() method any time a new layout was visited. On the /owner/palette route, a user needs to be able to add a new color, edit existing colors, or edit the JSON code.

// [owner]/palette.svelte

<script>
  import { actions } from '../../stores.js'

  actions.set({
    buttons: [
      {
        text: 'add a color',
        title: 'addColor', 
        icon: 'add',
        action: () => $actions.current = 'addColor'
      },
      {
        text: 'edit colors',
        title: 'editColors', 
        icon: 'edit',
        action: () => $actions.current = 'editColors'
      },
      {
        text: 'see JSON',
        title: 'seeCode', 
        icon: 'code',
        action: () => $actions.current = 'seeCode'
      }
    ]
  })
</script>

I mapped through these objects and used each to construct a button. Each configuration object could set things like a title and icon, and set the $actions.current value to render a different component to allow the user to edit data.

// actions-buttons.svelte

<script>
  import { actions } from '../stores.js'

  const icons = { ... } // a list of SVGs
</script>

{#each $actions.buttons as button}
  <button
    title={button.disabled ? `uh oh, there's a data error` : title}
    on:click={button.action}
    class:active={button.active}
    disabled={button.disabled}
  >
    <svelte:component this={icons[button.icon]} />
  </button>
{/each}

The actions component was a <form> tag that contained a giant if...else switch to conditionally show inputs that would post data back to the Sanity client.

// actions-area.svelte

<script>
  import { actions } from '../stores.js'

  const createNewColor = () => { ... }
</script>

<form id='action'>
  ...
  {if $actions.current === 'addColor'}
    <input
      type='text'
      id='new-color-name'
      name='new-color-name'
      bind:value={$data.color.name}
    />
    <input
      type='color'
      id='new-color-value'
      name='new-color-value'
      bind:value={$data.color.value}
    />
    <button on:click={createNewColor}>save color</button>
  {:else if $actions.current === ...}
</form>

Once the correct <input> elements are rendered, the Svelte bind: directive is used to update the $data store every time a user makes a change.

Netlify Functions

Now that we have data and users can create or edit data, we need a way to send that new data back to Sanity. The Sanity client can help here, with the .create and .mutate methods, but sending data requires a little more care than getting data.

Technically, anyone is able to hit the Sanity url endpoint and query data. There are ways to lock this down, but in my app I'm not too worried about it. However, I don't want just anybody to be able to write to that endpoint, which means I need a sanityClient configured with an authentication token. Tokens can be generated from the Sanity dashboard on manage.sanity.io, under Settings > API > CORS Origins.

const client = sanityClient({
  projectId: process.env.SANITY_ID,
  dataset: 'production',
  token: process.env.SANITY_TOKEN
})

I'm choosing to host this site statically on Netlify, so I can't include that token in the project. Firstly, it would be exposed in the project's git repository, and secondly it would be sent openly "over the wire" in each HTTP POST request.

This is where Netlify's serverless functions come in.

"Serverless functions" are not actually functions that don't run on a server, they just don't run on your server. A more accurate name for them is "cloud functions" since they run on other servers that exist only to perform one small action at a time.

Netlify Functions are pretty straightforward to set up. There are steps in the documentation on how to set them up via the online interface, or how to set them up directly in the netlify.toml file.

I set up two small functions, one to create and one to mutate, and they look almost exactly the same. The contents of each file in the /api folder will be packaged and deployed to a cloud server somewhere, so a new sanityClient needed to be created instantiated of each.

// api/create.js

require('dotenv').config()
const sanityClient = require('@sanity/client')
const client = sanityClient({
  projectId: process.env.SANITY_ID,
  dataset: 'production',
  token: process.env.SANITY_TOKEN
})

exports.handler = async function(event, _context, callback) {
  const payload = JSON.parse(event.body)
  const result = await client.create(payload, { returnDocuments: true })
  callback(null, {
    statusCode: 200,
    body: JSON.stringify(result)
  })
}

// api/mutate.js

require('dotenv').config()
const sanityClient = require('@sanity/client')
const client = sanityClient({
  projectId: process.env.SANITY_ID,
  dataset: 'production',
  token: process.env.SANITY_TOKEN
})

exports.handler = async function(event, _context, callback) {
  const payload = JSON.parse(event.body)
  const result = await client.mutate(payload, { returnDocuments: true })
  callback(null, {
    statusCode: 200,
    body: JSON.stringify(result)
  })
}

The returnDocuments: true option in the configuration object is important because it tells Sanity to return a representation of the document after the update request has succeeded. This means that the app can listen for the fetch.response and update accordingly with the latest data.

To avoid exposing my token credentials in these functions, I used the dotenv package again. After this package is installed, its config() method needs to be called as soon as possible in the project, so I put it at the top of my rollup.config.js file.

// rollup.config.js

import dotenv from 'dotenv'
dotenv.config()

process.env values can be defined in a .env file locally (make sure to add this to your .gitignore and commit it!), and in the Settings > Deploys > Environment section of the Netlify dashboard. These values don't have to match in both places, but they do both need to be valid tokens.

Sending Data

Once the Netlify Functions have been deployed, they live at a url corresponding to the name of the .js file.

To send data to these endpoints, I intercepted the POST action of the <form> element in my actions-area.svelte component. Since the <input> values are bound to the $data store, I could get values directly from the $data object and fetch against my Netlify function url.

Adding new data means posting a new object to the /functions/create endpoint. This object defines the _type and information of the new document to be created.

// actions-area.svelte

const createNewOwner = () => {
  fetch(`/.netlify/functions/create`, {
    method: 'POST', 
    credentials: 'same-origin',
    headers: { 'Content-Type': 'application/json' },
    body: {
      _type: '$data.owner',
      name: $data.owner,
      slug: slugify($data.owner)
    }
  }).then(response => response.json())
  .then(response => {
    $data.owners = [...$data.owners, response]
  })
  .catch(error => console.log('error', error))
}

In order to make sure that a user is seeing the most up to date representation of the data, every time a fetch call is made the $data store is updated with the response object from the Netlify function.

Adding to the colors array, since it involves editing existing data rather than creating new data, is slightly different. To do this I need to hit my /functions/mutate endpoint and give Sanity a patch to make.

// actions-area.svelte

const createNewColor = () => {
  fetch(`/.netlify/functions/mutate`, {
    method: 'POST', 
    credentials: 'same-origin',
    headers: { 'Content-Type': 'application/json' },
    body: [
      {
        patch: {
          id: $data.palette.id,
          insert: {
            after: 'colors[-1]',
            items: [{ name: $data.color.name, value: $data.color.value }]
          }
        }
      }
    ]
  }).then(response => response.json())
  .then(response => {
    $data.colors = response[0].colors)
  })
  .catch(error => console.log('error', error))
}

Because I need to add to append to the current array of colors the /functions/mutate endpoint takes an array of mutations to be performed on the document with the corresponding id value. Because of the returnDocuments: true option sent along with the request, I can then take the entire new array that contains both my old and new colors and set it to the $data store.

Still TODO

Tests

This application could probably use some tests, and this would be a good opportunity to explore mocking network activity using Cypress. I might get around to this in the future, but since this was just a fun side project there's also a chance I won't make time to thoroughly test it.

Authentication

Right now, this app works on the honor system — anyone can edit any colors. I hope they won't, but if this becomes a problem I could add authentication that would limit people to only making edits to things they were an Owner of. This might be a good learning experience for the fun of it, too. I could maybe implement Netlify Auth, which I've worked a little with in the past, or take a look at something completely new like Auth0. I've heard good things about Auth0 and how it can be used as a serverless function.

Building a Component in Three Frameworks

ryanfiller — Mon, 31 Aug 2020 12:56:51 +0000

I recently decided to break up my color-contrast-chart NPM package to be less coupled to a specific framework. I split off the core functionality into one package and the React rendering bits into another.

I did this because I knew I would be building a Svelte version of the package to use on my new site whenever I get around to refactoring it with Sapper. Since I was already building two versions I figured I might as well make a third and try out Vue for the first time. (Sorry Angular friends, maybe next time.)

This post is far from an exhaustive tutorial about how to use each framework, but more of a look into how each handles common frontend concerns at a high level. I've been working with React for almost four years, looking into Svelte on and off for about a year, and this will be my first time digging into Vue. I feel pretty confident in the React version, having refactored it several times already, but there's probably room for improvement in my Svelte and Vue implementations. If you have any constructive criticism, I'd absolutely love to hear it either on GitHub or Twitter.

Specifications

In order to make sure I was building the same features into each package, I came up with a short list of specifications. Each component would:

accept a color array to be transformed by the color-contrast-table core package
be able to toggle a set of default styles on but expose a set of usable class names for custom styles
have a pair of props that would be able to toggle the name and value being edited in real time and stored in local state
be able to pass in custom functions for when names and values change as well as a function for when inputs blur

I made a table of props and proptypes that each version of the component would need to conform to.

name	type	notes
`colors`	`array`	see color-contrast-table
`useStyles`	`boolean`	turn on default styles for chart
`editNames`	`boolean`	activate input for color names, does not need to be passed if `onNamesChange` is provided
`editValues`	`boolean`	activate input for color values, does not need to be passed if `onValuesChange` is provided
`onNamesChange`	`function`	optional callback to be fired when color name inputs change, will be passed `(colorIndex, event.target.value)`
`onValueChange`	`function`	optional callback to be fired when color value inputs change, will be passed `(colorIndex, event.target.value)`
`onInputBlur`	`function`	optional callback to be fired on blur of any input, will be passed `(event)`

Scaffolding a New Project

Creating a new project in a modern framework often require setting up complex environments and build setups. Luckily, all three frameworks offer a pretty straightforward ways to get a new project started.

React offers a first party CLI application tool, create-react-app. It's definitely a fast and easy way to get a new project going, and comes with Jest tests and Webpack already configured.

Once you have the CLI installed, you can run

  create-react-app new-project

There's actually a really helpful section in the React documentation suggesting some alternate tools for different scenarios if a full-blown Create React App would be too much overhead.

If TypeScript is your thing, I've heard good things about TSDX but have never used it myself.

Starting a new Svelte project could not be easier. There's a code snippet to copy and paste from The Svelte homepage that runs a degit command to create a Svelte app. It even uses npx so it doesn't required that you have degit installed.

  npx degit sveltejs/template new-project

While degit is yet another tool built by Svelte's creator Rich Harris, it isn't really a first party Svelte CLI tool. I think, though, that this speaks to how straightforward Svelte is compared to other frameworks. It can install from a simple repo with a rollup.config.js (another Rich Harris tool) and not have to deal with a complex Webpack configuration. This is because all of Svelte's work is done at compile time, so there's no need to transform or polyfill anything for run time in the browser.

Vue offers an absolutely amazing first party CLI. To start a new project, run

  vue create new-project

Honestly, this tool was magical, especially the vue serve command. It was crazy cool to be able to create any .vue file, then run vue serve and be able to view just that file being built and served in the browser.

Dev Tools

There isn't a ton to say about this, other than that all three frameworks have browser extension dev tools. I would highly recommend downloading them if you're doing any work with a particular framework. They help peer into component structure and data in more specific ways that a browser's normal inspect tools. This can save a lot of time when trying to diagnose the cause of an issue, plus it gives you some extra power to poke around in other people's websites and see how they're using a framework.

Components & Template Engines

Components are small pieces of reusable code that combine to build up complex applications, which is called "component composition." Often they accept data from their parent components and display or transform it in some way. Most modern JavaScript frameworks refer to passed data as "props," short for properties.

The most simple component in my color-chart is the <Color> component. This component needs to look at a color object which will contain a name, value, score, and contrast ratio.

There are two ways to create components in React: class components and function components. For the sake of simplicity in this post I'll be referring to function components. The React team is adamant that class components are not being deprecated and are still a totally valid way to approach React.

A React component is literally just a function that is exportd from a .js or .jsx file. Attributes that are passed to a component can be accessed with the props argument of a function component.

The React package itself will need to be imported first thing in any React component file.

  // color.jsx

  import React from 'react'

  const Color = (props) => {
    return {
      <div>
        <span>
          {props.color.score}
        </span>
      </div>
    }
  }

  export default Color

It's not required to name this function, but doing so will make debugging a lot easier than export default () => {...} will.

While technically not a requirement, the large majority of React projects use JSX as the template tool. JSX is not only for React, but I've never seen one used without the other.

JSX works mostly like HTML, but with ability to interpolate Javascript by wrapping it in curly brackets ({ }). This syntax can run expressions or print values, such as those from the props object . String attributes can be passed using quotation marks, but anything else will need to use the prop={value} bracket syntax.

This particular component is self-contained, but if it needed to wrap and render another component it could use React's special props.children value. This value will be automatically added to any component that contains children and doesn't need to be explicity passed anywhere.

  // label.jsx

  import React from 'react'

  const Label = (props) => {
    return {
      <span>
        {props.children}
      </span>
    }
  }

  export default Label

A component can be imported into another component's file with an import statement and then used like any other element.

  // color.jsx

  import React from 'react'
  import Label from './label.jsx'

  const Color = (props) => {
    return {
      <div>
        <Label>
          {props.color.score}
        </Label>
      </div>
    }
  }

  export default Color

A Svelte component is a special type of file with the .svelte extension that lets the Svelte compiler know it needs to be treated in a certain way. Behind the scenes, Svelte components are actually JavaScript classes, but writing them is a lot like writing regular HTML. JavaScript is contained within <script> tags, CSS within <style> tags, and everything else on the page will be rendered as HTML. A Svelte component can consist of one or more of these three sections.

  // color.svelte

  <script>
    export let color
  </script>

  <div>
    <span>
      {color.score}
    </span>
  </div>

A few things are immediately different from React. The component is automatically named and exported based on the name of the file. Rather than be passed an a props object, values must be created with the export let syntax. Sort of a running theme for Svelte, the syntax seems weird at first but makes sense the more you think about it. Think of it as declaring a reassignable variable, and exporting it so that it can be overwritten by other components.

Similarly to JSX, Svelte uses curly brackets to escape HTML and interpolate JavaScript values declared in the <script> tag. Unlike JSX, anything that is correct in HTML is also valid in a Svelte template. Svelte describes itself as as "superset" of HTML, so "any valid HTML is valid Svelte."

Component composition works slightly different as well. Rather than passing children via props, Svelte uses a special tag called a <slot/>.

<slot> elements are functionally very different than JSX's props.children, but at a basic level they should work mostly the same.

  // label.svelte

  <span>
    <slot />
  </span>

Components can be imported within the <script> section of other components and used as custom HTML tags.

  // color.svelte

  <script>
    export let color
    import Label from './label.svelte'
  </script>

  <div>
    <Label>
      {color.score}
    </Label>
  </div>

Vue, like React, has multiple ways to structure a component file. I don't have enough experience to speak to the pros and cons of each, but I chose to write all my components using the single file component approach.

Apparently you can use JSX with Vue, but none of the Vue developers I know have ever mentioned doing this. By default, Vue comes with its own template syntax that is similar to Svelte's.

  // color.vue

  <script>  
    export default {
      name: 'Color',
      props: {
        color
      }
    }
  </script>

  <template>
    <div>
      <span>
        {{ this.color.score }}
      </span>
    </div>
  </template>

Just like Svelte, JavaScript in a Vue component lives inside a <script> tag at the top of the file. Unlike Svelte, this code is required for a Vue component, and must contain a structured default export object. Vue components instantiate JavaScript classes, and Vue forces you to be declarative when defining a component's dependcies. This makes sense if you think about writing the constructor() function of a regular class.

The name key corresponds to how the component will be referenced in other files. All the props need to be explicitly added to the props object. Once properties are assigned to the Vue component class, they can be used in the HTML by using the this. syntax. this in JavaScript can be kind of a hard thing to understand, but for this scenario think about it as "this component."

Vue also needs to return a <template> tag in each component to register what HTML will be rendered. Interpolatin JavaScript in HTML uses "Mustache" syntax, or double curly brackets ({{ }}).

For composing components, Vue also uses the <slot> tag.

  // label.vue

  <script>  
    export default {
      name: 'Label'
    }
  </script>

  <template>
    <span>
      <slot />
    </span>
  </template>

Like props, any imported components will need to be registered inside the <script> tag. After that, they can be used inside the <template> as custom elements.

  // color.vue

  <script>  
    import Label from './label.vue'

    export default {
      name: 'Color',
      props: {
        color
      },
      components: {
        Label
      }
    }
  </script>

  <template>
    <div>
      <Label>
        {{ this.color.score }}
      </Label>
    </div>
  </template>

Passing Props and Checking Types

props, like I briefly mentioned before, are how modern JavaScript frameworks pass data around. For the most part props "flow down," meaning that they are passed from parent to child and not in the other direction.

In the color chart, each <Color> component needs to get a certain set of color data from its parent <Row> component. That data looks like this:

  color: {
    name: 'purple', // the color's name
    value: '#800080' // the color's hex value,
    score: 'AAA', // whether or not the color passes contrast with the row
    ratio: 1.5 // the actual contrast with the current row
  }

There are three main ways data can be passed: as individual attributes; bundled up as an object containing multiple attributes that can be unpacked later; or using some variation of the spread funtion to unpack the data before it makes it into the component.

The good news is that all three frameworks also have tools to add types to help manage a component's expectations around props data.

In React, props are immutable data passed into child components. This means that unless you go out of your way to allow changes, what you pass into a component will be exactly what the component will always render. Props are passed using regular HTML attribute syntax for strings, and the curly brackets syntax for any other type of value.

  // row.jsx

  import React from 'react'
  import Color from './color.jsx'

  const Row = (props) => {
    return (
      <tr>
        <Color
          name={props.color.name}
          value={props.color.value}
          score={props.color.score}
          ratio={props.color.ratio}
        />
      </tr>
    )
  }

  export default Row

To ensure that the <Color> component knows what type to expect for each prop, React requires the PropTypes addon. This used to be part of the core React package, but was split into its own dependency since using it is optional. It now needs to be separately imported into any file it is used in.

A component's .propTypes are assigned in the same file, after the main body of the component.

  // color.jsx

  import React from 'react'
  import PropTypes from 'prop-types'

  const Color = (props) => {
    return {
      <div title={`Ratio ${props.ratio}`}>
        <span>
          {props.score}
        </span>
      </div>
    }
  }

  Color.propTypes = {
    name: PropTypes.string,
    value: PropTypes.string,
    score: PropTypes.string,
    ratio: PropTypes.number
  }

  export default Color

To make this more concise, the entire color object can be passed from <Row> to <Color>, then its attributes can be accessed inside the <Color> component.

  // row.jsx

  import React from 'react'
  import Color from './color.jsx'

  const Row = (props) => {
    return (
      <tr>
        <Color color={props.color} />
      </tr>
    )
  }

  export default Row

This means an update in the Color's PropTypes. It's possible to deep check the shape of an object, but for the sake of simplicity let's just check that it is an object.

  // color.jsx

  import React from 'react'
  import PropTypes from 'prop-types'

  const Color = (props) => {
    return {
      <div title={`Ratio ${props.color.ratio}`}>
        <span>
          {props.color.score}
        </span>
      </div>
    }
  }

  Color.propTypes = {
    color: PropTypes.object
  }

  export default Color

The last way to pass props is to take advantage of the fact that they themselves are object type and use the ...spread operator. Instead of passing the bundled object as one value, the spread operator will take each attribute and pass it individually. This is a particularly helpful tool when a parent is passed props that in turn need to all be passed through to a child. Rather than be set to the value of an attribute, this syntax is applied directly to the component.

  // row.jsx

  import React from 'react'
  import Color from './color.jsx'

  const Row = (props) => {
    return (
      <tr>
        <Color {...props.color} />
      </tr>
    )
  }

  export default Row

Because each attribute was passed unbundled from the single color object, the type of each individual prop can be checked.

  // color.jsx

  import React from 'react'
  import PropTypes from 'prop-types'

  const Color = (props) => {
    return {
      <div title={`Ratio ${props.ratio}`}>
        <span>
          {props.score}
        </span>
      </div>
    }
  }

  Color.propTypes = {
    name: PropTypes.string,
    value: PropTypes.string,
    score: PropTypes.string,
    ratio: PropTypes.number
  }

  export default Color

Svelte props work similar to React props. They have nearly the same syntax, with quotation marks for strings and curly brackets for other values, but can also accept any keywords that work in regular HTML.

    // row.svelte

    <script>
      export let color

      import Color from './color.svelte'
    </script>

    <tr>
      <Color 
        name={color.name}
        value={color.value}
        score={color.score}
        ratio={color.ratio}
      />
    </tr>

Unlike React, Svelte comes built-in with an easy-to-opt-into typing system. When defining a prop in a child component using the export let syntax, a default value can be set. Svelte will then throw a warning when a new value is assigned that does not match that original type. To opt out of this either don't set a default or explicitly assign it undefined.

  // color.svelte

  <script>
    export let name = ''
    export let value = ''
    export let score = ''
    export let ratio = 0
  </script>

  <div title={`Ratio ${ratio}`}>
    <span>
      {score}
    </span>
  </div>

Svelte can also pass an entire object as one attribute. One cool thing Svelte offers is the ability to use a shorthand to pass a prop if its name and value are the same. Instead of setting an attribute equal to a value, the value can be wrapped with curly bracket and added directly on an element.

    // row.svelte

    <script>
      export let color = {}

      import Color from './color.svelte'
    </script>

    <tr>
      // long form
      <Color color={color} />
      // shorthand
      <Color {color} />
    </tr>

These values can then be accessed off of the object in the child component.

  // color.svelte
  <script>
    export let color = {}
  </script>

  <div title={`Ratio ${color.ratio}`}>
    <span>
      {color.score}
    </span>
  </div>

It may seem like all individually defined and exported props are not automatically grouped into a single props object, but they actually are. This comes with the caveat that this syntax is best used sparingly.

$$props references all props that are passed to a component – including ones that are not declared with export. It is useful in rare cases, but not generally recommended, as it is difficult for Svelte to optimise.

The same spread operator syntax can be used to pass all props into a child.

```svelte
// row.svelte

<script>
  export let color = {}

  import Color from './color.svelte'
</script>

<tr>
  <Color {...$$props} />
</tr>




  In the child component the exported `props` will need to correspond to whatever was also passed to the parent. In this example, it would be a `color` object.



  ```svelte
  // color.svelte

  <script>
    export let color = {}
  </script>

  <div title={`Ratio ${color.ratio}`}>
    <span>
      {color.score}
    </span>
  </div>

Passing props in Vue works mostly like React and Svelte, but with a few syntactical differences. Firstly, prop attributes have to be "kebab-case". Vue props will also always use the double quotation (" ") syntax to declare all types of props, not just strings. Vue also makes a distinction between static props and dynamic props, the latter of which are prepended with v-bind:. Since the color chart will sometimes update when a user interacts with it, this is the syntax to use in this situation.

  // row.vue

  <script>  
    import Color from './color.vue'

    export default {
      name: 'Row',
      components: {
        Color
      },
      props: {
        color
      },
    }
  </script>

  <template>
    <tr>
      <Color 
        v-bind:name="this.color.name"
        v-bind:value="this.color.value"
        v-bind:score="this.color.score"
        v-bind:ratio="this.color.ratio"
      />
    </tr>
  </template>

Vue, like Svelte, comes with a typing system that only requires a small amount of additional syntax. When registering props to a component, each prop can be assigned a value to define a type associated with each key.

  // color.vue

  <script>  
    export default {
      name: 'Color',
      props: {
        name: String,
        value: String,
        score: String,
        ratio: Number
      }
    }
  </script>

  <template>
    <td>
      <div title="`Ratio ${this.ratio}`">
        <span>
          {{ this.score }}
        </span>
      </div>
    </td>
  </template>

Just like the other frameworks, objects can be passed down as props as well. Like Svelte, Vue offers a shorthand for writing out v-bind:. v-bind can be left off and dynamic props can be prepended with just :.

  // row.vue
  <script>  
    import Color from './color.vue'

    export default {
      name: 'Row',
      components: {
        Color
      },
      props: {
        color: Object
      },
    }
  </script>

  <template>
    <tr>
      // long form
      <Color v-bind:color="this.color" />
      // shorthand
      <Color :color="this.color" />
    </tr>
  </template>

As you would probably expect, those values can be accessed via the color object prop.

  // color.vue

  <script>  
    export default {
      name: 'Color',
      props: {
        color: Object
      }
    }
  </script>

  <template>
    <td>
      <div title="`Ratio ${this.color.ratio}`">
        <span>
          {{ this.color.score }}
        </span>
      </div>
    </td>
  </template>

Similar to Svelte, Vue also secretly bundles all of a components registered prop values into an object called $props, which can be referenced elsewhere in the component as this.$props. Unlike Svelte and React, however, there isn't really a way to spread this value into a child component and it is made more for referencing passed in values elsewhere in the <script> tag.

Inline Javascript and Styles

Sometimes, in order to make components more dynamic, values need to be set locally to each instance of a component. This is often useful to do within the render body of the component if the output will end up directly in the DOM. These DOM side effects often involve manipulating classes for CSS, or even adding inline CSS directly onto elements.

For the color chart, the easiest way to style each block was to add an inline background-color to each <Color> component. Also, each block runs a small JavaScript function to determine whether to use black or white text.

Using a conditional CSS class is how I was able to scope the global style sheet for the entire chart. A user can turn styles off by not passing the useStyles top level prop.

I'll be using Block Element Modifier style classes for this section, so if these look odd read up on what all the dashes and underscores mean.

React does its best to be unopinionated when it comes to styles. JSX uses the className attribute as an analog to the regular HTML class. Any string, or expression that evaluates to a string, can be used and will end up in the DOM and can be hooked up to an external style sheet.

  // color.jsx

  import React from 'react'

  const Color = (props) => {
    return (
      <td className='color-contrast-table__color'>
        <div className='color-contrast-table__color-block'>
          <span className='color-contrast-table__color-score'>
            {props.color.score}
          </span>
        </div>
      </td>
    )
  }

  export default Color

React also allows for inline styles, but the syntax is different than regular HTML. The style attribute accepts an object, and as such the keys need to be camelCase strings rathan than normal CSS properties that contain hyphens. JavaScript values can be used directly in this object.

  // color.jsx

  import React from 'react'

  const Color = (props) => {
    return (
      <td>
        <div style={{ backgroundColor: props.color.value }}>
          <span>
            {props.color.score}
          </span>
        </div>
      </td>
    )
  }

  export default Color

The last built-in way to work with styles in React is similar to inline styles, but is useful for styles that don't need to be attached to a specific DOM element. React's (hilariously named) dangerouslySetInnerHTML attribute can be combined with a <style> tag to create an on-page style sheet.

  // styles.jsx

  import React from 'react'

  const Styles = () => {
    return (
      <style dangerouslySetInnerHTML={{__html: `
        .color-contrast-table
          ...
        }
      `}} />
    )
  }

  export default Styles

Since JSX is "just javascript," running inline method doesn't require any special work. A function can be imported from another file, and then used anywhere in the body of the component or its returned JSX.

  // color.jsx

  import React from 'react'
  import getLabelColor from './get-label-color.js'

  const Color = (props) => {
    return (
      <td>
        <div
          style={{
            backgroundColor: props.color.value,
            color: getLabelColor(props.color.value)
          }}
        >
          <span>
            {props.color.score}
          </span>
        </div>
      </td>
    )
  }

  export default Color

More complex functions can even be defined as nested functions within a component before the return of the component's JSX. To hook up the useStyle prop I used this strategy to conditionally add a top level className and then scoped my <style> tag accordingly.

  // table.jsx
  const Table = (props) => {

    function getClassName() {
      if (props.useStyles) {
        return 'use-styles color-contrast-table'
      } else {
        return 'color-contrast-table'
      }
    }

    return (
      <table className={getClassName()}>
        <tbody>
          ...
        </tbody>
      </table>
    )
  }

  export default Table

Svelte, striving to be as close to HTML as possible, lets you use regular HTML class attribute syntax.

  // color.svelte
  <script>
    export let color
  </script>

  <td class='color-contrast-table__color'>
    <div class='color-contrast-table__color-block'>
      <span class='color-contrast-table__color-score'>
        {color.score}
      </span>
    </div>
  </td>

Since "valid HTML is valid Svelte," a regular style attribute can be used to create inline styles. This isn't very well documented, but Svelte can also interpolate JavaScript values within this attribute with the curly bracket syntax.

  // color.svelte

  <script>
    export let color
  </script>

  <td>
    <div style='background-color: {color.value};'>
      <span>
        {color.score}
      </span>
    </div>
  </td>

Svelte also comes with some pretty powerful built-in style tools. In addition to being able to define a <script> tag at the top of a .svelte file, you can define a <style> tag as well. The Svelte compiler will generate unique classes that will encapsulate styles to only effect elements within this component file. This means that styles won't naturally cascade down to child components, unless the style rule is wrapped with the :global() modifier.

  // styles.svelte

  <style>
    :global(.color-contrast-table) {
      ...
    }
  </style>

Because the <script> and HTML sections of a component are optional, this creates a global <Style /> component I can include near the top level of my color chart.

Since the <script> section of a component will run any valid JavaScript, component functions can be imported and run here. Variables can also be created and used in the HTML body with the same bracket syntax as props values.

  // color.svelte

  <script>
    export let color

    import getLabelColor from './get-label-color.js'
    const textColor = getLabelColor(color.value)
  </script>

  <td>
    <div style='
      background-color: {color.value};
      color: {textColor};
    '>
      <span>
        {color.score}
      </span>
    </div>
  </td>

Just like React, methods can be called inline using curly brackets. I used the same scoping method combined with a :global() modifier to toggle the styles for the chart.

  // table.svelte

  <script>
    export let colors
    export let useStyles

    function getClassName() {
      if (useStyles) {
        return 'use-styles color-contrast-table'
      } else {
        return 'color-contrast-table'
      }
    }
  </script>

  <table class='{useStyles()}'>
    <tbody>
      ...
    </tbody>
  </table>

One extra thing to note here when applying this logic specifically to classes is that Svelte also comes with a class: directive that makes conditionally rendering classes easier. Whatever directly follows the : will be added to the element's class list if the prop is truthy.

  // table.svelte

  <script>
    export let colors
    export let useStyles
  </script>

  <table
    class='color-contrast-table'
    class:use-styles={useStyles}
  >
    <tbody>
      ...
    </tbody>
  </table>

Vue, just like Svelte, uses the same class attribute syntax as regular HTML.

  // color.vue

  <script>
    export default {
      name: 'Color',
      props: {
        color
      }
    }
  </script>

  <template>
    <td class='color-contrast-table__color'>
      <div class='color-contrast-table__color-block'>
        <span class='color-contrast-table__color-score'>
          {{ color.score }}
        </span>
      </div>
    </td>
  </template>

Vue's inline style attribute, however, is a little closer to React's. Vue uses the v-bind:style syntax and needs to be passed an object. It can use regular, hyphenated CSS properties as keys as long as they're surrounded with single quotation marks (' ').

Any attributes that need access to interpolated values needs to use a Vue directives. A directive is a special kdinf of attribute, usually prefixed with "v-" that lets Vue know it needs to interpolate that attribute in a special way.

  // color.vue

  <script>
    export default {
      name: 'Color',
      props: {
        color
      }
    }
  </script>

  <template>
    <td>
      <div v-bind:style="{ 'background-color': color.value }">
        <span>
          {{ color.score }}
        </span>
      </div>
    </td>
  </template>

One awesome benefit of using a Vue single file component is the ability to add a <style> tag to a component in addition to a <script> tag. This works a lot like the Svelte <style> tag, but is more configurable. By default the styles will work like a global CSS stylesheet, but the tag itself can accept a scoped attribute. This will add generated classes and encapsulate the styles similar to Svelte.

  // styles.vue

  <script>
    export default {
      name: 'Styles',
    }
  </script>

  <style>
    .color-contrast-table {
      ...
    }
  </style>

  <template>
    <div></div>
  </template>

One thing worth mentioning here is that since a Vue component must contain a <template> tag and that tag must contain an element, you will have to put some random DOM element here. If that bothers you (it bothered me), there is an NPM package called vue-fragment that will allow you to return a ghost element that won't actually render anything.

When it comes to using methods inside of components, Vue requires a bit more structure than the other two frameworks.

To define a value in the <script> section and use that value in the component body, it must be registered like other imports. In a single file component, data needs to be a function that returns an object of data values. If that data value is going to be defined as the result of an expression, that function needs to also be registered to the methods key of the Vue object.

  // color.vue

  <script>  
    import getLabelColor from './get-label-color.js'

    export default {
      name: 'Color',
      props: {
        color
      },
      methods: {
        getLabelColor
      },
      data: function() {
        return {
          textColor: this.getLabelColor(this.color.value)
        }
      }
    }
  </script>

  <template>
    <td>
      <div
        v-bind:style="{ 
          'background-color': color.value,
          'color': this.textColor
        }"
      >
        <span>
          {{ color.score}}
        </span>
      </div>
    </td>
  </template>

Methods can also be defined as values inside the methods object, and can be run directly within the <template> section.

  // table.vue

  <script>  
    export default {
      name: 'Table',
      props: {
        colors,
        useStyles
      },
      methods: {
        getClassName: function() {
          if (this.useStyles) {
            return 'use-styles color-contrast-table'
          } else {
            return 'color-contrast-table'
          }
        }
      }
    }
  </script>

  <template>
    <table v-bind:class="getClassName()">
      <tbody>
        ...
      </tbody>
    </table>
  </template>

For methods that determine which classes are added to an element, Vue allows for binding a directive to the class attribute. You can pass an object to a bound class attribute, and if the value returns truthy the key will be added to the element's class list.

  // table.vue

  <script>  
    export default {
      name: 'Table',
      props: {
        colors,
        useStyles
      }
    }
  </script>

  <template>
    <table v-bind:class="{ 'use-styles': useStyles }">
      <tbody>
        ...
      </tbody>
    </table>
  </template>

Loops and Conditional Rendering

Moving up one level from the <Color> component in the color charts is the Row component. Each row contains two things: a collection of generated <Color> components, and a <Header> element that needs to know whether to show regular text or editable inputs.

Each Row will get props data that looks like this:

  {
    color: {
      name: 'purple', // the name of this color
      value: '#800080', // the value of this color
      combinationScores: [...], // a list of data about the other colors
    },
    editNames: false, // whether the name should show text or an input
    editValues: false // whether the value should show text or an input
  }

The biggest difference between JSX and any other templating system I've used is highlighted in the first paragraph of the JSX documentation.

JSX may remind you of a template language, but it comes with the full power of JavaScript.

This means that rather than learning JSX specific ways to programmatically create markup, React relies on directly using JavaScript methods. To render a list of items, an array of data can be looped through with a .map or a .forEach Array method.

  // row.jsx

  import React from 'react'
  import Color from './color.jsx'
  import Header from './header.jsx'

  const Row = (props) => {
    return (
      <tr>
        <Header editNames={props.editNames} editValues={props.editValues} />

        {props.color.combinationScores.map((color, index) => {
          return (
            <Color
              key={index}
              color={color}
            />
          )
        })}
      </tr>
    )
  }

  export default Row

One particular quirk to note here is that when rendering elements any list of elements React requires each to have a unqiue key attribute. This can be anything — like the elements name value — but its often easiest to just use the array index. This helps React keep track of items during re-renders.

Another gotcha of JSX is that despite being "just JavaScript," if () statements don't work inside the return of a render method. Because of this JSX code is more likely to use either the "short circuit" or ternary operators.

The "short circuit" is more of a design pattern and less of an actual operator, but it can be read as "if the data exists, show the HTML; if not, stop and show nothing."

If the row component needed to only show <Color> components for passing color combinations, it might look like this:

  {color.score !== 'fail' && 
    <Color color={color} />
  }

The ternary operator is used when one element is needed in one scenario and another in a different scenario, such as in the Header of each row.

  // header.jsx

  import React from 'react'

  const Header = (props) => {
    return (
      <th>
        {props.editNames
          ? <input type='text' value={props.color.name} />
          : <span>{props.color.name}</span>
        }
        {props.editValues
          ? <input type='color' value={props.color.value} />
          : <span>{props.color.value}</span>
        }
      </th>
    )
  }

  export default Header

A ternary, especially when intermixed with markup, can look confusing at first, but it functions essentially the same as an if...else statement. If the expression before the ? is truthy, the first condition before the : will execute. If not, default to the second condition after the :.

Svelte comes with its own built in template syntax. To run logic you'll need to hook into their specific syntax, using # to start an expression, : to continue the previous expression, and / to end.

To render a list of elements from an array of data, Svelte has several way to run an each loop.

    // row.svelte

    <script>
      export let color
      export let editNames
      export let editValues

      import Color from './color.svelte'
      import Header from './header.svelte'
    </script>

    <tr>
      <Header editNames={editNames} editValues={editValues} />

      {#each color.combinationScores as color}
        <Color color={color} />
      {/each}
    </tr>

A nice thing about Svelte templates over JSX is that they are a little smarter, so there's no need to manually add a key to elements (although you can if you ever need to).

Svelte also provides blocks for if type statements so there's no need to use something like the short circuit or the ternary.

An if block wraps some HTML that will only be returned if the condition returns true. To only show blocks with a passing score:

  {#if color.score !== 'fail'}
    <Color color={color} />
  {/if}

An if statement can also have an :else clause, providing a default that will be rendered if the conditional is evaluated as false.

  // header.svelte

  <script>
    export let editNames
    export let editValues
  </script>

  <th>
    {#if editNames}
      <input type='text' value={color.name} />
    {:else}
      <span>{color.name}</span>
    {/if}

    {#if editValues}
      <input type='color' value={color.value} />
    {:else}
      <span>{color.value}</span>
    {/if}
  </th>

Vue templates also come with a built in logic system, but rather than using custom tags it uses directives.

Vue's template directive attributes are interesting because they can be applied directly onto a tag, or can be applied to a wrapping <template> element that will function as a "rootless" element during render.

  // row.vue

  <script>  
    import Header from './header.vue'
    import Color from './color.vue'

    export default {
      name: 'Row',
      components: {
        Header,
        Color
      },
      props: {
        color
      },
    }
  </script>

  <template>
    <tr>
      <Header :editNames="editNames" :editValues="editValues" />

      // directive directly on element
      <Color
        v-for="(color, index) in color.combinationScores"
        :key="index"
        :color="color"
      />

      // with wrapping element
      <template v-for="(color, index) in color.combinationScores">
        <Color
          :key="index"
          :color="color"
        />
      </template>

    </tr>
  </template>

Vue also has both v-if and v-else directives that work how you would expect. Just like with v-for these can be applied on a wrapping <template> or directly to an element.

  // header.vue 
  <script>
    export default {
      name: 'Header',
      props: {
        editNames,
        editValues
      },
    }
  </script>

  <template>
    // directive directly on element
    <th>
      <input v-if="editNames" type='text' v-bind:value="color.name" />
      <span v-else>{{ color.name }}</span>

      <input v-if="editValues" type='color' v-bind:value="color.value" />
      <span v-else>{{ color.value }}</span>
    </th>

    // with wrapping element
    <th>
      <template v-if="editNames">
        <input type='text' v-bind:value="color.name" />
      </template>
      <template v-else>
        <span >{{ color.name }}</span>
      </template>

      <template v-if="editValues">
        <input type='color' v-bind:value="color.value" />
      </template>
      <template v-else>
        <span >{{ color.value }}</span>
      </template>
    </th>
  </template>

Vue also comes with one extra operator that the other two frameworks don't include — v-show. v-show works visually just like v-if, but instead of not rendering an element it still renders the markup, but uses CSS to hide it from the DOM.

  // directive directly on element
  <Color v-show="color.score !== 'fail'" color={color} />

  // with wrapping element
  <template color.score !== 'fail'>
    <Color color={color} />
  </template>

This could be accomplished in React or Svelte as well, but it's nice of Vue to provide such an easy syntax for it.

State and Events

If props are one half of modern frameworks, state is the other. Props are data passed into components, state represents values internal to the component at render time. State is often updated in response to actions that a user takes. State can even be derived from an initial set of props passed into a component as a starting state.

Each component can hold it's own state, and pass it down into child components via props, but often the top level component for a system will maintain all the state and disperse it down the tree. All three frameworks contain mechanisms to re-render a component if its props or state change. If a user takes an action, the top level component will be notified to update its state, and then let the children know they needs to re-render with new data.

Custom events tied to different inputs and user actions are used to update state.

React has a very complicated state system for class components that involves binding values and updater functions to a component's this. Since I've only been talking about function components it makes more sense to look at the useState hook and not the setState function. Hooks can be a confusing concept at first, especially if you're not already familiar with all of the class lifecycle methods, but try to think of them as importable functions that add ability for components to do more complex actions than just render JSX.

Any of the built-in React hooks can be imported as a named import from the 'react' package, or they can be accessed directly off the React default import, like React.useState().

The useState hook is a function that can accept an argument to use as its initial state. It will return two values: the state value and a function to update that state value. These two values are usually written with the array destructure assignment syntax, and will mostly follow the valueName, setValueName naming convention.

  // chart.js

  import React, { useState } from 'react'
  import generateChart from 'color-contrast-table'

  const Chart = (props) => {

    const [colors, setColors] = useState(props.colors)
    const colorChart = generateChart(colors)

    return (
      <Table colors={colorChart} />
    )
  }

  export default Chart

Calling setColor(newColors) would cause the value of colors to change and cause a re-render of the <Chart> component as well as any children that depend on the colors prop. The setColors function can even be passed down as a prop itself and called within a child component. State setting functions in class components would need to have their this value bound in the class constructor, but because arrow function components don't reassign this a state updater can be passed and called wherever without worrying about binding.

Because this function needs to be called on the change event of an input, which will only return one value, the function needs to do a little more work to get only that new value into the existing colors object. Once that is worked out, the new colors object can be set using the setColor updater.

```react

// chart.js

import React, { useState } from 'react'
import generateChart from 'color-contrast-table'

const Chart = (props) => {

const [colors, setColors] = useState(props.colors)

const onNamesChange = (index, value) => {
  const newColors = [...colors]
  newColors[index].name = value
  setColors(newColors)
}

const onValuesChange = (index, value) => {
  const newColors = [...colors]
  newColors[index].value = value
  setColors(newColors)
}

const colorChart = generateChart(colors)

return (
  <Table
    colors={colorChart}
    onNamesChange={onNamesChange}
    onValuesChange={onValuesChange}
  />
)

}

export default Chart

// header.jsx

import React from 'react'

const Header = (props) => {
return (

type='text'
value={props.color.name}
onChange={event => props.onNamesChange(props.index, event.target.value)}
/>
type='color'
value={props.color.value}
onChange={event => props.onValuesChange(props.index, event.target.value)}
/>

)
}

export default Header




  The most important concept when dealing with state in React is that state objects are [immutable](https://developer.mozilla.org/en-US/docs/Glossary/Immutable) and should always be set using one of React's updaters and never reassigned directly.



  ```react
  // don't do this!

  const [colors] = useState(props.colors)

  const onNamesChange = (index, value) => {
    colors[index].name = value
  }

Svelte is very interesting when it comes to stateful logic. One of the main tenets that differentiates Svelte from other frontend systems is that all assignments are reactive. Svelte "hijacks" the assignment operator (=) and uses it to trigger state changes and re-renders within Svelte apps.

Svelte also comes with a built-in method to make anything reactive by prefacing it with $:. This is another one of those "looks weird but is actually valid JavaScript" things from Svelte, this time taking advantage of a JavaScript label.

All of that to say, simply by declaring a prop, a Svelte app is already stateful. State, whether just a reactive prop or a labeled reactive statement, can be passed down to child components like any other type of data.

  // table.svelte 

  <script>
    export let colors

    import generateChart from 'color-contrast-table'
    import Table from './table.svelte'

    $: colors = generateChart(colors)
  </script>

  <Table {colors} />

Updating stateful values in Svlete can be handled in nearly the same way as in React, where an updater function is passed down into a child, and the return will set a new value in the parent. However, Svelte also offers something very different called a store.

A store is a place to put data outside of the normal component hierarchy. They provide methods to subscribe, update and set their data. Svelte stores come in several varieties, but the one that makes the most sense to use here is a writable, meaning that we can both read and write data to it.

  // stores.js

  import { writable } from 'svelte/store'
  export const colorArray = writable()

Then, in the <Chart> component, the colorArray store can be imported, set with props data, subscribed to, and passed down.

  // chart.svelte

  <script>
    export let colors

    import generateChart from 'color-contrast-table'
    import Table from './table.svelte'

    import { colorArray } from './stores.js'
    colorArray.set(colors)
    colorArray.subscribe(colorArray => colors = colorArray)

    $: colors = generateChart(colors)
  </script>

  <Table {colors} />

This doesn't change much in the <Chart> component itself, but what it does allow for is direct access to update the colorArray store without having to pass functions. Instead, the <Header> component can access the store directly, call its update method, and the rest of the components will be made aware of this change via the subscribe method in <Chart>. Store methods can be composed in other functions that will sort out updating a single object property, then can be bound to input events using Svelte's element directives.

  // header.svelte

  <script>
    export let color
    export let index

    import { colorArray } from './stores.js'
    const onNamesChange = (index, value) => {
      colorArray.update(colorArray => {
        const newColors = [...colorArray]
        newColors[index].name = value
        return newColors
      }
    })

    const onValuesChange = (index, value) => {
      colorArray.update(colorArray => {
        const newColors = [...colorArray]
        newColors[index].value = value
        return newColors
      }
    })
  </script>

  <th>
    <input
      type='text'
      value={color.name}
      on:input={event => onNamesChange(index, event.target.value)}
    />

    <input
      type='color'
      value={color.value}
      on:input={event => onValuesChange(index, event.target.value)}
    />
  </th>

Vue has two state-like concepts: computed and watched properties. A computed property is one that is calculated based on some other data in the app and will remain cached after updating. A watch property is like a computed property that requires a more custom implementation for how the data changing should be handled. The Vue docs recommend using computed over watch for most scenarios that don't involve asynchronous data, so that seemed like the right option for me.

  // chart.vue

  <script>  
    import generateChart from 'color-contrast-table'
    import Table from './table.vue'

    export default {
      name: 'Chart',
      components: {
        Table
      },
      props: {
        colors
      },
      methods: {
        generateChart,
      },
      data() {
        return {
          colorArray: this.$props.colors
        }
      },
      computed: {
        colorChart: function () {
          return this.generateChart(this.colorArray)
        }
      }
    }
  </script>

  <template>
    <Fragment>
      <Styles/>
      <Table v-bind:colors="colorChart" /> 
    </Fragment>
  </template>

It feels slightly extraneous to have to assign a data.colorArray value and pass it through to computed.colorChart, but since Vue props are also immutable this is necessary. props.colors can't be changed, but data.colorArray can, and whenever it does computed.colorChart will also change and cause a re-render.

Vue uses an event-driven system to update state. Rather than having a function be passed down and bound to the change event of an input, an event is emitted by the input and then "caught" by a parent component. Custom events are defined by using the v-on: syntax, and are then passed an $emit() function. The first argument of $emit() is the name of the event to be emitted and the rest will be passed into the function when the event is caught.

  // header.vue

  <script>  
    import getLabelColor from './get-label-color.js'
    import EditName from './edit-name.vue'
    import EditValue from './edit-value.vue'

    export default {
      name: 'Header',
      props: {
        color,
        index,
      },
      methods: {
        getLabelColor,
        namechange(index, value) { this.$emit('namechange', index, value) },
        valuechange(index, value) { this.$emit('valuechange', index, value) }
      }
    }
  </script>

  <template>
    <th>
      <input
        type='text'
        :value="value"
        v-on:input="$emit('namechange', index, $event.target.value)"
      />

      <input
        type='color'
        :value="value"
        v-on:input="$emit('valuechange', index, $event.target.value)"
      />
    </th>
  </template>

These events can be caught and passed upwards so that a deeply nested child can update a value higher than its direct parent. For less typing, the @ symbol can be used as a shorthand for v-on.

  // header.vue

  methods: {
    namechange(index, value) { this.$emit('namechange', index, value) },
    valuechange(index, value) { this.$emit('valuechange', index, value) },
  }
  ...
  <input 
    type='text'
    :value="color.name"
    @input="$emit('namechange', index, $event.target.value)"
  />
  <input 
    type='color'
    :value="color.value"
    @input="$emit('valuechange', index, $event.target.value)"
  />

  // other components in between

  methods: {
    namechange(index, value) { this.$emit('namechange', index, value) },
    valuechange(index, value) { this.$emit('valuechange', index, value) },
  }
  ...
  <Header
    @namechange="namechange"
    @valuechange="valuechange"
  />

  //chart .vue

  methods: {
    namechange: function (index, value) {
      ...
    }
    valuechange: function (index, value) {
      ...
    }
    ...
    <Table
      @namechange="namechange"
      @valuechange="valuechange"
    >
  }

This might look like props being passed down, but this data flow is actually starting in the nested component and working its way upward. Once this function has been passed upwards to the same component in which the original computed values live, a method with the same name as the emitted event can be run to assign new data.

  // chart.vue

  <script>  
    import generateChart from 'color-contrast-table'
    import Table from './table.vue'

    export default {
      name: 'Chart',
      components: {
        Table,
      },
      props: {
        colors: Array,
      },
      methods: {
        generateChart,
        namechangefunction (index, value) {
          this.colorArray[index].name = value
        },
        valuechangefunction (index, value) {
          this.colorArray[index].value = value
        }
      },
      data() {
        return {
          colorArray: this.$props.colors
        }
      },
      computed: {
        colorChart: function () {
          return this.generateChart(this.colorArray)
        }
      },
    }
  </script>

  <template>
    <Fragment>
      <Styles/>
      <Table
        :colors="colorChart"
        @namechange="namechange"
        @valuechange="valuechange"
      /> 
    </Fragment>
  </template>

Like I mentioned before, we can't mutate props values, so instead these functions needs to change computed.colorArray. One nice side effect of this requirement is that unlike in React and Svelte where we had to spread an existing value into a new object to update one value, Vue can directly change one piece of the computed.colorArray object.

Front end state management is a LOT more complicated than what I briefly touched on here. Often since state deals with user input and data transformation there are a million different ways to handle this depending on how to optimize for the specific situation.

React can use the context API to circumvent passing props a lot like how Svelte uses stores. Svelte can use custom event directives to emit and listen for custom events similar to how Vue works. All three frameworks can pass down a function in one way or another that can be used to update a parent's state.

Performance

Just for fun, here's the final bundle size of each package running within three small example projects I put together.

Quirks and Final Thoughts

Of the these three frameworks, I've been working with React the longest and have built the most complex apps with it. My last few day jobs have involved primarily using React. That said, while I have the most knowledge about its intricacies, I probably also have the most experience with running up against its rough edges. There's a lot I like about React now, but I remember JSX being a lot to get used to. It can sometimes be hard to search out help as a beginner, especially now that there's probably as much information on the web about function components and Hooks as there are about class components and Lifecycle Methods. As a beginner its not always apparent when to use which.

Also, for whatever reason, at some point React's dev tools became two views — Components and Profiler. To be honest, I still don't know what the Profiler view does and much preferred the old consolidated view.

I've only built a handful of small projects with Svelte, but its been very enjoyable to use. It definitely has some syntax oddities, but I've found that they're often justifiable when explained in the right way. A lot of things make sense eventually but are used in ways that I've never quite seen JavaScript written before. This is out of the scope of what I wrote about in this post, but Svelte not relying on a virtual DOM is something that greatly interests me. This makes me want to explore Svlete more in the future.

As far as the Svelte community, I'm not a fan of Discord being the official source of help. I've come across many GitHub issues through web searches, been redirected to the Discord group, then been unable to use Discord's search to find any relevant information. Asking for help in Discord is hit or miss. It really depends who else is online at the time and if they have the answer to the question you're asking. Plus, I don't always have time to wait around for an answer, and since Discord lacks threads I've definitely missed responses that have come in after I've closed the Discord app.

Vue is super interesting, and as a direct alternative to React there's a lot about it that appealed to me. At first it felt like registering props, components, methods, data, etc... in each file felt like a lot of work, but the more I worked with Vue the more I appreciated its strong guidance system. For this being my first Vue project, the compiler threw a LOT of helpful console warnings and errors that really led to an overall smooth developer experience.

That said, I found Vue's versions can be kind of confusing. I can imagine this is how a lot of people feel not really being familiar with class vs function components in React, but I got pretty mixed up several times trying to use version 3 solutions to version 2 problems, or trying to do something in a single file component that was meant for a regular Vue instance.

This is just a personal opinion, but I think its super weird to use double quotes for interpolation.

  // React
  <div attribute={value}>text</div>

  // Svelte
  <div attribute={value}>text</div>

  // Vue
  <div v-attribute="value">text</div>

I have to say that most of my compile errors were around trying to use curly brackets when Vue wanted double quotes. Quotation marks pretty heavily signify a string type in my mental model at this point.

I hope this brief look into React, Svelte, and Vue helped someone make up their mind about which of the frameworks they'd like to get started with. All three have strengths and weaknesses, things I like and things I don't. It's hard to pick one I would definitely say is "the best," and that's probably a some-what subjective answer anyways. The best way to find out for yourself is to just start building.

If any of the examples from the post need a little bit more context to make sense, check out the full mono-repo for all three versions on GitHub. And if I got something wrong, either in the explanation or the packages themselves, I'm definitely accepting feedback and pull requests!

Good luck building!

Things Svelte and Sapper Can't Do (Yet)

ryanfiller — Sun, 26 Jul 2020 00:00:00 +0000

Last month I wrote about testing Svelte and Sapper to learn about their intricacies and limitations before trying to change my blog framework. I decided I'd explored enough to attempt a refactor and I found a few features that couldn't easily be replicated or done at all.

A .svelte file cannot export multiple components

The first problem I uncovered is a limitation within the Svelte framework. I found a workaround, but it was much, much more verbose.

On my Gatsby blog I use MDX to replace markdown elements with React components. Sapper has an equivalent tool, MDsveX. The configuration for both is similar — they need to import components and create an object that maps them to HTML elements.

// react
import { H1, H2, H3, H4, H5, H6 } from "../markdown/headings/index.js"

const components = {
  h1: H1,
  h2: H2,
  h3: H3,
  h4: H4,
  h5: H5,
  h6: H6
}

<MDXProvider components={components}>...</MDXProvider>

// svelte
<script context="module">
  import { h1, h2, h3, h4, h5, h6 } from './headings/index.js'
  export { h1, h2, h3, h4, h5, h6 }
</script>

My goal is to replace each heading tag with a page link component. The component is build by taking the text content of the title and transforming it into a hash link. The hash is added as an id to the heading and then wrapped in an <a> tag that links back to the hash. This basically replicates the functionality of remark's autolink headers plugin.

MDX Headings in Gatsby

The React way to build this component pretty straightforward. Because I still need to generate 6 different headings I made a generic <Heading /> component that could accept a prop telling it which h tag to render. I'll explain more about the slugify function further down.

const Heading = (props) => {

  import { slugify } from 'helpers'

  const hashUrl = slugify(props.children)
  const Level = `h${props.h}`

  return (
    <Level 
      id={hashUrl}
      className='heading'
    >
      <a href={`#${hashUrl}`}>
        {props.children}
      </a>
    </Level>
  )
}

Then, in an index file, I was able to use the <Heading /> component to compose six new components, one for each of the HTML headings.

import Heading from './heading'

const H1 = props => <Heading h="1">{props.children}</Heading>
const H2 = props => <Heading h="2">{props.children}</Heading>
const H3 = props => <Heading h="3">{props.children}</Heading>
const H4 = props => <Heading h="4">{props.children}</Heading>
const H5 = props => <Heading h="5">{props.children}</Heading>
const H6 = props => <Heading h="6">{props.children}</Heading>

export { H1, H2, H3, H4, H5, H6 }

My directory structure looked like this.

└─ headings/
  ├─ heading.js // the generic component
  └─ index.js // export of composed h1-h6

I want to emphasize that React is creating and exporting six unique components in a single index.js file.

MDsveX Headings in Sapper

There are a few big differences with building this component in Svelte. Ignore the getText function for now, I'll elaborate on that later.

<script>
  export let h
  import { slugify } from 'helpers'

  let id
  let hashLink
  const getText = node => {
    id = slugify(node.text)
    hashLink = `#${id}`
  }
</script>

{#if h === '1'}
    <h1 id={id}><a use:getText href={hashLink}><slot/></a></h1>
{:else if h === '2'}
    <h2 id={id}><a use:getText href={hashLink}><slot/></a></h2>
{:else if h === '3'}
    <h3 id={id}><a use:getText href={hashLink}><slot/></a></h3>
{:else if h === '4'}
    <h4 id={id}><a use:getText href={hashLink}><slot/></a></h4>
{:else if h === '5'}
    <h5 id={id}><a use:getText href={hashLink}><slot/></a></h5>
{:else if h === '6'}
    <h6 id={id}><a use:getText href={hashLink}><slot/></a></h6>
{/if}

The first is that Svetle doesn't seem to have the ability to use strings to dynamically choose html tags. Maybe this is possible with svelte:component, but I could only get this to work with other custom components and not html tags. The good news is that the Svelte community is aware of this, and at the time of writing this post there is an open proposal to implement a fix. For now I went with one of the easier fixes suggested in the GitHub issue and added a series of if else statements.

The second issue lies in trying to replicate the index.js file that exports six heading components.

import h1 from './h1.svelte'
import h2 from './h2.svelte'
import h3 from './h3.svelte'
import h4 from './h4.svelte'
import h5 from './h5.svelte'
import h6 from './h6.svelte'

export { h1, h2, h3, h4, h5, h6 }

Svelte components can be imported and exported using ES6 syntax, but only one component can be created per .svelte file. Rather than naming a component and exporting it manually, Svelte will use the file name to automatically determine a component's named and how it is exported.

<script>
  import Heading from './heading.svelte'
</script>

<Heading h='1'><slot/></Heading>

An index file that exports six headings is still possible, but the directory structure is a lot messier than with React.

└─ headings/
  ├─ h1.svelte // composed component
  ├─ h2.svelte
  ├─ h3.svelte
  ├─ h4.svelte
  ├─ h5.svelte
  ├─ h6.svelte
  ├─ heading.svelte // the generic component
  └─ index.js // export of imported h1-h6

Sapper's router doesn't work with hash links

As with React, there is no officially supported Svelte router, only community favorites that most projects use. As far as I know Sapper doesn't use any one specific router package. Instead, it has a series of helper functions that handle internal navigation.

Sapper's routing strategy, however, does currently contain a pretty big bug. Clicking on <a> tags that point to hash links will trigger a navigation to a new page rather than scroll to an id on the same page. A link on the www.site.com/example page that looks like <a href='#test'>test</a> should scroll the page to an element with id='test' and change the url to www.site.com/example#test. This link will mistakenly navigate the app to www.site.com/#test, and likely end up rendering a 404 page.

This is a known bug

The Sapper team is aware of this bug with one or two issues already filed about it. I looked into the issue but couldn't figure out a fix since both the handle_click and navigate functions seem to have short circuits for when the urls contain hashes. Sapper's goto function doesn't appear to have any way to know about a hash link, so maybe that's the issue?

There IS a temporary fix

There is a workaround for this bug.

<script>
  import { onMount } from 'svelte'

  onMount( () => {
    document.querySelectorAll('a').forEach(a => {
      if (!a.hash||!document.querySelectorAll(a.hash).length) {
        return
      }
      a.href = window.location + a.hash
    })
  })
</script>

I am a strong proponent that all sites should work without JavaScript, so I don't love that this fix relies on the clientside onMount lifecycle hook. On the other hand, if a user has all scripts blocked from running then Sapper won't be able to rehydrate in the first place. This means Sapper's router won't take over navigation and all links should keep their default browser behavior, so this is a non-issue. Still, this code takes a second to run after the component mounts and the links still momentarily don't work. Also depending on the CSS this could lead to some style flashes as href shuffle around.

Components don't have programmatic access to their children

Time to circle back to the slugify and getText functions I mentioned earlier.

The HTML that MDX or MDsveX would replace looks like this:

<h1>The sun is shining, but the ice is slippery.</h1>

The goal is to transform the markup into something that looks like this:

<h1 id="the-sun-is-shining-but-the-ice-is-slippery">
  <a href="#the-sun-is-shining-but-the-ice-is-slippery">
    The sun is shining, but the ice is slippery.
  </a>
</h1>

In the React version of the Heading component the id and href attributes are derived by running the child text of the component through a function that will make them viable hash links.

const Heading = (props) => {

  import { slugify } from 'helpers'
  const hashUrl = slugify(props.children)

  return (
    <h1 
      id={hashUrl}
      className='heading'
    >
      <a href={`#${hashUrl}`}>
        {props.children}
      </a>
    </h1>
  )
}

This works because props.children can be accessed and manipulated like any other React prop. Svelte's API works differently, providing the <slot /> component as a way to render child content.

<script>
  import { slugify } from 'helpers'
  let id
  let hashLink
  const getText = node => {
    id = slugify(node.text)
    hashLink = `#${id}`
  }
</script>

<h1 id={id}><a use:getText href={hashLink}><slot/></a></h1>

props.children and <slot /> are similar but have one major difference. React has access to the child content and can transform it during run time before render. Svelte needs to know about child content at compile time, and can't know about children until after they are rendered.

The only way I found to get the child content to pass to the slugify function was to query it from the DOM after render. Svelte does have use:action binding, which makes it very easy to run a function as soon as an element is created. There are two big downsides to this. First, this leads to the flash of no-link styles I mentioned earlier. A component is created, then once the page is loaded enough to fire a DOM query the hash link is generated and appended. The second is that since this relies on direct DOM manipulation, this function won't fire if a user doesn't allow Javascript. This is a bummer since hash links navigation is something that browsers support natively and definitely shouldn't require Javascript.

There is an open Pull Request that will fix this

Some good news about this missing feature is that there is currently an open pull request to add a $$slots prop. This will work similarly to the existing $$props value. It is hard to say if this would solve my exact problem since it isn't implemented yet, but any programmatic access to the child content should work better than having to query text after it renders. The bad news is that this feature doesn't currently appear on Svelte's roadmap so it's hard to say when exactly it might land.

Dealbreakers?

So, do these handful of "missing" features mean I don't recommend trying Svelte?

No, Svelte is still a great framework that has enough features to do most things. Since it is a little younger than some other frameworks and doesn't have a massive corporation behind it, it may not have features for a handful of fairly specific scenarios, yet.

This does, unfortunately, mean that I won't currently be moving my blog from Gatsby to Sapper. I plan on giving this another shot when Sapper does a full 1.0 release. This should give Svelte time to release more features and give me time to refactor some of my React code to make it more portable. I'm also in the early planning stages of another web app and I'm still considering using Svelte and Sapper to build it. Like I said, Svelte is great, it just isn't not a great fit for my blog right now.

I've also only been working with Svelte for a few months, and it is entirely possible that these things are doable and I just haven't discovered how. If that's the case I would absolutely love to be told I'm wrong, let me know @ryanfiller_ on Twitter and I'll update this article with the fix.

DEV Community: ryanfiller

Blackletter Logo

What is Blackletter

Inspiration

Rough Sketch

Refining

Letter Stems

X-Height

Grid Layout

The Finished Logo

Progress on the New Site

Building an Alert Component in Svelte

The Basic Component

The HTML <dialog> Element

Stacking Context

Basic CSS

Managing tabindex

Trapping Focus

Persisting data with localStorage

The Final Product

Why My Blog Stopped Using Deploy Previews

What are Deploy Previews?

With Great Power... Comes Great Responsibility

Some Downsides to "Single Use Deploys"

Estimating the Cost of This Site

What Can You Do?

surge.sh

Building a Color Scheme Toggle

Setting up Colors

Designing the Toggle

Some Prerequisites

1. Reading a User's OS Preference

2. Clicking the Toggle Button

3. Intentionally Blocking JavaScript

4. Keeping Data in LocalStorage

5. Reading Data Without Flashes

6. Keeping Everything in Sync

Final Code

Building a Better Svelte Data Flow

How does Sapper work?

How does mdsvex work?

Shortcomings

Fetching data in other places

Combining both page composition methods

Getting data

Rendering the page

My sapper-mdsvex-starter

Special thanks

Choosing Theme Colors

Choosing a color palette

Keeping accessibility in mind

Naming colors

Narrowing down a theme

Converting a palette to Dark Mode

Other considerations for Dark Mode

A Short History of Interface Colors

What even is Dark Mode?

Where did Dark Mode come from?

Modern Dark Mode

Why should a site support Dark Mode?

For Eye Health

For Less Energy Consumption

Just Because

Dark Mode isn't for Everybody

Automatic Social Share Images

Which Tags to Use?

Dynamically Constructing a Preview Image

Passing Data with URL Search Parameters

encodeURI()

encodeURIComponent()

URLSearchParams

Replacing Data on the Page

Using a Serverless Function to Capture the Page

Uploading the Screenshot to Cloudinary

Forwarding to the Final URL in the Response

Final Function

Shoutouts

Transforming Markdown with Remark & Rehype

How do Markdown Parsers Work?

What is Remark?

The HTML `<dialog>` Element

Managing `tabindex`

Persisting data with `localStorage`

My `sapper-mdsvex-starter`

`encodeURI()`

`encodeURIComponent()`

`URLSearchParams`

`<Router>` Component