For a while I was interested in the idea of "sustainable websites" - in 2020-21 I even built my website around it and was betting on that as a my career going forward! I felt relieved to be able to "do something for the climate" inside my work as a web developer.

That’s no longer the case.

Building a green site! (what’s the impact?)

In January 2021, I built the website for a startup building a carbon footprint tracker for corporations. They reached me because they were interested in my approach to a low-carbon web - after doing a talk on the topic, this was the perfect opportunity to turn theory into practice, and I jumped eagerly at it.

I obsessed over optimizing every nook and cranny of a tiny static site for a starting company with unvalidated product, making tech choices that became obsolete and hard to maintain the second I shipped. I’ve wasted time & resources of a company in dire need of them: what could’ve been a 2-day project on Webflow, became 3 weeks of intense programming, with thousands of lines of code and a weird headless CMS to manage it.

Needless to say, I felt void of meaning when I shipped.

But I still needed to do something for the climate, right? Imagine on scale, this would matter! “Do you know how many people download the awfully bloated Google.com per second?!”

So I attended online conferences, read articles and wrote countless notes, with the promise of eventually publishing a lot, running a newsletter, lecturing a course, etc.

But the more I did it, the less I could justify what I was proposing. The most common question was along the lines of “what’s the impact of this in my individual web project?”, and I simply couldn’t feel good about any honest answer.

Sure, the inflated MBs shipped on Amazon.com do mean some good tonnes of CO2 emitted per year, but it’s insignificant close to the destruction done by Amazon-led consumerism.

With this unsettling truth circumdating as almost-conscious feelings in myself, I kept postponing “the dream of being a green builder”, until I started drawing more attention and money in other markets. And so ended my tech sustainability journey, of which the only rubble is my still-green website (which is still beautiful, thanks Mari!)

Going beyond utilitarism and individualism

Since then, I’ve developed my thoughts a bit further on sociopolitical and environmental topics. Most importantly, I’ve developed more closeness to myself, other people and nature, going into the body and emotions, and beyond what the intelect can reach. That gave me a lot of perspective on this failed attempt, not all of which I’d be able to articulate.

For one, I was seeking the money and vanity of being one of the first on a nascent field. Individualistic, status-driven, self-centric modern society at its finest.

Also, what kept me from acting in the end was the “lack of value” of the work - an utilitarian notion which keeps us producing always more, giving higher surplus to our capitalist overlords.

And more recently, I finally understood that any commodity that names itself “sustainable” (in this case, websites) is just paving the path for corporate greenwashing and guilt-free consumerism. Even if the proposers of the so-called sustainability are well-meaning.

Companies trying to make a buck co-opting this web sustainability discourse have been reaching me out more and more, which was what prompted me to write these thoughts. If this isn’t a glaring indication of the issue above, I don’t know what is.

On October 2020, I closed my talk on an “eco-friendly web framework” saying we don’t need more tools, we need education.

I still agree with this statement. But I no longer think it’s about educating programmers to build leaner websites and designers to rethink the need & scope of what’s being built.

I now think we should be educating people to become anti-capitalist, and embrace the anti-racist, anti-racialist, feminist, agroecological movements that are required for this change to happen.

If we want to “save the planet”, we need ecosocialism, not an eco-friendly web.

How am I becoming an ecosocialist myself, you ask? Still learning, and glad to learn with you, feel free to reach out!

TL;DR: while learning its syntax, instead of trying to write Typescript, you can write Javascript and let the compiler and your IDE do the work for you.

If you want to type an existing piece function or value, you can use typeof VARIABLE_NAME and Typescript's compiler will introspect the type from your Javascript, without you having to manually type it out.

Besides lowering the barrier to entry, this also speeds things up quite significantly. And you still get TS's amazing auto-complete and warnings!

Perhaps more importantly, if you use TS-friendly IDEs like VS Code you can hover over a variable definition to get the shape of the data and start learning its syntax.

Use these tricks with a basic knowledge of Type Aliases, and you've pretty much got to 80% of Typescript values.

Of course, there are unions, assertions, narrowing, type casting, constraints, overloads and-otherso-confusing-my-brain-is-melting features 🫠

These are mainly for library authors, though.

I've been using TS for almost 5 years and I still write mostly type definitions (or interface, basically the same but for objects) and enums (fancy key/value objects). Here's an adaption of real-world code I wrote recently:

// We often use library-provided types
import { SanityDocument } from '@sanity/client'

type TranslationInMeta = {
  /**
   * Using TSDoc comments is great, by the way!
   * @link https://tsdoc.org/
   */
  _key: string
  _ref: string
}

// Sometimes we do fancy merging of types...
type TranslationMetaDoc = TranslationInMeta & SanityDocument {
  locales: TranslationInMeta[]
}

export function useDocumentTranslations({
  currentDocument,
}: {
  currentDocument?: SanityDocument
}) {
  // It's okay to use `any`, too!
  const routerContext = React.useContext<any>(RouterContext)

  const [translationsDocument, setTranslationsDocument] =
    React.useState<TranslationMetaDoc | null>(null)

  // ...
}

Looks mostly like React Javascript, right? That's because it is! Just a "flavored" version of it 😉

Now, if you're a library author, you may find yourself writing code like this... (source)

export function createMachine<
  TContext,
  TEvent extends EventObject = AnyEventObject,
  TTypestate extends Typestate<TContext> = { value: any; context: TContext },
  TServiceMap extends ServiceMap = ServiceMap,
  TTypesMeta extends TypegenConstraint = TypegenDisabled
>(
  config: MachineConfig<
    TContext,
    any,
    TEvent,
    BaseActionObject,
    TServiceMap,
    TTypesMeta
  >,
  options?: InternalMachineOptions<
    TContext,
    TEvent,
    ResolveTypegenMeta<TTypesMeta, TEvent, BaseActionObject, TServiceMap>
  >
): StateMachine<
  TContext,
  any,
  TEvent,
  TTypestate,
  BaseActionObject,
  TServiceMap,
  ResolveTypegenMeta<TTypesMeta, TEvent, BaseActionObject, TServiceMap>
>;

I honestly don't even know how this code works - it's a function that has no body, and there's another declaration of a function with the same name right below it. Too much for my brain to handle 😵‍💫

So yeah, take it easy, start by writing Javascript and adopt TS incrementally :)

Credits to Clara Amenyo for sparking this idea in a pairing session during my Recurse Center batch :)

Non-web developers are surprised when we tell them how complicated rendering images can be. Worrying about the layout is only a part of it, we also need to ensure images are accessible, performant, and responsive.

Over the years, I've spent hours obsessing over details and often got overwhelmed. Thankfully, Sanity.io's powerful CDN and recent CSS & HTML advancements made it much simpler & easier to get it right. Let's get to it!

The holy grail of web images

In short, we want crisp, fast-loading, accessible images that don't waste bandwidth. Concretely, they need to:

1. Scale to their visual placement on the page - no 3000px-wide file in a tiny 50px avatar component
2. Scale to the user's device pixel density - a 3x retina screen will use 150 actual pixels to render 50 "virtual" pixels (the equivalent of CSS's 50px)
3. Be served in the most effective format - if a simple vector, an SVG will always be smaller & crispier, for example
4. If cropped by the layout, they should adapt to their container with proper focus on the most important bits of the picture
5. Only load when in view (lazy loading)
6. Contain clear descriptions in the alt property
7. Avoid low contrast and other visibility issues

With Sanity's image CDN we can automate 1, 2 & 3 and give editors the peace of mind of images just working™, so they can focus on creating high-quality content and not on scaling files.

For cropping (#4), you can enable hotspots & crops in Sanity and have your front-end(s) react automagically to them, ensuring the most important bits of the image are always shown, as defined by creators.

6 & 7 are out of the front-end's control, but you can instruct and nudge your editors to help visually impaired readers. See step 3 below.

Now, let's go through the step-by-step to achieve the holy grail above 🌟

Step 1: generating image variations

Sanity's CDN allows you to generate multiple variations of the same image by simply replacing a few query parameters in their URLs, such as:

• ?w=200 (scale to 200px wide)
• ?fit=max (scale the image up to its maximum dimensions)
• ?auto=format (use whatever format is more efficient)
• ?bg=333 (add a #333 gray color as the image's background, if transparent)
• ?q=40 (compress the image to 40% of its original quality)

Refer to the image URL documentation for all the available transformations.

Knowing this, we can build as many size variations of an image as needed for achieving the holy grail described above ✨

We'll generate a set of image sources to feed into the img element's srcset, and specify a sizes property with how the image scales according to the window size, and let the browser pick which image to download based on the user's device width and pixel density. Here's how I generate these variations:

import { getImageDimensions } from "./getImageDimensions";
import imageUrlBuilder from "@sanity/image-url";

export const imageBuilder = imageUrlBuilder({
  projectId: "SANITY_PROJECT_ID",
  dataset: "SANITY_DATASET",
});

const LARGEST_VIEWPORT = 1920; // Retina sizes will take care of 4k (2560px) and other huge screens

const DEFAULT_MIN_STEP = 0.1; // 10%
const DEFAULT_WIDTH_STEPS = [400, 600, 850, 1000, 1150]; // arbitrary
// Based on statcounter's most common screen sizes: https://gs.statcounter.com/screen-resolution-stats
const DEFAULT_FULL_WIDTH_STEPS = [360, 414, 768, 1366, 1536, 1920];

export default function getImageProps({
  /**
   * The image's reference object.
   * Example: {asset: {_ref: string}, hotspot: {...}, crop: {...} }
   */
  image,

  // Number of the largest width it can assume in the design
  // or "100vw" if it occupies the whole width
  maxWidth: userMaxWidth,

  /**
   * The minimal width difference, in PERCENTAGE (decimal), between the image's srcSet variations.
   *
   * -> 0.10 (10%) by default.
   */
  minimumWidthStep = DEFAULT_MIN_STEP,

  // List of width sizes to use in the srcSet (NON-RETINA)
  customWidthSteps,

  // Custom <img> element's `sizes` attribute
  sizes,
}) {
  if (!image?.asset?._ref) {
    return {};
  }
  const maxWidth =
    typeof userMaxWidth === "number" ? userMaxWidth : LARGEST_VIEWPORT;

  // For all image variations, we'll use an auto format and prevent scaling it over its max dimensions
  const builder = imageBuilder.image(image).fit("max").auto("format");

  const imageDimensions = getImageDimensions(image);

  // Width sizes the image could assume
  const baseSizes = [
    maxWidth,
    ...(customWidthSteps ||
      (typeof userMaxWidth === "number"
        ? DEFAULT_WIDTH_STEPS
        : DEFAULT_FULL_WIDTH_STEPS)),
  ];
  const retinaSizes = Array.from(
    // De-duplicate sizes with a Set
    new Set([
      ...baseSizes,
      ...baseSizes.map((size) => size * 2),
      ...baseSizes.map((size) => size * 3),
    ])
  )
    .sort((a, b) => a - b) // Lowest to highest
    .filter(
      (size) =>
        // Exclude sizes 10% or more larger than the image itself. Sizes slightly larger
        // than the image are included to ensure we always get closest to the highest
        // quality for an image. Sanity's CDN won't scale the image above its limits.
        size <= imageDimensions.width * 1.1 &&
        // Exclude those larger than maxWidth's retina (x3)
        size <= maxWidth * 3
    )

    // Exclude those with a value difference to their following size smaller than `minimumWidthStep`
    // This ensures we don't have too many srcSet variations, polluting the HTML
    .filter((size, i, arr) => {
      const nextSize = arr[i + 1];
      if (nextSize) {
        return nextSize / size > minimumWidthStep + 1;
      }

      return true;
    });

  return {
    // Use the original image as the `src` for the <img>
    src: builder.width(maxWidth).url(),

    // Build a `{URL} {SIZE}w, ...` string for the srcset
    srcset: retinaSizes
      .map((size) => `${builder.width(size).url()} ${size}w`)
      .join(", "),
    sizes:
      props.maxWidth === "100vw"
        ? "100vw"
        : sizes || `(max-width: ${maxWidth}px) 100vw, ${maxWidth}px`,

    // Let's also tell the browser what's the size of the image so it can calculate aspect ratios
    width: retinaSizes[0],
    height: retinaSizes[0] / imageDimensions.aspectRatio,
  };
}

And, to getImageDimensions, we can rely on its image assets' _id (asset._ref):

export function getImageDimensions(image) {
  if (!image?.asset?._ref) {
    return
  }

  const dimensions = image.asset._ref.split('-')[2]
  const [width, height] = dimensions.split('x').map(Number)

  if (!width || !height || Number.isNaN(width) || Number.isNaN(height)) {
    return
  }

  return {
    width,
    height,
    aspectRatio: width / height,
  }
}

Then, we can use getImageProps with any image, according to its maximum size in the layout:

// We call getImageProps with the raw `image` object, not the expanded asset reference.
getImageProps({
  image: {
    _key: "389dd32f5e44",
    _type: "image",
    alt: "A browser window showing another image of this website",
    asset: {
      _ref: "image-556d99f9e1be990a12c0742c62008fe3147f4bad-1430x626-png",
      _type: "reference",
    },
    crop: { /* ... */ },
  },
  maxWidth: 600
});

Initially, I posted this article with a more minimal approach, but I've since extended the function with what I personally use. I plan on abstracting this into a package and simplifying the code above to better explain the approach. In the meantime, reach out if you have questions: meet@hdoro.dev or hdorodev

Step 2: rendering the image

With the srcset, src and size values ready, we can start building the image component itself. I'll use Svelte as it's close to HTML, but you can use these principles with any web framework. Let's start with the basics:

<!-- SanityImage.svelte -->
<script>
	import getImageProps from '../utils/getImageProps';

	export let image;
</script>

<img
  alt={image.alt || " "}
  {// Pass src, srcset and sizes to the image element
    ...getImageProps({
      image,
      maxWidth: 600
    })
  }
/>

With the above, images will load and the browser will choose the proper size for them. BUT all images are loading as soon as the page loads, and what we really want is to only load them when they show up on-screen - the famous lazy loading.

In the past, I'd leverage custom lazy loading code that would hide the image until an IntersectionObserver fired when its parent showed up in the viewport. Then, I'd finally add the <img> element to the DOM and the browser would do its magic.

It worked, but it has a few accessibility and SEO concerns, as the content isn't all there for non-visual readers & bots. Thankfully, in 2022 the loading="lazy" attribute (for images, not iframes) works on all major browsers. So, with one line our images are lazily loaded ✨

<img
  loading="lazy"
  alt={image.alt || " "}
  {// Pass src, srcset, width, height and sizes to the image element
    ...getImageProps({
      image,
      maxWidth: 600
    })
  }
/>

The above won't be 100% smooth for UX, though, as the browser won't know what height the image will assume at a given width. This leads to content jumping around as images load and the browser recalculates their dimensions and the page's layout.

In the past, I'd use the padding hack to force a consistent height on the image element (or its parent) and hence prevent content from jumping around. It worked wonderfully but led to extra markup and styles that made it harder to create complex image layouts. Plus, the image component ended up much harder to reason about.

Again, it's 2022 and the browser now calculates the image's aspect ratio based on images width and height attributes (supported across all major browsers). As getImageProps is already returning width & height, all we need to do is set "height: auto" to prevent the image from being distorted! More info on this by Jen Simmons.

<img
  style="height: auto;"
  loading="lazy"
  alt={image.alt || " "}
  {// Pass src, srcset, width, height and sizes to the image element
    ...getImageProps({
      image,
      maxWidth: 600
    })
  }
/>

As an added bonus, our component is now much less tied to framework-specific features. It's literally a couple of generic JS functions and a single <img /> element with dynamic attributes.

React version:

const SanityImage = ({ image }) => {
  return (
    <img
      style={{ height: "auto" }} // could be a global style
      loading="lazy"
      alt={image.alt || " "}
      {// Pass src, srcset, width, height and sizes to the image element
        ...getImageProps({
          image,
          maxWidth: 600
        })
      }
    />
  )
}

Plain JS version:

const SanityImage = ({ image }) => {
  const { src, srcset, sizes, width, height } = getImageProps({
    image,
    maxWidth: 600
  });
  return `
    <img
      style="height: auto"
      loading="lazy"
      alt="${image.alt || " "}"
      src="${src}"
      srcset="${srcset}"
      sizes="${sizes}"
      width="${width}"
      height="${height}"
    />
  `
}

Above-the-fold, "eager" image loading

For images above the fold, such as the one in the "hero" (or header) component, you don't want to lazy load them as you want users to see them as soon as the page is loaded. The image component above could easily support this modification with a configurable loading property:

<!-- SanityImage.svelte -->
<script>
	import getImageProps from '../utils/getImageProps';

	export let image;
	export let loading = "lazy"
</script>

<img
  style="height: auto"
  {loading}
  fetchPriority={loading === "eager" ? "high" : undefined}
  alt={image.alt || " "}
  {// Pass src, srcset and sizes to the image element
    ...getImageProps({
      image,
      maxWidth: 600
    })
  }
/>

<!-- Using the above: -->
<SanityImage image={...} loading="eager" />

Notice we're adding fetchPriority="high" for eager images, which tells the browser to give preference to loading them sooner, reducing the hit on the Largest Contentful Paint performance benchmark.

Bonus: image loading transition/animation

For a nicer loading effect, we can hide the image until it's fully loaded, and then trigger an opacity transition for a subtle-yet-elegant animation. Here's how I achieve that in Svelte:

<script>
  // ...
  
  let loaded = false
</script>

<img
  ...
  data-loaded={loaded}
  on:load={() => loaded = true}
/>

<style>
  img {
    transition: .15s opacity;
  }
  img[data-loaded="false"] {
    opacity: 0;
  }
</style>

Once loaded, the browser will call the onload event, and the data-loaded attribute will become true, changing the CSS from opacity: 0 to the unset, default value of 1, creating the simple transition.

Step 3: guiding editors & enforcing accessibility

Finally, a crisp, fast-loading, and frugal image component is no good if its output is not shared across all users. To make it more democratic, guide your editors to supplement images with useful alternative descriptions. You can even make the alt fields required if your team is open to it!

// Example image schema in Sanity
export default {
  name: "image",
  title: "Image / photo",
  description:
    "💡 highest quality possible without upscaling the image (up to 2500px). If the image contains text, make sure it's highly readable with a high contrast.",
  type: "image",
  options: { hotspot: true },
  fields: [
    {
      name: "alt",
      title: "Accessibility label for the image",
      description:
        'Help make the site more accessible & SEO-friendly with a short textual description of the image, such as "screenshot of the dashboard app"',
      type: "string",
      validation: Rule => Rule.required(),
      options: {
        isHighlighted: true,
      },
    },
  ],
};

If you want to go the extra (10) mile(s), you could test an image's contrast and how friendly to color-blind people it is. I'm not sure if there's a clear way to run these tests automatically, but given Facebook has been running checks on text in ads' images for almost 10 years, I'm sure we can figure it out. I'd love to help implement something like this, reach out if you're interested: meet@hdoro.dev or hdorodev

That's it! Get in touch if you have questions or suggestions for how to further improve this image component, it'll be a pleasure to connect :)

The traditional web page is a set of sections/blocks/modules stacked on top of each other, with varying margins between elements depending on their type.

You could model this in many ways, and I've tried several over the years. In the end, it'd always become a hot mess that was hard to reason about.

With CSS custom properties, though, you specify that every child in a parent has a set margin-top based on a mg-top variable, and store all design rules in a single, concise CSS file.

/* Parent sets the margin of every child, except the
first, which should be at the top of the parent */
.layout-root > *:not(:first-child) {
  margin-top: var(--mg-top, 1em); /* 1em as the default, could be 0 */
  
  
  /* or, if you want to specify mg-top as a simple number and want to convert it to rems: */
  margin-top: calc(calc(var(--mg-top, 1em) / 16) * 1rem);
}


/* Then, each individual section inside the layout can define their own top margins */
.faq {
  --mg-top: 3rem;
  
  --mg-top: 60; /* or number only if using the calc() route above */
}
.project, .about {
  --mg-top: 120;
}
.highlighted-cta {
  --mg-top: 180; /* need more prominence? higher margin! */
}

This works flawlessly with media queries:

@media (min-width: 1024px) {
  .highlighted-cta {
    --mg-top: 240;
  }
}

And creates the perfect framework for rule-based design or Content Responsive Design:

.cta {
  --mg-top: 60;
}

/* CTAs coming after a pricing table should be closer */
.pricing-table + .cta {
  --mg-top: 20;
}

.project {
  --mg-top: 120;
}

/* No need to separate projects all that much */
.project + .project {
  --mg-top: 90;
}

I recently up with this while building Marifulness.com, it's another fruit of my exploration of leaning more heavily on CSS's capabilities. It's one of those things that you miss when going too heavy-handed on Tailwind CSS. Honestly, I think I won't use Tailwind again, just copy its pattern for useful token-based classes.

As I was exploring Andy Bell's CUBE CSS as an alternative to utility-only frameworks, I came across his approach to "flow" (in this CSSTricks video), which is essentially the same solution I arrived at. As expected, he was more insightful than me, though, and revealed:

1. the need for excluding the first child to ensure safe layouts - *:not(:first-child) (in his case, * + *)
2. and the possibility of using this as a general flow approach anywhere in your layouts - even deeply nested paragraphs in a card component, for example

With 2, the following is possible:

<main class="flow">
  <!-- Project is also a flow container -->
  <div class="project flow">
    <h2>Project name</h2>
    <p>My project description ...</p>
    <img src="..." />
  </div>
</main>

<style>
  .flow > *:not(:first-child) {
    margin-top: var(--mg-top, 1em);
  }
  .project > p {
    --mg-top: 0.5em;
  }
  .project > img {
    --mg-top: 3em;
  }
</style>

<div class="article-content flow">
  <h1>Full blog post</h1>
  <p>...</p>
  <p>...</p>
  <img src="..." />
  <h2>...</h2>
  <blockquote></blockquote>
  <ul>
    <!-- ... -->
  </ul>
</div>

<style>
  .flow > *:not(:first-child) {
    margin-top: var(--mg-top, 1em);
  }
  .article-content > blockquote {
    --mg-top: 2em;
  }
  .article-content > img {
    --mg-top: 1.5em;
  }
  .article-content > h2 {
    --mg-top: 3em;
  }
  .article-content > ul + p {
    --mg-top: 1.5em;
  }
  /* And whatever other spacing rules you may have for rich text */
</style>

If you have suggestions, reach out at meet@hdoro.dev or hdorodev :)

I've recently published the 1st version of Tapi, a visual & collaborative content modeling tool that generates Sanity.io schemas with one click. As this is my first time building a product, I'm unsure where to go next and how to reason about the journey forward.

These "lab notes" will be a collection of loose notes exploring pathways and how I feel about them.

Tapi's original sin

I started working on Tapi on January 14th, 2022, when my partner sparked the idea of using Figjam as the medium for creating content models. My first step was to open a new board and start experimenting with ways of modeling using native Figjam's tools: post-its, arrows/connectors, stickers, and comments.

I recorded the process and voiced my thinking out loud, polishing the approach very quickly. I realized that a solid workflow for diagramming content models could add the most value to the field. But, as a developer addicted to building, tinkering & automating, I wanted to create a tool that baked these decisions in and automatically exported models to target content platforms.

I think this is the source of many of my woes and indecisions. While I don't regret building the widget, I know that starting with a no-code, visual template for diagramming models would have given me more clarity in the problem space and more fluidity to test multiple approaches.

I didn't spend enough time on this conflict between tooling vs. workflows. When I learned about Figjam widgets, the builder in me went wild, and tooling won. The UX design phase began based on ~2hr of research and experimenting 🙈

And, well, it's easy to see in retrospect that this original sin is seeping into the rest of the work.

Where I'm at: confusion

Tapi is launched, and it's helpful to a handful of people. I've had really heart-warming messages coming my way from enthusiasts of content modeling & infinite canvases, but very little actual usage (that I know of, I don't do analytics).

I have a clear road I could follow to make it more useful and start generating revenue:

1. Create a library of pre-made content models that users can add to their projects to build faster
2. Start charging per project export - either monetarily or by submitting a model to the library (crowdsourcing of content)
3. Get a better sense of the content world
   1. Read Carrie Hane's Designing Connected Content
   2. Watch Marcelo Lewin's Content Modeling Weekly screencasts
   3. Dive deep into content strategy medium (Twitter, conferences, what else?)
   4. Get together and interview multiple content designers
4. Research how to better communicate the pieces of a model
   1. What should a field/attribute be called?
   2. How to explain "documents" and "blocks"? Are there better names?
5. Bake in content design best practices & workflows
   1. How to bake the transition from high-level, title-cased work (which models are there, how they relate) to low-level definitions (which fields exist, their types & validation, etc.)?
   2. What editing UI concerns should be defined in Tapi? For example, should it expose field descriptions, or whether or not a plain text field should have multiple lines?
   3. How deep should be the customization of validation options? Right now it's either required/optional, but content people often talk about text's length very early in the process, for example. What else should be included?
6. Polish papercuts and fix UX/UI issues
7. Marketing mode!
   1. Use Tapi as a learning tool in my Sanity mentoring sessions
   2. Produce content on creating content models with Tapi
   3. Seek partnerships such as sponsoring Marcelo Lewin's weekly screencasts or offering affiliate links/coupons
   4. Give talks and show up in the public sphere
   5. Dedicated website with documentation, testimonials, storytelling, etc.
   6. Paid advertising?

Of course, this is an untested road. I won't know if it works until I actually do it. However, I have a strong hunch that this would lead to success, in my own definition of it - income enough to pay my meager bills and strong connections with interesting people.

BUT that's where the original sin comes in: I'm not super stoked about content strategy as a problem space. I do it when I need it, and I enjoy it - it was a blast discussing the content model for the Sanity.io Exchange, and that's still the satisfaction peak of my career.

My connection to structured content, however, is intuitive and based on my limited experience, and I don't feel a calling to become an intellectual on it. Point #3 above on diving deep into the field gives me all sorts of weird sensations in my stomach and throat.

Rationality tells me to pursue it:

1. "This is a field prepped for growth. Here comes stable income! 🤑" (career stability, "success" for the outside world, ego)
2. "Committing myself to this goal would make me a better human & professional"
3. "I can contribute a lot to the field, and hence to humanity, by helping establish industry-wide standards"
4. "You'll never be successful if you can't even establish & grow a tiny tool in a tiny niche like this"

But my body & soul ask me to treat this less seriously, to bring more play into Tapi, to focus on developers & designers instead of principles-based content strategists. If I follow my desire, I'll build a bunch of features that I personally find "cool" (either as a user or the problem solver building it). And I'll throw a bunch of effort down the sink.

Conclusion

So yeah, debating which features to build, how to approach the market, or any other "hard thinking" isn't what's at stake for lab note #1. My relationship with this project is.

Right now, I feel a very strong trichotomy between focusing on developers (speed, 2-way binding to code), content strategists (processes and people), or educators (visual clarity, great onboarding). I'm not inclined to focus on either but fear that the middle ground won't take me anywhere.

My biggest fear is to have thrown hundreds of hours away just to create a nice demo that makes for a popular tweet but doesn't help anyone.

I'll let this simmer a bit, bringing it up in conversations, meditations & journal writing.

If you have strong opinions, I'm all ears (or eyes) at meet@hdoro.dev or hdorodev. I'm also open to collaborating 😉 (thanks for reading!)

From a high-level, the process is simple:

1. Create a Sanity client with your project's configuration
2. From SvelteKit's endpoints, use this client to fetch data with GROQ
3. Render this data with Svelte from the endpoint props passed to pages
4. Ensure the data is there before rendering pages

Let's get into the specifics - you can also follow my video going through this process step-by-step.

Creating the Sanity client

Start by installing @sanity/client in your SvelteKit project:

npm i @sanity/client
# or yarn add

Then, create a sanityClient.js|ts file exporting a configured client with your project's info.

// sanityClient.js
import sanityClient from "@sanity/client";

const client = sanityClient({
  projectId: "YOUR_PROJECT_ID",
  dataset: "YOUR_PROJECT_DATASET",
  apiVersion: "2022-03-24", // choose the API version you want
  useCdn: true,
});

export default client;

Refer to @sanity/client's documentation for the options you configure. Put this file where you can access from routes - most SvelteKit apps have the src/lib folder configured with a $lib alias, which is a great option.

You can also configure the client with SvelteKit's environment variables if you don't want to have project tokens in the code or need to have different test environments.

Fetching Sanity data from endpoints

Assuming you have a homepage at src/routes/index.svelte that you want to feed with Sanity content, create a src/routes/index.js|ts file to fetch data for this page - this will be your page endpoint.

For data fetching, we want to use the get function and use our Sanity client to run a GROQ query that picks exactly the desired data:

import client from "../sanityClient";

export const get = async () => {
  const genuses = await client.fetch(/* groq */ `*[
    _type == "genus"
  ][0..10]{
    _id,
    name,
  }`);

  return {
    body: {
      genuses,
    },
  };
};

To make sure the above is working, you can add a console.log before returning the endpoint's body. If the data is undefined or null, make sure your client configuration is right and test your GROQ query in the Sanity studio's Vision plugin.

You can also have route-dependent data by accessing a route parameters. Here's an example for the routes/genuses/[_id].js endpoint:

import client from "../../sanityClient";

export const get = async (event) => {
  // Access the _id from the params object ✨
  const { _id } = event.params;
  const genus = await client.fetch(
    /* groq */ `*[
      _type == "genus" &&
      _id == $_id
    ][0]`,
    { _id }
  );

  if (!genus?._id) {
    return {
      status: 404,
    };
  }

  return {
    body: {
      genus,
    },
  };
};

Rendering data in pages

In the SvelteKit page route that matches the page endpoint above, add export let PROP_NAME for all of the props you return in your get function's body. Now you can access your data in your front-end 🎉

<script>
  export let genuses = [];
</script>

<ul>
  {#each genuses as genus}
    <li>
      <a href={`/genuses/${genus._id}/`}>{genus.name}</a>
    </li>
  {/each}
</ul>

Warning: check data's validity before rendering pages

In the genuses/[_id].js endpoint example above you'll notice I return a { status: 404 } if there's no genus returned from Sanity. This makes sure a request to my-site.com/genuses/a-fake-genus-that-doesnt-exist would return a 404 instead of a blank or broken page.

When working with dynamic content, it's a good practice to always check if the keys you expect are there and their values are valid. It's often the case that a reckless component doesn't do these checks, accessing something like optionalObject.property and ends up leading its parent page to a 500 as Javascript throws an error.

And that's it! Reach out if you have any questions meet@hdoro.dev or hdorodev

Here's the high-level view of how to do Sanity pagination with GROQ:

1. define a filter for the documents you need to fetch
2. limit them with query slices
3. paginate by changing the number in the slices
4. and keep tab of the total page count to properly display the pagination UI in the front-end

Querying paginated data

Now, let's tackle this in practice. Let's assume you have a feed of content, which you fetch like so:

*[
  // A multi-content feed
  _type in ["news", "thought", "poem", "event"] &&
  !(_id in path("drafts.**")) &&
  defined(slug.current) &&
  status == "published"
]
// Editor-picked & popular come first
| score(editorPick, popularity)
// Freshest and hottest first
| order(_score desc, _createdAt desc)

The first thing you need to do is to extract the query filter into a re-usable fragment so that you can use it consistently across the places we'll need it (see the pagination UI section below).

export const COLLECTION_FRAGMENT = /* groq */ `
*[
  _type in ["news", "thought", "poem", "event"] &&
  !(_id in path("drafts.**")) &&
  defined(slug.current) &&
  status == "published"
]
`;

With this, you can build the most obvious part of your query, the one that gets the actual data:

const ITEMS_PER_PAGE = 10;

const myData = await sanityClient.fetch(
  /* groq */ `{
  "items": ${COLLECTION_FRAGMENT}

    // === ORDERING THE COLLECTION ===
    // Editor-picked & popular come first
    | score(editorPick, popularity)
    // Freshest and hottest first
    | order(_score desc, _createdAt desc)
    
    // === SLICING THE COLLECTION ===
    [($pageIndex * ${ITEMS_PER_PAGE})...($pageIndex + 1) * ${ITEMS_PER_PAGE}]
    {
      ..., // your item data projection here
    }
  }`,
  // == Query parameters ==
  {
    // Let's get the first page
    pageIndex: 0,
  }
);

See how above we're simply appending the scoring & ordering operators after the filter fragment? It may be hard to grasp at first, but it helps to remember that GROQ runs sequentially and we can chain our operations.

In the snippet above we're already slicing up our collection to get only the amount defined by our ITEMS_PER_PAGE variable. Let's break that line down:

// === SLICING THE COLLECTION ===
const ITEMS_PER_PAGE = 10;

// Notice the difference between the GROQ variable ($pageIndex)
// and the javascript constant (${ITEMS_PER_PAGE})
const slice = `[($pageIndex * ${ITEMS_PER_PAGE})...($pageIndex + 1) * ${ITEMS_PER_PAGE}]`

// ITEMS_PER_PAGE is fixed/constant, so we could inject it in the query directly
const sliceWithParam = `[($pageIndex * 10)...($pageIndex + 1) * 10]`

// Now, let's add a parameter to the query
const myData = await sanityClient.fetch(
  "QUERY_HERE",
  // == Query parameters ==
  {
    pageIndex: 0,
  }
);

// Injecting the parameter in the query...
const sliceWithValue = `[(0 * 10)...(0 + 1) * 10]` // or [0...10], AKA the first 10 items

If the above isn't clear, going through my GROQ course's section on slices may help 😉

Now, all you need to do is change your pageIndex parameter and you'll get the proper data for each page ✨

Powering the pagination UI

In order to build a pagination widget or an infinite scrolling mechanism that users can interact with, you'll need to know how many pages there are available.

This is where our re-usable filter fragment comes in handy. We can create a pagination object with the current pageNumber and totalPageCount in our GROQ query:

const myData = await sanityClient.fetch(`{
  "items": {
    // Our previous item query here
  },
  "pagination": {
    "totalPageCount": count(${COLLECTION_FRAGMENT}._id) / ${ITEMS_PER_PAGE},
    "pageNumber": $pageIndex + 1,
  }
}`,
  // == Query parameters ==
  {
    // Let's get the first page
    pageIndex: 0,
  }
);

Now, you can buid any pagination UI you desire (you'll need to round totalPageCount, though)!

If you're designing the UI, do check out Smashing Magazine's article on designing better infinite scroll, which covers well the distinction and trade-offs between traditional pagination links and endless feeds.

Back/front-end example with SvelteKit

If you're still wondering how to implement the full flow, this SvelteKit implementation may be a good reference. I'm doing traditional pagination, but infinite scrolling would have a similar approach, except querying from an API endpoint on the client-side.

First, let's create a route under routes/page/[pageNumber].svelte:

<script lang="ts">
	import PaginationUI from '$lib/components/PaginationUI.svelte';
	import PostsGrid from '$lib/components/PostsGrid.svelte';
	import type { PaginationData, PostCardProps } from '$lib/types';

	export let posts: PostCardProps[] = [];
	export let pagination: PaginationData;
</script>

<h1 class="page-title">Posts</h1>

<PostsGrid {posts} />

<PaginationUI {pagination} />

To get the posts and pagination data this route depends on, we'll create a page endpoint at routes/page/[pageNumber].ts:

import { client } from '$lib/client';
import { PAGINATION_FRAGMENT, POST_LIST_QUERY, SETTINGS_QUERY } from '$lib/queries';

export const get = async ({ params }) => {
	const pageNumber = params.number ? Number(params.number) : 1;
	const data = await client.fetch(
		`{
		"posts": ${POST_LIST_QUERY},
		"settings": ${SETTINGS_QUERY},
		"pagination": ${PAGINATION_FRAGMENT}
	}`,
		{
			pageIndex: pageNumber - 1
		}
	);
	
	if (!data.posts?.length) {
	  return {
	    status: 404
	  }
	}

	return {
		body: {
			...data,
			pagination: {
				...(data.pagination || {}),
        // Assume totalPageCount is at least 1, and round it up
				totalPageCount: Math.ceil(data.pagination?.totalPageCount || 1)
			}
		}
	};
};

And, if you're wondering, here's my minimal, unstyled PaginationUI component:

<script lang="ts">
	import type { PaginationData } from '$lib/types';
	import { getPathFromSlug } from '$lib/urls';

	export let pagination: PaginationData;

	$: getPaginationHref = (pageNumber: number): string => {
		if (pageNumber <= 1) {
			return '/';
		}

		if (pageNumber >= pagination.totalPageCount) {
			return getPathFromSlug(`page/${pagination.totalPageCount}`);
		}
		return getPathFromSlug(`page/${pageNumber}`);
	};
</script>

<div>
	<a
		href={getPaginationHref(pagination.pageNumber - 1)}
		disabled={pagination.pageNumber - 1 <= 0}
		rel={pagination.pageNumber === 1 ? 'current' : undefined}
		class="nav-link"
	>
		Previous
	</a>
	<span>
		Page {pagination.pageNumber} of {pagination.totalPageCount}
	</span>
	<a
		href={getPaginationHref(pagination.pageNumber + 1)}
		disabled={pagination.pageNumber + 1 > pagination.totalPageCount}
		rel={pagination.pageNumber >= pagination.totalPageCount ? 'current' : undefined}
		class="nav-link"
	>
		Next
	</a>
</div>

SvelteKit bonus: parameter matching

SvelteKit recently landed support for parameter matching to verify if a given parameter value is valid for a given route or not.

params/pageNumber will ensure page numbers can only be positive integers:

import type { ParamMatcher } from '@sveltejs/kit';

export const match: ParamMatcher = (param) => {
	return /^\d+$/.test(param) && Number(param) > 1;
};

And with this we can update our route's filenames to be [number=pageNumber], so if page/im-not-a-number or page/-130 get requested SvelteKit will immediately return a 404.

The easiest way to provide web previews for Sanity.io content: fetching the draft version of documents if the requested URL includes a ?preview=true query parameter.

Here's an example with SvelteKit for a blog post route handler:

import { sanityClient } from '$lib/client';

// If requests include a ?preview=true query parameter, we're in preview mode
export function isPreview(request) {
	return Boolean(request.url.searchParams?.get('preview'));
}

export const get = async (event) => {
	const { slug } = event.params;
	const data = await sanityClient.fetch(/* groq */`{
    "post": *[
			_type == "post" &&
			slug.current == $slug
      // If not in preview, only show published documents
			${isPreview(event) ? '' : '&& !(_id in path("drafts.**"))'}
		]
		${
			isPreview(event)
				? // In preview, get draft if existent - it'll have the freshest _updatedAt
				  '| order(_updatedAt desc)'
				: ''
		}	
		[0]{
			..., // your query here
		},
  }`,
		{ slug }
	);

  if (!data.post?._id) {
    return {
      status: 404
    }
  }

	return {
		status: 200,
		body: data,
	};
};

The three main parts of the code above:

• We define if we're in preview mode by checking the "preview" query parameter and converting it to a boolean
• If we're not in preview, exclude draft documents (!(_id in path("drafts.**")) in the query's filter)
• If we are in preview, give preference to drafts
  • We could query only drafts, but if the document was published and didn't have a draft, the page would return a 404.
  • Instead, we order all documents that match the given slug by their _updatedAt value. As drafts are the freshest, they'll always show up first.
  • However, if no draft is present, the published version will show up.

Accessing previews from the Sanity studio

To replicate the UI above, you can use Simeon Griggs' great sanity-plugin-iframe-pane and add it as a custom view to previewable documents.

If you don't have a custom structure builder, start by following the official docs on custom document views.

// /deskStructure.js
import S from '@sanity/desk-tool/structure-builder';
import { EarthGlobeIcon, EditIcon } from '@sanity/icons';
import Iframe from 'sanity-plugin-iframe-pane';

// Replace with your own approach to getting the URL for each document
function resolveProductionUrl(document) {
	return slugToAbsUrl(
		getDocumentPath({
			_type: document._type,
			slug: document.slug?.current
		})
	);
}

// Example where only the homepage, case studies & posts are previewable
const previewableTypes = ['home', 'caseStudy', 'post'];

/**
 * Defines views/tabs for each content type.
 */
export const getDefaultDocumentNode = (props) => {
	if (!previewableTypes.includes(props.schemaType)) {
		return S.document().views(S.view.form());
	}

	return S.document().views([
		S.view.form().icon(EditIcon),
		S.view
			.component(Iframe)
			.options({
				defaultSize: 'desktop',
				url: (doc) => resolveProductionUrl(doc) + '?preview=true',
				reload: {
					button: true
				}
			})
			.icon(EarthGlobeIcon)
			.title('Preview')
	]);
};

Want to have live previews that change as users edit? In my experience, this is more of a wasteful distraction than a useful feature - I want to focus on writing most of the time and only check how it'll visually look every once in a while.

But, if that's your jam, you can pass the document's _rev version id as a separate query parameter in the URL to constantly refresh the iFrame as users edit the content.

S.view
  .component(Iframe)
  .options({
    defaultSize: 'desktop',
    url: (doc) => resolveProductionUrl(doc) + `?preview=true&_rev=${doc._rev}`,
    reload: {
      button: true
    }
  })
  .icon(EarthGlobeIcon)
  .title('Preview')

---

And that's it! You'll need to change your GROQ queries slightly, but compared to changing components and creating dedicated preview routes, this method is much simpler than my previous iteration 😊

RegEx is notoriously hard ¹ to write and maintain after a certain threshold of complexity.

In building a regular expression to parse Wordpress shortcodes, I went way beyond the simplicity boundary, and had to come up with a few tricks to help me make the code easier to write and simpler to maintain:

1. Use named capture groups
2. Split the expression in smaller sub expressions
3. Use extensive, recipe-like documentation of how each sub-part works

Take the raw RegEx below:

// Good luck debugging this 10+ min after your write it
const myMagicalRegex =
  /\[([a-z][\w\d_\*-]{1,})(?:\s{1,}([^\]]{0,})){0,1}\](?:((?:(?!\[\/\1\]).)*)\[\/\1\]){0,1}/gmu;

I'm convinced that even those who work daily with complex regular expressions will have a hard time reading / parsing this. Here's the alternative, implementing the 3 principles above:

/**
 * Shortcode names are made up of lowercase words/digits/asterisks, separated by hyphens and underscores.
 *
 * Rules:
 *  - no whitespace
 *  - can include words, digits, hyphens, underscores & asterisks
 *  - must start with a lowercased letter
 *
 * Examples: popup, wcf7-contact-form,  vc_columns,  text*
 */
const nameExp = /(?<name>[a-z][\w\d_\*-]{1,})/; // Group #1
// 👆👆👆 Example of a named capture group

/**
 * Attributes come in all shapes and sizes, but as a group they must always be preceded by a whitespace.
 * Right now I'm accepting anything that isn't a closing bracket "]".
 * @TODO: how to handle closing brackets in attributes' values?
 *
 * Examples:
 *  - Strings: title="Not" padding_bottom="0px"
 *  - Numbers: width=100 id=30
 *  - Numbers as strings: width="100" id="30"
 *  - Attribute name IS the value: [textarea mensagem] [text* your-name]
 */
const attributesExp = /(?:\s{1,}(?<attributes>[^\]]{0,})){0,1}/; // Group #2

/**
 * Include everything inside the shortcode, if any.
 *
 * Breaking it down:
 * 1. we wrap it in a non-capturing group (?:) to check how many times the full match happens.
 *  - (?:ACTUAL_CONTENT_REGEX){0,1}
 *  - Content can occur either 0 or 1 times as not all shortcodes have content.
 * 2. The actual content is wrapped in a named capture group (?<content>)
 *  - The content will be whatever (`.`) isn't the closing shortcode bracket (see 3. below)
 *  - The usage of negative lookahead (?!) is explained here: https://stackoverflow.com/a/8057827
 *  - @TODO: better understand this portion
 * 3. The content *must* finish with the closing shortcode bracket
 *  - we backreference the captured "name" group (group #1 above -> \1)
 *  - as we know the bracket will close like [/shortcode-name], we can test for \[\/\1\]
 */
const contentExp = /(?:(?<content>(?:(?!\[\/\1\]).)*)\[\/\1\]){0,1}/; // Group #3

// 👇👇👇 The final shortcode is built from 3 manageable sub-expressions
const shortcodeRegExp = new RegExp(
  `\\[${nameExp.source}${attributesExp.source}\\]${contentExp.source}`,
  "gum"
);

Sure, it's extensive and isn't perfect. RegEx remains a big challenge for me, but now I feel more capable of tackling harder problems with it (and this confidence is bearing fruit!).

I had a couple of bugs with this expression a few days/weeks after the first implementation, and was capable of fixing them with relative ease. At least I know that, years from now, it'll be clear where to start debugging, and that's a huge win!

Bonus tip for JS: when consuming the RegEx matches, use array de-structuring to name matches just like your capture groups:

"...".replace(
  shortcodeRegExp,
  (match, ...groups) => {
    // Keeping in mind the capture group order in the expression,
    // we know what's each group in the final match 👇👇👇
    const [name, rawAttributes, content] = groups;

    // Then we can use it freely
    const attributes = parseShortcodeAttributes(rawAttributes);
    const shortcode = { name, attributes, content };

    if (IsShortcode?.(shortcode) === false) return match;
    
    // ...
  }
);

If you have other tricks for writing, understanding and maintaining RegEx, do reach out!

There are many ways to limit the size of a given piece of content - a process usually called truncation or clamping. CSS Tricks has a bunch of interesting approaches and there are tons of libraries out there to do it, from lodash.truncate to React-specific components to thousands of others.

I started doing this with the naive str.slice(0, maxLength) + "...", but that will add ellipsis even to text that is smaller than maxLength.

Adding a if (str.length < maxLength) return str conditional is a good step, but then you'll find some words are truncated in hal...

Frustrating, right?

To fix this, I created this crazy complex function that would increase the truncated string until it found a whitespace, at which point it'd return to ensure only whole words were displayed. It worked across many projects for over a year, but felt kinda yucky.

Now that I'm a little more comfortable with RegEx I figured that there must be a better way. The answer came through the power of String.prototype.search():

export function truncate(str: string, maxLength: number) {
  if (str.length < maxLength) {
  	return str;
  }
  
  // To prevent truncating in the middle of words, let's get
  // the position of the first whitespace after the truncation
  const firstWhitespaceAfterTruncation = str.slice(maxLength).search(/\s/) + maxLength;
  
  return str.slice(0, firstWhitespaceAfterTruncation) + '...';
}

11 lines of code including comments and tons of whitespace! I'll definitely drag this around all of my projects - hope it's useful to you :)

PS: technically I'm not respecting the maxLength in this code, but I'm okay with the small deviation this brings.

If you must have maxLength as the absolute maximum length of strings, you could use String.matchAll() to check the index of the last whitespace right before the original target truncation, and use that as the value for str.slice(0, truncationTarget) 😉

I've used Javascript Sets to de-duplicate items in an array for a few years, but I never understood it beyond that. It felt like one of those obscure language features that would never fully make it into my programs...

// My only usage of sets so far
const uniqueTags = Array.from(new Set(tags))

But reading Russ Olsen's Getting Clojure (which is super well written and fun, by the way!), I casually came upon this line:

Since sets are all about membership, the main thing you can do with them is discover if this or that value is in the set.
(Page 32)

And then it dawned on me: Sets are solely a collection of unique values, so there's no better tool for these use cases it specializes in.

Use-case #1: checking if item is in collection

Set.has is faster than Array.includes:

// With Arrays
const singletonTypes = ['home', 'settings']
const isSingleton = singletonTypes.includes(doc._type)

// With Sets - faster
const singletonTypes = new Set(['home', 'settings'])
const isSingleton = singletonTypes.has(doc._type)

Of course, with few items this is negligible. But this could be a performance opportunity when there are hundreds, thousands of items in a set that is being checked multiple times per second, such as the render method of hundreds of a React/Svelte components.

Use-case #2: ensuring collection has no duplicates

This is way easier with sets:

// With arrays, you manually need to check if item isn't already there
if (!singletonTypes.includes('settings')) {
  singletonTypes.push('settings')
}

// With Sets
singletonTypes.add('settings') // if already exists, it'll be skipped

Issues with Sets

• Set order is according to time of addition and you can't overwrite this behavior
  • Arrays are still the go-to option for tightly ordered lists of values
• Sets aren't immutable like in Clojure and they aren't as easy to make immutable like Arrays, so be careful of side-effects in seemingly innocent contexts
• Sets are rare in most real-world JS, so your code may end up more complicated and inaccessible to beginners than needed

So... yeah, I'm not convinced I'll actually use sets, but now I know how it could be useful. I feel slightly more capable with the language 😊

Bonus: sets are a mathematical concept

These come from the mathematical model of sets. That thing we used in school exercises to denote that a given variable was a real number, α ∈ R, is a practical use of sets.

And reading the Wikipedia article on Sets, I discovered where the term "singleton" came from! It's the sole item in a mathematical set. Next time I create a singleton in my content model, I'll definitely think of Sets.

This is my first "real-world" example of how much programming is based on Mathematics, I'm hooked!

Next up is getting a good grip on Map - but that's a challenge for another time.

JSON, being such a flexible and widespread format, is commonly used by Static Site Generators (SSGs) to feed data into their HTML templates. This is the case of Hugo, Eleventy, Jekyll, Bridgetown and most others from the 330+ generators listed in jamstack.org.

Thankfully, Sanity.io is JSON-first. Your data is stored in it, GROQ (the querying language for fetching from your dataset) understands JSON natively, and even your content models are defined through Javascript objects!

Here's the high level view of how to create JSON files from Sanity data during builds to feed SSGs:

1. Run a script before the SSG builds
2. This script will connect to Sanity through one of its client libraries
3. Fetch data from the GROQ queries you define
4. Save those to the proper files in disk
5. Then run the generator's process and access the data from your templates

Keep in mind that 1. could happen in a process native to your generator, such as ElderJS's bootstrap hook and Eleventy's many data fetching approaches.

Below is my current go-to script for doing 1-4 in NodeJS with the @sanity/client package:

// NodeJS-based GROQ queries that are persisted into the filesystem
import sanityClient from "@sanity/client";
import fs from "fs";
import path from "path";

// @TODO: Update with your project's config
const client = sanityClient({
  projectId: "tvkfaenh",
  dataset: "production",
  apiVersion: "v2022-02-26",
  // As this runs in a static generation context, we can afford not using the CDN to always get the freshest data
  useCdn: false,
});

// @TODO: write your GROQ queries here
const QUERIES = [
  {
    filename: "genus.json",
    query: `*[_type == "genus"]`,
  },
  {
    filename: "homepage.json",
    query: `{
      "hero": *[_type == "homepage"][0],
      "genus": *[_type == "genus"][0..3],
      "settings": *[_type == "settings"][0]
    }`,
  },
];

const promises = QUERIES.map(({ filename, query }) => {
  return new Promise(async (resolve, reject) => {
    try {
      // 1. Get the data from Sanity
      const data = await client.fetch(query);

      // 2. Save that as JSON to disk
      fs.writeFileSync(
        path.join("data", filename),
        JSON.stringify(data, null, 2)
      );
      resolve(true);
    } catch (error) {
      console.error(`${filename} went wrong`, error);
      reject();
    }
  });
});

async function getData() {
  await Promise.allSettled(promises);
}

getData();

If you aren't comfortable with it, my interactive article on GROQ may help! Let me know if you have questions or improvements to the script above meet@hdoro.dev or hdorodev 😊

Using the data in SSGs

Each generator will have its own approach to loading & using data into it. Some examples:

• Hugo & Eleventy automatically insert data into templates from JSON files in the data directory
• Jekyll, Bridgetown & Hexo have the _data folder

More commonly, generators like ElderJS, Astro and full-stack frameworks like Next, Nuxt, SvelteKit & Remix have their bespoke ways of loading data on a per-route or per-request basis. The method I describe above isn't recommended for these stacks as you'd be over-fetching data from loading all content for every page.

Do reach out if you have questions about specific integrations, it'd be a pleasure to help! You can book a free mentoring session here 😉

I recently built a couple of RSS feeds - one for my own site (thanks to Ollie for the request) and another for my partner's. This is how I approached it.

Getting the right data

Each feed is going to vary according to their site's content structure. Start by identifying which document types you'll display and how their data translates into feed items' schema:

// Data format for items in the "feed" npm package (Typescript)
export interface Item {
    title: string;
    description?: string;
    id?: string;
    link: string;
    date: Date;
    content?: string;
    category?: Category[];
    guid?: string;
    image?: string | Enclosure;
    audio?: string | Enclosure;
    video?: string | Enclosure;
    enclosure?: Enclosure;
    author?: Author[];
    contributor?: Author[];
    published?: Date;
    copyright?: string;
    extensions?: Extension[];
}

At the very minimal, you'll need to add a title, date, and link to your entries. description is a nice addition, if possible.

Data-related tips:

• Important: links must be absolute, including the HTTP protocol -> "https://hdoro.dev/my-post" instead of "/my-post"
• id can be the same as link
• If you have multiple document types, add a category to differentiate them
• Have editor-defined publishedAt and/or updatedAt fields to allow controlling when readers get updates about each piece

From the decisions above, build a single GROQ query to get all the data you'll need for items and make sure it runs properly (if you aren't comfortable with it, my interactive article on GROQ may help!). Here's an example from Mari's site, which exposes case studies and blog posts in a single feed:

{		
  // You could also have separate sub-queries for each document type.
  // I have them in a single one for simplicity given they're very similar.
  "entries": *[
    _type in ["post", "caseStudy"] &&
    defined(slug.current) &&
    !(_id in path("drafts.**"))
  ]{
    _type,
    // Notice how I'm already massaging all the data in GROQ,
    // getting the most desirable value for each property.
    "publishedAt": coalesce(publishedAt, _createdAt),
    "updatedAt": coalesce(updatedAt, _updatedAt),
    "slug": slug.current,
    "image": coalesce(seo.ogImage, image, images[0]),
    "title": coalesce(seo.title, title),
    "description": coalesce(seo.description, subtitle),

    // type-specific values
    _type == "post" => {
      "category": "Articles",
    },
    _type == "caseStudy" => {
      "category": "Case Studies",
      services,
    },
  }[]|order(updatedAt desc), // finish by ordering them

  // Global settings for the feed configuration (see below)
  "settings": *[_id == "settings"][0]{
    ${SETTINGS_FRAGMENT}
  },  
}

Data for the feed configuration

Aside from specific items, you'll also need to add general information to your feed, such as its title, description, language, copyright, etc.

Some of this information will be inherently static (such as favicon, the root link, and copyright), but others should probably come from Sanity itself to allow more control to editors (title, description could be updated, for example).

For this, I highly recommend creating a global settings document and querying it in your GROQ query (as I'm doing in the code above).

Decision: full text or not?

You could add the full content of each entry to your feed, which many readers prefer as it allows them to do all their reading in one app without having to visit each source website.

Personally, I'd rather have people read on my own website for various reasons - design & vibe, branding, owning the medium, opening up for dynamic elements in the middle of written content, etc.

Whatever you choose, keep in mind that providing the full content will require you to convert PortableText data, with all of your custom block types, annotations and styles, to plain text or HTML.

This can be a time-intensive if you use front-end frameworks such as React & Svelte, as you won't be able to use your component code without first using the framework's rendering API directly to get the HTML. Then we start getting into bundling issues and other complications that make the process sour very quickly.

Once you're comfortable with the data format you're getting, let's generate the actual feed!

Generating the feed

As I mentioned above, the npm package feed takes care of generating the XML for me. I've used it both in SvelteKit and in NextJS, and the approach is pretty much the same:

1. Create an API endpoint
2. Fetch Sanity.io data according to what you require in the step above
3. Configure the feed
4. Add each entry to it
5. Export to XML
6. Finish the request with the proper headers

Here's the simplified code for a SvelteKit GET route, properly commented for the most important bits:

export const get = async () => {
  // 1. ===== FETCHING DATA =====
  // See the query in the section above
  const { settings, entries } = await sanityServerClient.fetch(QUERY);

  // 2. ===== CONFIGURING FEED =====
  const author = {
    name: "Mari Moraes",
    email: settings.email,
    link: BASE_URL,
  };
  const feed = new Feed({
    title: "Marifulness",
    description: settings.feedDescription,
    id: slugToAbsUrl("/"),
    link: slugToAbsUrl("/"),
    language: "en",
    // Will get to safe image in a bit!
    image: getSafeImage(settings.ogImage),
    favicon: BASE_URL + "/favicons/apple-icon-72x72.png",
    copyright: `All rights reserved ${new Date().getFullYear()}, Mari Moraes`,
    updated: entries?.[0] ? new Date(entries[0]?.updatedAt) : undefined,
    author,
  });

  // 3. ===== ADDING ENTRIES =====
  entries.forEach((entry) => {
    const url = slugToAbsUrl(getDocumentPath(entry));
    feed.addItem({
      title: entry.title,
      description:
        entry.description ||
        // alternative description for case studies
        new (Intl as any).ListFormat("en").format(entry.services || []),
      published: new Date(entry.publishedAt),
      id: url,
      link: url,
      date: new Date(entry.publishedAt),
      image: getSafeImage(entry.image),
      author: [author],
      category: [
        {
          name: entry.category,
        },
      ],
    });
  });

  // 4. ===== GENERATING THE XML =====
  const xml = feed.rss2();
  return {
    status: 200,
    body: xml,
    headers: {
      "Content-Type": "application/xml",
    },
  };
};

Beware of images

For some reason, XML is picky about its URLs and apparently can't handle query params (not 100% of this!). As Sanity images depend on query parameters to define their width, height, cropping, etc., we need to sanitize them before adding to the feed. Here's how I'm doing it:

/**
 * XML is picky about its URLs and can't handle query params.
 * As our images require those, we need to encode them first
 */
function getSafeImage(image?: SanityImageRef) {
	try {
		const imageUrl = image
			? imageBuilder.image(image).fit('max').auto('format').maxWidth(1200).url()
			: undefined;
		return `${imageUrl.split('?')[0]}?${encodeURIComponent(imageUrl.split('?')[1])}`;
	} catch (error) {
		return undefined;
	}
}

The route code above has a few examples of how I use this getSafeImage function 😉

Style your feed

By default, RSS feeds are only readable to machines. If you want to make it also readable by humans, you could follow Matt Webb's AboutFeeds template and style it. Here's how I'm doing it from my adapted XSL stylesheet:

// Add the stylesheet attribute right below the first line of the XML
const FIRST_LINE = `<?xml version="1.0" encoding="utf-8"?>`
const xml = feed
  .rss2()
  .replace(
    FIRST_LINE,
    FIRST_LINE +
      '<?xml-stylesheet href="/rss-styles.xsl" type="text/xsl"?>',
  )
res.status(200).setHeader('Content-Type', 'application/xml').send(xml)

Publishing your feed

Now that you have the proper feed being generated, make sure to add it to your website and other mediums you want to advertise it on. Suggestions:

1. Add a link to it from the website's footer
2. Add a link tag to your feed from the HTML's head
   1. Example: <link rel="alternate" type="application/rss+xml" href="https://hdoro.dev/feed.xml">

That's it! Hope you find this useful :)

I would love to use Cloudflare Workers for hosting all of my work - from static sites to highly dynamic SvelteKit applications. They have the best performance of any serverless platform with 0ms cold starts (with improvements coming often!), are affordable & powerful, and, most importantly, are aware of their responsibility with the planet and actively work on improving the sustainability of their products.

They allow you to set your worker to only run in servers powered by renewables, are certified by the The Green Web Foundation and even provide carbon emission reports to educate clients on the impact of their web properties. You can say I'm a fan.

BUT, given the architecture of their platform, adopting Workers isn't as straightforward as I'd love it to be. The Javascript code you ship to it runs on the V8 engine, similar to Node & Chromium browsers, but it doesn't expose many of the APIs these two have. This makes it so you can't use many packages common in modern JAMstack development:

• dotenv breaks it as it requires fs, a Node API
  • 💡 You can get around this with dotenv-cli, though
• Popular database adapters, such as @supabase/supabase-js, use XMLRequest (not supported in Workers) to handle fetch requests in older browsers
  • For Supabase specifically, the official example for integrating with Workers relies on using patch-package in a postinstall script to modify cross-fetch, one of its dependencies. If you update your packages, you have to do it all over again - not the best experience!
  • I've experimented with the process above inside a slightly complex SvelteKit handler in this repository, and it almost worked! My future self will probably come back to try to fix the last bits.
• Many libraries reference window, a browser-only object

In short, you'll have to be extra careful about your usage of npm packages, and publishing any non-trivial project that will certainly face dependency issues.

There's also the clunky deployment process - I'd need to set-up a GH action to do deployments or do it manually from my machine, both which involve extra work when compared to Vercel, Netlify or Workers' cousin, Cloudflare Pages.

Cloudflare Pages is actually a big step up for them, and will soon power this very blog. However, it's suitable solely for purely static sites, such as those powered by Astro or ElderJS, as it doesn't (yet?) integrate seamlessly with Workers. You need to have two separate processes for deploying the front-end and the dynamic API, which removes the possibility of deploying a NextJS or SvelteKit app using a mix of static and server-rendered routes.

I imagine they're working on solving these issues as I write this, and I trust they'll come around with better solutions for these problems. In my experience, their products and communication are usually very confusing and the UX isn't the best, but the fact that Cloudflare Pages offers a really smooth flow is a sign they're about to change that. They're probably seeing Vercel's success with all of the focus on Developer Experience (DX) & productivity, and are now trying to follow.

If you represent Cloudflare and think I made an unjust statement here, do reach out (meet@hdoro.dev or hdorodev)! I'd love to rectify and learn better 😊

Before using Algolia to search through our Sanity.io data, we first need to sync content between the two systems. This guide will help you with that.

There are 3 main parts to this equation:

1. Defining & querying the data we want to have in Algolia
2. Indexing all existing Sanity content, which we can do any time there's a significant schema change
3. Synchronizing changes between them - happens through Sanity webhooks fired on create, delete & update operations

Defining our search objects' data structure

The bigger our Algolia records are, the slower search requests will be. The hard limit is 10kb, but we want to keep them under 2kb for snappy response times. Hence, we don't want to index our entire Sanity documents.

To think about the data you want to index, I make 5 informal distinctions between fields:

1. Bureaucratic/required fields are those you have to include no matter what
   1. objectID for updating records - usually the Sanity document's _id
   2. document's _type
   3. the revision ID (_rev) as a just-in-case for special sync operations
2. Fields for textual search - think titles, descriptions, headings, etc.
3. Data for faceting/categorization - tags, status, authors, genre, etc.
4. Custom ranking factors - upvote count, date published, featured...
   1. These values need to be booleans (true/false) or numbers.
   2. In my GROQ query below, you'll notice I transformed status (a string/enum) into statusNumber.
5. Presentational content you need for rendering results to users - images, visual properties, etc.

To experiment with these, I recommend creating and testing GROQ queries. We'll use the projections later on, so it's worth the investment. Here's a commented example from the recipes website I'm creating:

*[
  _type == 'recipe'
  && !(_id in path('drafts.**'))
  && defined(slug.current)
  && status != 'unapproved'
] {
  // Bureaucracies
  _type,
  _rev,
  "objectID": _id,
  _createdAt,

  // Textual search
  title,
  description,
  "ingredients": ingredients[_type == "recipe.ingredient"].title,
  "headings": pt::text(body[
    _type == "block" && style in ["h1", "h2", "h3", "h4"]
  ]),

  // Faceting
  duration,
  "categories": categories[]->{
    title,
    _id,
  },
  "tags": tags[]->{
    title,
    _id,
  },

  // Finer ranking
  "statusNumber": select(
    status == "approved" => 100,
    status == "pendingReview" => 50,
    -100
  ),

  // Presentational content
  "mainImage": photos[0],
}

If something in the query above is unclear, I wrote an in-depth guide on GROQ you may find useful 😉

After you run the query and make sure it's getting exactly the data you want, I recommend saving a subset of documents in a JSON file and manually uploading them to Algolia's dashboard to live test your search.

If you're indexing multiple document types, I'd recommend using the same GROQ query for all of them and running conditionals based on their type. It'd make the processes below easier to reason about. Here's an example:

*[
  _type in ['recipe', 'article', 'user']
  && !(_id in path('drafts.**'))
  && defined(coalesce(handle.current, slug.current))
] {
  // Bureaucracies - shared across all
  _type,
  _rev,
  "objectID": _id,
  _createdAt,

  _type != "user" => {
    title, description,
  },

  _type == "user" => {
    name, bio,
  },

  _type == "recipe" => {
    "ingredients": ingredients[_type == "recipe.ingredient"].title,
  },

  // ...
}

Index all applicable documents

After you figure out the data structure & queries you need to run, indexing all is the simpler part. In short, we'll get the data and use Algolia's SDK to run saveObjects on it. Here's my code, in the shape of a SvelteKit API endpoint:

import sanityServerClient from '$lib/utils/sanityServerClient'
import algoliasearch from 'algoliasearch'

export const algoliaInstance = algoliasearch(
  process.env['ALGOLIA_APPLICATION_ID'],
  process.env['ALGOLIA_ADMIN_KEY'],
)

const QUERY = `YOUR_QUERY_HERE`

export const get = async (request) => {
  // Basic security to prevent others from hitting this API
  const passphrase = request.query.get('passphrase')
  if (passphrase !== process.env['ALGOLIA_SECRET']) {
    return {
      status: 401,
    }
  }

  const documents = await sanityServerClient.fetch(QUERY)

  const index = algoliaInstance.initIndex(process.env['ALGOLIA_INDEX'])

  try {
    console.time(`Saving ${documents.length} documents to index:`)
    await index.saveObjects(documents)
    console.timeEnd(`Saving ${documents.length} documents to index:`)
    return {
      status: 200,
      body: 'Success!',
    }
  } catch (error) {
    console.error(error)
    return {
      status: 500,
      body: error,
    }
  }
}

If this script is successful running, you should see your data once you refresh the Algolia dashboard 🎉🎉

Syncing data via webhooks

To make sure data is updated, deleted or created accordingly, we'll need to create an endpoint for handling Sanity's webhooks. These fire whenever there's a change in your dataset, sending a payload similar with the _ids of documents updated, created or deleted. Something similar to this:

{
	"ids": {
		"updated": [],
		"created": ["M9IWNQzEM85EAsYtvAZnPd"],
		"deleted": []
	}
}

We could manually query these _ids, figure out their _type, get the appropriate data and send that to Algolia. Thankfully, though, we can delegate this grunt work to the official sanity-algolia package.

Here's how my serverless function for handling those webhooks looks like:

import sanityServerClient from '$lib/utils/sanityServerClient'
import indexer from 'sanity-algolia'
import { algoliaInstance, RECIPE_PROJECTION } from './index-all'

export const post: RequestHandler = async (request) => {
  const passphrase = request.query.get('passphrase')
  if (passphrase !== process.env['ALGOLIA_SECRET']) {
    return {
      status: 401,
    }
  }

  const index = algoliaInstance.initIndex(process.env['ALGOLIA_INDEX'])
  const sanityAlgolia = indexer(
    {
      recipe: {
        index,
        // The projection is the piece of the GROQ query
        // where we determine what data to fetch
        projection: RECIPE_PROJECTION,
      },
      // 💡 Could have many other document types here!
    },
    
    // Serializer function for manipulating documents with Javascript
    // I'm not using it as GROQ is doing all the work
    (document) => document,
    
    // Visibility function to determine which document should be included
    (document) => !['unapproved'].includes(document.status),
  )

  // Now let sanityAlgolia do the heavy lifting
  return sanityAlgolia
    .webhookSync(sanityServerClient, request.body as any)
    .then(() => ({
      status: 200,
      body: 'Success!',
    }))
    .catch(() => ({
      status: 500,
      body: 'Something went wrong',
    }))
}

To test this is working, we can manually create a webhook payload and send that to the serverless function. For example, let's pick up the first object in Algolia and try to delete it by sending a request similar to this:

fetch(WEBHOOK_ENDPOINT, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ids: {
      updated: [],
      created: [],
      // Add your document _id below:
      deleted: ["M9IWNQzEM85EAsYtvAZnPd"],
    },
  }),
});

If you got a 200 out of that, open the Algolia dashboard, wait a few seconds and refresh it to see if the document is gone. Otherwise, triple-check your credentials & index, and read through sanity-algolia's docs.

If the experiment above is successful, it means you're ready for production! Send your endpoint live, add its URL to Sanity's manage dashboard as a webhook for your project & you're good to go 🎉

This integration can definitely go deeper than this. My first implementation involved synchronizing almost 20 document types across 2 different Sanity datasets, with all sorts of data normalization challenges. I hope this guide gives a solid understanding that you can use when tackling these more complex use-cases. If not, feel free to reach out at meet@hdoro.dev or hdorodev!

I may eventually write about the search UI I'm building with Xstate and Svelte, with a strong focus on SEO, performance & UX. Glad to hear if that's of interest to you 😊

TL;DR: if you're in need of a PortableText renderer for Svelte, the official @portabletext/svelte package is the way to go. The minimal renderer I built from the approach below can be found in this this Github repo 😊

Usually, when you want to render PortableText in your front-end(s), you reach to one of the official packages such as @sanity/block-content-to-react or @sanity/block-content-to-html. When your the medium/framework you're developing in doesn't have a solid alternative for rendering, though, things can get complicated.

I'm currently building a community-driven recipes website with my wife. It's one of those projects where I give myself the luxury of creating everything from scratch to learn and challenge myself. We're using Svelte, which has no stable PortableText renderer - although MovingBrand's package and Rune's svelte-pote are worth mentioning (thanks for the effort, y'all!), they aren't super mature yet.

Knowing that, I was a reluctant from using PT-based content in the app as I knew I'd had to hand-roll my own implementation, but figured it'd be a good flexer of my understanding of the format.

In the past I've built a handful of Svelte-powered static websites using @sanity/block-content-to-html and rendering them as HTML with {@html}. It was messy, but it worked for static components. As now I need dynamic functionality such as inserting the logged user's name inside the text, this wasn't an option.

Creating our renderer

Let's take the start of this article as an example of PortableText data:

const example = [
  {
    // Rich text block (paragraph/header/list/quote)
    _type: "block",
    _key: "2ca469a56edd",
    // Block type: "paragraph"
    style: "normal",
    // Marks enrich text with custom data or formatting, defined here
    markDefs: [
      {
        _type: "blockAbsUrl",
        _key: "06d4cabb8fc8",
        url: "https://www.npmjs.com/package/@sanity/block-content-to-react",
        newWindow: true,
      },
    ],
    children: [
      {
        _type: "span",
        _key: "59e1710cc3f8",
        text: "Usually, when you want to render PortableText in your front-end(s), you reach to one of the official packages, ",
        marks: [],
      },
      {
        _type: "span",
        _key: "asdoih123893f8",
        text: "such as ",
        // Marks can be about formatting, such as strong, em, code, etc.
        marks: ["em"],
      },
      {
        _type: "span",
        _key: "4792e1707c91",
        text: "@sanity/block-content-to-react",
        // Or you can use your own markDefs, such as a link
        // Refers to the mark definition above (blockAbsUrl)
        marks: ["06d4cabb8fc8"],
      }
    ],
  },
  {
    // Custom component type:
    _type: "callout",
    _key: "8d196ce704a5",
    title: "Context",
    // Nested PortableText:
    body: [
      {
        _type: "block",
        _key: "6ec552e3531b",
        // ...
      },
    ],
  },
];

Its base structure is an array of objects, each containing a _key and _type.

Rendering custom blocks

We can have custom components/blocks with their own data structure, such as the callout which has a title and a body, which is its own PortableText instance. This is a solid place to start our renderer:

<!-- PortableText.svelte -->
<script>
  export let blocks = []
  export let serializers = undefined
</script>

{#each blocks as block, index (block._key)}
  {#if serializers?.types?.[block._type]}
    <!-- Custom block-level element -->
    <svelte:component
      this={serializers.types[block._type]}
      {block}
      {index}
      {blocks}
    />
  {:else}
    <!-- Block _type not yet supported -->
  {/if}
{/each}

In the PortableText.svelte component above, we're mapping over all blocks and rendering a Svelte component for them based on their _type. The serializers property is an object that takes components for rendering custom marks and types - here's an example of that in action:

<script>
  import PortableText from '../PortableText/PortableText.svelte'
  import AbsoluteURL from '../PTElements/AbsoluteURL.svelte'
  import Callout from '../PTElements/Callout.svelte'

  export let article
</script>

<PortableText
  blocks={article.body}
  serializers={{
    // Rendering the Callout component for the callout block _type
    types: {
      callout: Callout,
    },
    marks: {
      absUrl: AbsoluteURL,
    },
  }}
/>

If we render the above for the example data, we'll get a Callout rendered 🎉

Rendering rich text

It's a good start, but to get the full content we'll need to render entries of _type: "block", and this is where things start getting a bit complicated. PortableText blocks have the following complexities:

• They have multiple children, each which have their own marks
  • Marks can set formatting (marks: ["strong", "em"] for an italicized, bold text)
  • Or they can refer to a custom mark defined in the block's markDefs (marks: ["06d4cabb8fc8"], where this id refers to a mark definition's _key.
  • marks: ["strong", "06d4cabb8fc8"] for a bold link, for example
  • This means a single text property can be wrapped in multiple elements (<strong><em><a>Click me!</a></em></strong>)
• Children also have their _types
  • Regular text is of _type: "span"
  • But we can also add custom inline-blocks, such as _type: "userInfo" for displaying the user's name and avatar in the middle of the text
• Their style
  • The normal style is the regular <p> element in HTML land
  • h1-h6 and blockquote are also straightforward
  • But styles can be customized. For example, I often use textCenter in my projects for a centralized paragraph.
• The level and listItem properties set their list indentation
  • This means there is no "parent bullet" containing its children items, which would be easier to reason about.

Let's start by creating a BlockRenderer component and plugging it in into PortableText:

{#each blocks as block, index (block._key)}
  {#if serializers?.types?.[block._type]}
    <!-- Custom block-level element -->
    <svelte:component
      this={serializers.types[block._type]}
      {block}
      {index}
      {blocks}
    />
  {:else if block._type === "block"}
    <BlockRenderer {blocks} {index} {block} {serializers} />
  {:else}
    <!-- Block _type not yet supported -->
  {/if}
{/each}

Aside from the wrapper element, BlockRenderer is very similar to PortableText: it gets an array of entries (in this case block.children) and renders components for each based on their _type. For now, let's wrap every block in a paragraph - we'll deal with styles later:

<!-- BlockRenderer.svelte -->
<script>
  import BlockSpan from './BlockSpan.svelte'
  import type { PTBlock, Serializers } from './ptTypes'

  export let index
  export let blocks
  export let block
  export let serializers
</script>

<p>
  {#each block.children as child (child._key)}
    {#if serializers?.types?.[child._type]}
      <!-- Custom inline element -->
      <svelte:component
        this={serializers.types[child._type]}
        {block}
        node={child}
      />
    {:else if child._type === 'span'}
      <!-- Regular span / text child -->
      <BlockSpan span={child} {block} {serializers}>{child.text}</BlockSpan>
    {:else}
      <!-- Unsupported child _type -->
    {/if}
  {/each}
</p>

This is enough for custom inline components. The BlockSpan requires a bit more work.

Before proceeding, notice how in the code above we're adding {child.text} to the <BlockSpan>'s content. This is the actual textual value users will see, and it'll be exposed inside BlockSpan as a <slot>, which is very similar to React's props.children (more on Svelte slots).

As mentioned above, we can have multiple marks per _type: "span", so we'll need to do a bit of recursion in order to properly render the full span. In the BlockSpan implementation below, notice how each instance of it is focused solely on one mark and recursively renders another child BlockSpan with the remaining marks (nestedSpan):

<!-- BlockSpan.svelte -->
<script lang="ts">
  export let block
  export let span
  export let serializers

  $: allMarks = span.marks || []

  // Let's start with the first mark
  $: currentMark =
    // If the mark references an entry in markDefs, use that object as the currentMark
    block.markDefs.find((def) => def._key === allMarks[0]) || allMarks[0]

  // If we have more marks, we'll render a nested BlockSpan with remaining marks
  $: nestedSpan = {
    ...span,
    marks: allMarks.slice(1),
  }

  $: customComponent = serializers?.marks
    ? typeof currentMark === 'string'
      ? serializers.marks[currentMark]
      : serializers.marks[currentMark?._type]
    : undefined
</script>

{#if !currentMark}
  <!-- If no current mark, render only the text without wrapping elements -->
  <slot />
{:else if customComponent}
  <svelte:component this={customComponent} {block} {span} mark={currentMark}>
    <!-- Inside the custom component, render recursive BlockSpan with remaining marks -->
    <svelte:self {block} span={nestedSpan} {serializers}>
      <slot />
    </svelte:self>
  </svelte:component>
{:else if currentMark === 'strong'}
  <strong>
    <svelte:self {block} span={nestedSpan} {serializers}>
      <slot />
    </svelte:self>
  </strong>
{:else if currentMark === 'em'}
  <em>
    <svelte:self {block} span={nestedSpan} {serializers}>
      <slot />
    </svelte:self>
  </em>
{:else if currentMark === 'code'}
  <code>
    <svelte:self {block} span={nestedSpan} {serializers}>
      <slot />
    </svelte:self>
  </code>
{:else if currentMark === 'underline'}
  <u>
    <svelte:self {block} span={nestedSpan} {serializers}>
      <slot />
    </svelte:self>
  </u>
{:else if currentMark === 'strike-through'}
  <s>
    <svelte:self {block} span={nestedSpan} {serializers}>
      <slot />
    </svelte:self>
  </s>
{:else}
  <!-- Unsupported mark _type - let's render the plain text -->
  <slot />
{/if}

With the above, we have rich text with proper formatting and inline notations in a customizable way! Say we want to add custom classes to bold text - the default is a plain <strong> element as you can see above -, we'd do the following with <PortableText>:

<script>
  import PortableText from '../PortableText/PortableText.svelte'
  import AbsoluteURL from '../PTElements/AbsoluteURL.svelte'
  import CustomStrong from '../PTElements/CustomStrong.svelte'

  export let article
</script>

<PortableText
  blocks={article.body}
  serializers={{
    marks: {
      // Custom mark
      absUrl: AbsoluteURL,
      // Custom component for format-only mark
      strong: CustomStrong
    },
  }}
/>

Here's what CustomStrong could look like:

<!-- CustomStrong.svelte -->
<strong class="text-gray-900 font-black">
  <!-- Emojis for extra boldness 💥 -->
  👉 <slot /> 👈
</strong>

Aside from not handling lists, the one issue with this PortableText renderer is that every block will be rendered inside a paragraph, even when its style is a heading, quote, etc. Let's fix that by replacing the wrapping <p> in BlockRenderer.svelte with a new component, BlockWrapper:

<!-- Subset of BlockRenderer.svelte -->
<BlockWrapper {block} {serializers} {index} {blocks}>
  {#each block.children as child (child._key)}
    <!-- rendering logic (see previous code example) -->
  {/each}
</BlockWrapper>

BlockWrapper is very similar to BlockSpan in the sense that its sole purpose is to wrap its children in appropriate tags. The difference is that it doesn't need the complicated recursion we saw above as each block can only have one style. The result is a much simpler component:

<script>
  import type { PTBlock, Serializers } from './ptTypes'
  import ReportError from './ReportError.svelte'

  export let index
  export let blocks
  export let block
  export let serializers

  $: style = block.style || 'normal'

  $: customStyle = serializers?.blockStyles?.[style] || undefined
</script>

{#if customStyle}
  <svelte:component this={customStyle} {block} {index} {blocks}>
    <slot />
  </svelte:component>
{:else if style === 'h1'}
  <h1><slot /></h1>
{:else if style === 'h2'}
  <h2><slot /></h2>
{:else if style === 'h3'}
  <h3><slot /></h3>
{:else if style === 'h4'}
  <h4><slot /></h4>
{:else if style === 'h5'}
  <h5><slot /></h5>
{:else if style === 'h6'}
  <h6><slot /></h6>
{:else if style === 'blockquote'}
  <blockquote><slot /></blockquote>
{:else if style === 'normal'}
  <p><slot /></p>
{:else}
  <!-- Unsupported style - let's render it inside a paragraph to prevent hiding content -->
  <p>
    <slot />
  </p>
{/if}

Similarly to custom types and marks, some times we want to render styles differently. In order to deal with that, the serializers object can also take blockStyles:

<script>
  import PortableText from '../PortableText/PortableText.svelte'
  import CustomHeading from '../PTElements/CustomHeading.svelte'
  import CentralizedText from '../PTElements/CentralizedText.svelte'

  export let article
</script>

<PortableText
  blocks={article.body}
  serializers={{
    blockStyles: {
      // Custom heading 1
      h1: CustomHeading,
      // Custom user-defined style
      textCenter: CentralizedText
    },
  }}
/>

And, as we've passed index and blocks properties to our custom style components, our CustomHeading can adapt its styles based on other blocks near it - what is often called rule-based design:

<!-- CustomHeading -->
<script>
  export let index
  export let blocks
  export let block

  const HEADING_STYLES = ["h1", "h2", "h3", "h4", "h5"]
  $: style = block.style
  $: precededByHeading = HEADING_STYLES.includes(blocks[index - 1]?.style)

  $: anchorId = `heading-${block._key}`
</script>

<!-- If preceded by heading, have a higher margin top -->
<div class="relative {precededByHeading ? "mt-10": "mt-4"}" id={anchorId}>
  <a href="#{anchorId}">
    <span class="sr-only">Link to this heading</span>
    🔗
  </a>
  {#if style === "h1"}
    <h1 class="text-4xl font-black"><slot/></h1>
  {:else if style === "h2"}
    <h2 class="text-3xl"><slot/></h2>
  {:else}
    <h3 class="text-xl text-gray-600"><slot/></h3>
  {/if}
</div>

The example above is a bit underwhelming, but imagine sticking a CTA next to a contact form if they come together; or creating a grid of images if two or more small images follow each-other; or putting testimonials on top of their preceding case studies... the sky is the limit!

I hoped this served to shine some light on PortableText and make it less of a black box for you. You can find the full source code here. Glad to take contributions and feedback!

We can host audio files in Sanity and plug them into paragraphs by adding custom types to the block.of array. You can see this in action in my Learn GROQ guide. Without further ado, here's the process:

Starting with the schema, we need to add the inlineAudio schema type to our block content's of property (documentation on this property):

export default {
  name: "contentBody",
  title: 'Body of content',
  type: 'array',
  of: [
    {
      type: 'block',
      of: [
        {
          name: 'inlineAudio',
          type: 'file',
          title: 'Inline audio player',
          options: {
            accept: 'audio/*',
          },
        },
      ],
    },
    {type: "image"}
  ]
}

The `of` array defines which custom types
should be rendered inline




Accept only audio files




Notice the difference with custom types at the same level as the `type: block`:
these, like the image here, will be standalone blocks which are placed between paragraphs, not inside them.

This will allow us to add the "Inline audio player" element to our paragraph from the insert menu:

Now editors have the ability to add inline audio players to their content! 🎉🎉 Let's cover how to render this in the front-end. Here's a portion of the component that renders the block content of my articles (I'm using React and the @sanity/block-content-to-react package):

import * as React from 'react'
import BlockContent from '@sanity/block-content-to-react'

import AudioPlayer from '../AudioPlayer'

const serializers = {
  types: {
    // Handler for the "inlineAudio" _type
    inlineAudio: ({ node }) => {
      // The component we use to render the actual player
      return <AudioPlayer {...node} />
    },
  },
}

const ArticleBlockContent = (props) => {
  return (
    <BlockContent
      blocks={props.blocks}
      serializers={serializers}
    />
  )
}

export default ArticleBlockContent

And here's the AudioPlayer component that actually renders the data into an actionable button for users:

import * as React from 'react'

const AudioPlayer = (props) => {
  // Used to store the audio element once instanciated
  const [audioEl, setAudioEl] = React.useState()

  if (!props.asset?._ref) {
    return null
  }
  
  const { _ref: ref } = props.asset
  // Example:
  // From: file-ff7d1c2d7bd5ac367359d57f0319f5f458bc3c3d-m4a
  // To: https://cdn.sanity.io/files/q2j8cwsg/production/ff7sfgc2d7bd5ac367359d57f0319f5f458bc3c3d.m4a?dl

  const assetRefParts = ref.split('-') // ["file", "ff7...", "m4a"]
  const id = assetRefParts[1] // "ff7..."
  const format = assetRefParts[2] // "m4a"
  const assetUrl = `https://cdn.sanity.io/files/${process.env.NEXT_PUBLIC_SANITY_PROJECT_ID}/${process.env.NEXT_PUBLIC_SANITY_DATASET}/${id}.${format}`

  function playAudio() {
    try {
      if (!audioEl) {
        const audio = new Audio(assetUrl)
        setAudioEl(audio)
        audio.play()
      } else {
        audioEl.play()
      }
    } catch (error) {}
  }
  return (
    <button onClick={playAudio} aria-label="Play audio">
      🔊
    </button>
  )
}

export default AudioPlayer

And that's it! There are many more interesting use cases of inline blocks, some of which I hope to cover in the future.

Reach me at meet@hdoro.dev or hdorodev if you have any questions ;)

PS: This is also available in video on YouTube: https://www.youtube.com/watch?v=syFw-_XibFE

The most complicated part of content is its long term maintainability. Sure, producing is hard - you should see how long I'm taking to write these words -, but keeping your words up-to-date with organizational & product changes, market shifts and even the cultural climate is an entirely new beast.

One way you can improve this process is by re-surfacing old content to editors for review. In Sanity, a quick way to do that is to add a menu item that displays a random piece of content. It's the perfect use-case for Sanity's structure builder.

I've recorded a video going through it, in case you prefer that format.

Displaying a random document with the structure builder

Here's the high-level approach to getting to that:

1. Create a new S.listItem in your structure
2. Before rendering content inside of it, we'll fetch all ids of a given collection of documents
3. Then we'll pick a random id from this list
4. And render a S.document(chosenId) with this id

The code to implement is short - without comments it could fit in 12 formatted lines:

import S from '@sanity/desk-tool/structure-builder'
import client from 'part:@sanity/base/client'

export default () =>
  S.list()
    .title('Content')
    .items([
      S.documentTypeListItem('idea').title('Ideas'),
      // New item in the desk menu:
      S.listItem()
        // Add a recognizable title & icon
        .title('Random idea')
        .icon(FiHelpCircle)
        // And use an async function to resolve its content
        .child(async () => {
          // It'll first fetch the ids of every idea in the dataset
          const ids = await client.fetch(`*[_type == 'idea']._id`)
          // Get a random one from that list
          const chosenId = getRandomItem(ids)
          // And display the document for this random one
          return S.document().id(chosenId).schemaType('idea')
        }),
      // ...
    ])
    
// Used to find a random id every time the
// "Random Idea" menu is clicked
function getRandomItem(arr) {
  const randomIndex = Math.floor(Math.random() * arr.length)
  return arr[randomIndex]
}

Over the course of the next months I'll try to share other examples of how the structure builder can be used to create effective editing environments. My goal is to show how Sanity can make content maintenance easier (or "Content Ops" in general).

The structure above is something I'm using for myself. On a personal level, I'm hoping that by reviewing my ideas more often, I'll learn better. After all, Learning life-long wisdom takes time ;)

This is the written version of the talk I did for Greenconf 2020. I'll post the video here soon.

Hey there, everyone! Today I'll show you a glimpse of what an eco-friendly web development framework could look like.

My name is Henrique and I'm starting my journey on making a positive impact on the planet through web design and development. Like you, I'm learning and often getting overwhelmed by the scary and complex sustainability topic, so feedback is very much appreciated.

First, I want to be clear about what I mean by "web framework". This could go into many directions, but here we'll focus on a developer tool for building content-driven websites and web-apps, focusing on the front-end. It'll provide some back-end functionality but it won't go deep in databases, permissions and complex APIs. It also won't cover edge cases and super complex apps such as Twitter and Github.

This is still broad, but being broad is the idea. We're covering ~95% of the use cases out there, from marketing sites to admin dashboards and small social apps. (Yes, 95% is an invention 😋)

A summary of what we want here is to conceive a developer tool that can materially reduce our websites and apps' carbon footprint while still achieving economic goals and being inclusive and accessible. To guide our decisions, we'll focus on 3 qualitative questions:

• How can we power our work with renewable energy?
  • This is proposed by Tim Frick in his book Designing for Sustainability
  • The idea is simple: data centers consume a lot of energy, if we can source that energy from renewables, then we're already doing a great job
• How can we make it as efficient as possible?
  • Also from Tim Frick, this question focuses on what can we do to reduce the overall energy consumption and digital waste of our apps?
  • This also includes concerns about UX design, as a bad user experience could lead to wasted energy on useless browsing
• And, even better, how can we avoid building unnecessary products and features?
  • This one is especially important in our wasteful industry - think about all the features you built that users didn't want and design extravaganzas you included in the final work because of stakeholder requests.
  • I know I've done that a lot
  • It hurts to think that those, besides being pointless, also have a carbon footprint.
  • Remember the greenest app is the one you don't build

These are our three guiding principles that we'll use to frame our solutions. As I know you're wondering about the concrete numeric impact of this work, let's take a look at an example to give you some perspective.

Danny van Kooten has wrote a very nice piece on how he reduced his footprint by roughly 59 tons of CO2 per month by reducing the Javascript size of his WordPress plugin by 20kb.

He lives in The Netherlands, whose citizens had an average of 10.3 tons of CO2e emitted in 2017. So with his tiny code change, he managed to offset the carbon footprint that ~70 fellow dutch people would have in a year. Even if he overshot his calculations by 50 times, this optimization would be enough to cover his personal impact for 1 year and 4 months.

This is an imperfect framing, of course, but it shows that as web developers we have a significant opportunity to use our work to make a positive impact on the world. Now that we know which questions to ask and how making our websites more sustainable could help the planet, let's move on to how this framework could help.

This will be a rapid-fire of features and directives, I won't go too deep into each of them. For details, go to hdoro.dev/sustainability. The goal here is to spark some inspiration and show concretely how we can help developers make sustainable choices more easily. With only 15 minutes I won't really be able to convince you that X is materially greener than Y 😅

(I'm still writing the rest, in the meantime, refer to the repository on the features of an eco-friendly-web-framework)

You can find the slides here. And the video for the talk on YouTube is below:

Unfortunately, I didn't finish the written version yet 😥 I'll update this post as I finish polishing my notes (they're very messy and I couldn't automatically generate a transcription from the video).

Resources mentioned in the talk & more

• Tools for testing
  • Google Lighthouse
  • WebPageTest
  • Pingdom tools
  • Google PageSpeed Insights - runs Google Lighthouse and provides real world data through Chrome User Experience Report
• Why care about performance
  • Why Performance Matters, by Google Developers
  • Gatsby Low Tech Starter, by Mathieu Dutour
  • Location, Privilege and Performant Websites, by Stephanie Stimac
• Gatsby performance benchmarks - 922 Gatsby sites tested with Google Lighthouse
• Making Google Fonts faster by Sia Karamalegos
• Create a Medium like Lazy Image Loading Effect Using Gatsby.js in 5 minutes by Srey Sachdev
• Lazy loading content with useInView hook and IntersectionObserver (screencast)
• The cost of Javascript in 2018
• BundlePhobia
• Speed up your Gatsby site with 1 line of code 🤯
• gatsby-plugin-preact on Gatsbyjs.org
• Gatsby recipe to implement gatsby-plugin-preact automatically
• Should I Use a Carousel
• Creating a simple slideshow / carousel app with React hooks 🥑
• The unseen performance costs of modern CSS-in-JS libraries in React apps
• Introducing the React Profiler
• Compiled CSS-in-JS
  • callstack/linaria
  • atlassian-labs/compiled-css-in-js
• CSS-in-JS evolution
  • Stylis v4
  • Theme UI
  • styled-component v5 achievements
  • Smart atomic CSS generation with new libraries such as FB’s stylex (not yet released, see this video, minute 28)
  • Exploring the new age of CSS-in-JS by Annamalai Saravanan
• Gatsby's content duplication issues
  • This thread on Twitter by Devon Govett
  • Why Gatsby is better with Javascript (note on performance), by Mikhail Novikov

Oh, and if you have 3 minutes to spare, you can help by giving some feedback, this was my first talk ever 😊

TL;DR:

Gatsby relies heavily on Javascript through the dependence on React and the addition of a router and other logic to its runtime.

Hence, one could argue it's quite bloated for simple static sites, delivering tons of JS that users wouldn't otherwise need.

By changing the rendering engine from React to Preact we can reduce up to 100kb (unzipped) in bundle size, making our sites faster on mobile (runtime and loading) and more suited for SEO 🎉

And I finish with a bonus tip at the end, check it out 😉

The problem

Gatsby is great, and I mean it. It has allowed me to build complex sites with ease, such as Data Hackers, and unlock the creative freedom provided by building from scratch without the colossal work needed to build the basis for it, as there are many plugins and great guides out there. Also, it's just React with the added benefit of not having to care about webpack and the likes, so it's quite easy to get productive. In short, it has amazing DX, and it has brought me tons of joy since I started working with it in 2017.

What is not so amazing is its performance. Yes, I'm challenging their homepage slogan.

First, who even defines what "matters"?! Second, it likes to pride itself in being "blazing fast", that it provides speed by default, to which I agree to a bunch of cases, but not all of them. For a simplistic blog like the one you're reading, Gatsby actually hurts its performance. I'd have to do a terrible job to ship 70.9kb of downloadable Javascript (219kb uncompressed) on this very barebones page, and yet, that's what "fast in every way that matters" brings to the table.

I have a huge collection of thoughts on this and have been delaying a post on the shortcomings and threats of Gatsby for a while, but that will have to wait longer. To finish driving my point home, take a look at my Lighthouse score - measured on applied slow 4G for mobile - for the default Gatsby mode:

And keep in mind that the document itself is only 10.8kb, including styles, so a TTI of 2.8s for such a simple page is unacceptable (for me, at least 😜). If you want to see it for yourself, here's this version of the page.

The solution: reduce JS through Preact

Turns out Preact X just came out and, with it, came stability and reliability enough to ditch React for Preact as the rendering engine and benefit from the reduced JS. They say a picture is worth a 1000 words, so I'll give you two:

Now, that's better! Still a bit disheartening considering the simplicity of the page (which you can find here) and the fact that a few months ago this result was considerably better. As Lighthouse is changing its metrics and weight attributes over time (see the weights for V2 and compare them to the weights for V3), seemingly putting more emphasis on aspects that are highly affected by JS heavy set-ups, I expect Gatsby sites to perform worse and worse over time.

Anyway, it's still a good gain that becomes more expressive on bigger sites, and it comes at no cost / collateral, so switching to Preact is an obvious choice. I'm not sure if you'd hit incompatibilities on big apps that make use of other libraries such as Apollo, etc., but in my experience I haven't seen a single site with a problem so far. And to do it, the process is super straightforward and simple (alternatively, you can follow the plugin's official docs)!

npm i gatsby-plugin-preact preact

And then, in your gatsby-config.js:

/* ... */ plugins: [/* ... */ `gatsby-plugin-preact`];

There you go! 1 npm install and 1 line of code later, and you've saved 45.2% of uncompressed JS (43.02% for of the download size) 🎉🎉

Do yourself, and the internet / users / planet, a favor and do that for every Gatsby site you ever make! Heck, you can even bake it into your default base theme / starter, easy peasy!

Bonus tip: remove ALL Javascript 😈

Now, if you're building a simple website / blog that doesn't benefit from the SPA aspects of Gatsby and doesn't use any dynamic features of React, like my blog and many others I've seen out there, you don't need to cope with the tons of JS nor ditch Gatsby's data layer and templating niceties... you can remove all Javascript from your site!

This one is obviously not for every situation, but can make absolute sense if the average user of the site is not going to navigate to tens of pages and always come back, case in which having Gatsby's caching and service worker capabilities would be great. However, I'm more than happy to do this tradeoff on my own blog, and here are the results:

They speak to themselves, but they could be even better if the gatsby-plugin-no-javascript - which I used to remove JS from the site - also removed the page-data.json file, which increases my payload by 70,2% for no reason, as it only makes sense in the context of hydrating the app.

This is achieved with a simple yarn add gatsby-plugin-no-javascript and adding the following to your gatsby-config.js:

/* ... */ plugins: [/* ... */ `gatsby-plugin-no-javascript`];

⚠ Note: plugins related to your hosting provider - specifically, I ran into it with Netlify - can add some specific headers to you requests that point to JS files. Make sure to delete them to avoid this behavior 😉

In conclusion, Users will now save more of their bandwidth, load your site faster and feel less the effects of JS bloat (high input delay, janky scrolling, etc.). As web devs, we must be more and more vigilant to the impacts of our choices for businesses and users. Serving unnecessary JS might be comfortable for us, but it's bad for everyone, even the planet (think about the bandwidth, and consequent electric energy, being wasted on the internet!). We can't blind our sights to this in name of UX!

This is a compilation of information and thoughts I gathered from reading Google Search guides, from the perspective of a web developer / designer. In the end of this article, I've prepared a TODO to go through when delivering a website, which might be helpful to you 😉

⚠ Please note: this is mostly written for myself, it's by no means an introductory and comprehensive guide. If you're new to SEO or want something more exhaustive, you should read the real deal!

Annotations on Google's documentation on SEO

General notes

• By putting your users first and caring about the accessibility of the content, you're already checking most of the boxes
• They don't talk much about speed here, which I found very weird 🤔
• Google indexing is becoming mobile first, starting July 1st 2019. This means that it's most important than ever to optimize your site for mobile if you want to up your SEO game.
• You can ping Google's servers with a sitemap URL for re-indexing
  • Example: [http://www.google.com/ping?sitemap=https://hdoro.dev](http://www.google.com/ping?sitemap=URL/of/file)/sitemap.xml
• Google is launching "miniapps", a new set of rich results that we can create and connect to our own API endpoints, seems really cool!
  • Check out the presentation at Google I/O '19 on it
  • I'm thinking it'd be great for my recipes blog as I could search by ingredients directly in the search results 🤔

Stuff that might hurt SEO

• Doorway pages might hurt SEO. Gotta talk with Thiago about that
• Cloaking (presenting a different version of the page for users and search engines) is an absolutely no-no
• Hiding text and links (like a hidden sidebar) can be tricky
  • TODO to myself: search and write about accessible and SEO-friendly off-screen menus
• If working with affiliate networks, make sure to read this article on it, as having duplicate content across the network could really hurt your ranking
• Based on the irrelevant keywords article, it seems like Google is smart enough to detect when people are doing "keyword stuffing". So, focus on making a good flow of content, not forcing the amount of keywords in a sentence
• There are others, of course, be sure to check the Quality Guidelines

The AMP problem

Unfortunately, Google is really pushing for AMP, and there are huge chunks dedicated solely to it 😔 (tiny rant below)

• I see the AMP project as Google's effort to further its hegemony on the web, so I'm definitely worried about this, as publishers feel obliged to comply with their specifications in order to keep relevant in search;
• There's also the verified-look it gives to fake news, losing your brand's signature, handing content hosting to Google, etc.
• If fact, there are so many problems, you can dive deep in articles such as Kill AMP before it kills the web, The problem with AMP and even A report from the AMP Advisory Committee Meeting.
• I do like the idea of AMP Story, the richness of AMP Ads and the possibilities of AMP email, but I'd love scraping the project even more!

Javascript and Googlebot

If you use too much Javascript on your site(s), you should learn more about its relationship to the Googlebot:

• Googlebot always declines user permission, so never count on them for critical content
• It doesn't support localStorage and always clears cookies
• Do some sort of feature detection and polyfill stuff that it doesn't support
  • See Feature Detection on MDN
• Lazy-loading components should load when scrolled into the viewport with the Insersection Observer API and a polyfill
  • Although this is becoming much easier with the native browser lazy loading API 😍
• Be careful with infinite-loading sections, as they should have some sort of history and pagination to allow for linking and better crawling. If you don't do so, you'd better just provide regular pagination else you'll miss out a bunch on SEO. There are probably ready-made components that do so, though 🤔
• There's a concept of dynamic rendering for websites that rely on JS features that crawlers don't support. However, with Googlebot using the latest version of Chrome, I don't feel this is relevant for me. If other search engines are very important to you, you might want to check this out!

Structured data and rich results

• They give a BIG emphasis to structured data
  • This makes sense, as Schema really helps linking and interpreting content across the web, which is super important for search engines.
  • Specifically for Google, it's what allows for rich results such as recipes breakdowns.
• If you want to learn more about it, I have an introductory article on "Structuring and linking data in webpages: why care and how-to"
• "Google recommends using JSON-LD for structured data whenever possible." (source) → plus, using Microdata and RDFa is a bit messy
• Google explicitly recommends to use fewer, but more accurate properties in your data, than many incomplete or inconsistent ones.
• Structured data must be in the content of the website, and not hidden from users, else Google might ignore it
• For list pages, follow this reference on Carousels
• "BlogPosting", "TechArticle" and others are more specific types of "Article", so I believe that, for Google, it doesn't seem to make a difference.
• Choose the most specific types and properties possible from the Schema.org definitions
• Be sure to check out the search gallery for rich result options and follow the ones you want to add. The definitions there may overwrite schema.org's, and that's okay, go with Google 😉
• "You can include multiple structured data objects on a page, as long as they describe user-visible page content. However, if you mark up one item in a list you must mark up all items" (source)
  • For multiple objects in JSON-LD, you can either use a @graph object in a single script, or using multiple script see more on Stack Overflow.
• The only way to create a knowledge graph card on your site/company is through Google My Business
• There's an "Action" markup for structured data brewing that will allow users to take specific action straight from search. This doesn't interest me as of now, so I skipped this section.
• It's probably best to check Google's reference on structured data than to browse endlessly through Schema.org in search for what types and properties to use, as many of those listed in Schema aren't supported by Google. Oh, and the UX for the Schema site is horrible 😝
• Some properties like reviews can make for really huge JSON objects, so I want to try adding them on client-side with JS and see if it works and it's worth the trade-off.
  • However, this approach could increase computations and slow down the experience on mobile
• image properties have a bunch of specificities:
  • must be at least 696px wide, in the formats .png, .jpg or .gif;
  • can be an array of strings, Google will pick accordingly;
  • crawlable and indexable;
  • image must represent the content. Not sure if this means it should be inside of the content or if Google analyzes its content 🤔

Further resources

• jsonld.com provides a bunch of ready-made Schema definitions in the JSON-LD format
• json-ld.org/playground/ is great for testing your schema declarations
• Google Search for developers concentrates a bunch of useful stuff for us
• Structured Data Codelab a step-by-step tutorial by Google to learn how to use structured data. Pretty basic, but good enough to et started.
• There's a Google Webmasters Forum and a Webmasters StackExchange where you can probably answer specific questions on structure data
• SchemaApp JSON-LD Schema Generator doesn't have the best user experience, but is still much better than browsing Schema.org endlessly
  • This one is super complete as it fetches data from Schema's API, so it's always fresh

Duplicate content, canonical, and the likes

• I finally understood what is a canonical: in case you have multiple variants of the same content in different addresses (say, you write a post on your blog and on Medium), the canonical is the main source, which Google will crawl more often. The rest are the duplicate URLs
• They are generated automatically if on the same domain
• Reasons for using a canonical include specifying which URL you want to show-up on search, maximizing SEO and simplifying analytics
• Even when you set a specific canonical URL, Google can ultimately choose another one based on performance, content or others.
• For www / non-www versions, you should go to Google Search Console and set which one is the preferred. There's no need for doing this with http / https versions, Google favors https by default.
• If using hreflang for multi-language sites, you must specify a canonical URL (not sure how, though)
• You can tell Google to ignore dynamic parameters (ex: example.com/blog?order=ASC). If needed, read this piece on Block crawling of parameterized duplicate content
• There are many other recommendations to follow and methods to apply it in Consolidate duplicate URLs

On multi-language / region websites

• You can use <link hreflang="..." tags, but this can increase the size of the HTML and be hard to manage.
• You can go with HTTP headers as well, but these tends to be hard to implement for those without much knowledge on servers (myself included).
• So a better alternative seems to be creating language-specific sitemaps
• See the article on "Tell Google about localized versions of your page" for implementation details

TODO when delivering a seo-ready website

• [ ] JSON-LD structured data with Schema definitions
  • [ ] Use Google's Structure Data Testing Tool
• [ ] Validate the HTML with W3C's Markup Validation Service
• [ ] Run the site through a screen reader to look for accessibility bottle-necks
• [ ] Test the site with Google Lighthouse, Pingdom and WebPageTest.org
• [ ] Use appetize.io (or similar, such as BrowserStack) to test the site on other devices
• [ ] On Google Search Console:
  • [ ] if applicable, test the robots.txt file with robots.txt tester
  • [ ] create a sitemap.xml and test it with the Sitemaps panel
  • [ ] use the URL inspection tool to see how it shows up on Googlebot
    • [ ] Be sure to check out the mobile-friendly test as well
  • [ ] Set your preferred domain (www or non-www)
  • [ ] if using rich results, take a look at "Rich result status reports" after the site is indexed
• [ ] If you want to dive deeper, consider going through FrontEndChecklist.io

The following article is dedicated to share some thoughts on Stencil - an interesting compiler / framework / framework compiler that could have an impact in our industry.

⚠ Please note: I've only scratched the surface of Stencil and I bet there's much to it that I don't know and that might change my perception, so feel free to elucidate me, feedback is always welcome 😄

TL;DR

• Stencil is a mash-up of front-end frameworks (namely React, Vue and Angular) that compiles your schwifty code to web components;
• Its main focus is for creating isolated components that work everywhere, but it can also be used as a full-blown framework from project set-up to testing;
• Coming from React, I found the developing experience (DX) to be quite satisfying, but the software can still unstable for production work, although there are plenty of apps out there;
• If I'd found Stencil a year ago, I'd consider abandoning React for it as it has some very cool features and abstractions, and ships super tiny bundles, but with current Hooks and Suspense development, I'll probably use it just for fiddling around with side projects;
• Nevertheless, Stencil should be in your radar as it might help steer the JS framework community towards more compiler-based alternatives

What is StencilJS

In short, Stencil is a tool that compiles your react/angular-like typescript code into web components that leverage the browsers' native APIs. It has quite a lot of cool stuff packed into it, such as the generation of multiple bundles for different browsers (ES5 for IE11 and the likes vs. modern ES6+ JS), automatic code splitting and component lazy-loading, but it shines on being framework agnostic. Essentially, you can use Stencil components anywhere on the web, from insert your framework here apps to vanilla JS projects, and that's exactly why the Ionic team built it.

You should read more about it on their site and watch its announcement video, but, in essence, its main goal is to provide a way for Ionic 4 components to become usable in any front-end project, eliminating the need to re-write the UI library for each different stack. However, although Stencil's main focus is on compiling reusable components, it can also be used as a fully-fledge framework to build entire apps, and that's the main usage I'll cover in this article.

Why it might matter to you

If you're building a design system for a large company with several domains, apps, teams and stacks, the benefit of Stencil is obvious: write your components once and have them work for everyone, everywhere. This also applies to UI libraries: instead of having material-ui for React and angular-material for, you guessed it, Angular, we could unite efforts and resources into creating a single, universal library.

If, however, you're building full apps and are looking for a framework, StencilJS is also an option, especially if you need to deliver tiny packages to save users' bandwidth, as it excels in that regard. Stencil's docs are quite tiny and the software has a bunch of interesting decisions and features, so I suggest you take a look into it (should take about 1hr).

In case reading the docs is not in your plans, just know that Stencil is highly dependent upon Typescript, it uses decorators similar to Angular as well as JSX from React, and plugging in components in .html templates feels a bit like Vue (as far as I'm concerned). Below is a super simple sample component:

import { Component } from '@stencil/core';

// If I wanted to isolate the CSS applied to this component from the rest of
// the stylesheet, I could use `shadow: true` in the @Component options ;)
@Component({
  tag: 'loading-spinner',
  styleUrl: 'loading-spinner.css',
})
export class LoadingSpinner {
  render() {
    return <div class="loader" />;
  }
}

Then, when calling it inside another stateful component, I'd use:

// ...
  render() {
    if (this.isLoading) {
      return <loading-spinner />;
    }
  }
// ...

Quite similar to React, huh? If this doesn't appeal to your style, however, Stencil is still relevant to you. Together with Svelte, Imba, Glimmer, and even Angular with its Ivy project, Stencil is riding the compiler wave in which frameworks focus more on build-time transformations in order to ship smaller and more performant code to the browser.

Personally, I'm super excited with this trend and believe it has the potential to dramatically change user experience on the web. In fact, I'm already benefiting from this concept at my agency with Gatsby, a static site/app generator that has been improving quite a lot since I began using it in 2017: simply by upgrading my dependencies for older sites I can see performance improvements.

Eventually, if Web Assembly reaches a point in which it can access the DOM in a performant way, then compilers can shift gears and focus solely on WASM, which could yield amazing returns! So, long story short, keep Stencil on your radar. It's backed by Ionic and for such I bet it's coming to last, and may help steer the whole front-end community towards native browser APIs such as web components, and towards this fancy compiler movement.

My experience with Stencil

Context set, let's get our feet wet and actually talk about Stencil for real apps. You might have heard of the RealWorld project in which people build the exact same app (a Medium-like clone) with different tools, be it for the front-end or the API. I'd been enamoring their repo for a while, so when I figured Stencil was worth the shot, it was an easy pick for testing the new framework.

So, in the pursuit of knowledge and a spot at the bleeding edge of front-end development, I created Stencil's RealWorld example app, which you can find live here. I've annotated my experience while I was at it, and summarized everything below 😉

Onboarding

As I put before, the Stencil way of working is quite similar to React, and for such its learning curve was super easy and quick to grasp... It also helps the fact that their docs are quite clear straight to the point, although it still contains some holes. Knowing Ionic's documentation, I trust Stencil's will become awesome over time when things mature.

There's also a community on Slack, although I didn't have much to say there and when I did no one paid much attention 😔 hahaha

Developer Experience (DX)

Below is a bunch of stuff hard to imagine if you've never used Stencil, and I was a bit lazy when deciding not to use examples... sorry for that! Feel free to skip to the next section 😉

What I love:

• Tight Typescript integration, with type-checking tied to the console;
• Awesome attention to details with effective and fast hot-reloading, nice display of the app's status through the page's favicon, easy project set-up, CLI downloading dependencies only when needed etc.;
• Automatic (and effective) code splitting, period;
• No need to import components into every file like you do in React: Stencil automatically generates TS types for each component in the src folder and allow you to insert them into JSX with automatic type assertion;
• npm run start is quite fast when compared to Create React App and Gatsby
• You don't have stateful vs. stateless components differentiation like in React, which is quite positive as you can simply add a @State decorator when you want to use it
  • With React Hooks, however, this becomes less of an advantage haha
  • This could be considered a flaw as we're adding classes for everything, but I doubt this has real impact on performance
• Instead of React.Fragment or <></>, if you want to render multiple elements at the root of your component, you just use an array: jsx~return [<hr />, <button>Hello</button>]
  • The comma between tags can be a hassle if you miss it, be sure to add ts-lint with tslint-stencil
• This one is both a blessing and a curse: errors on specific components don't crash the whole app
  • This is good for isolating bad stuff, but can be bad for debugging
• Easy set-up of PWAs
• Selecting components is super easy with the @Element decorator
  • Although you can't directly select tags inside the component, you can always use js~this.element.querySelector('tag-name') or something like that to go down the tree. See the docs for a clearer example.

What could be better:

The fact that you write components' class names in PascalCase and their tags as separated-by-hash can be a bit confusing;

You can only export one thing per .tsx file, which is understandable, as the compiler alerts numerous exports per file could cause inefficient bundling and code splitting... However, I believe Typescript interfaces and types should be exportable as they don't get included in the final code (dunno if that's feasible, tho 😝)

When testing, whenever you try to navigate the router goes crazy and the test crashes.

• In fact, the router doesn't really integrate well into e2e testing as of @stencil/router 0.3.2 and @stencil/core 0.17.0, making it impossible to run any test

You can't ALT + CLICK (or equivalent) on components to go to their corresponding file, instead you're sent to its definition file, which is auto-generated by Stencil. A small price to pay for not having to import components, maybe?

Tooling is still in its infancy. I had so many hurdles with VS Code that writing code became a bit cumbersome at first, and the currently available plugin options aren't quite there yet. I'm optimistic, though!

Stencil is missing an alternative to Redux. Although they provide @stencil/state-tunnel (which is similar to React's Context), the package is highly unstable as of version 0.0.8

• In fact, state-tunnel had an unreleased version 0.0.9-1 that I found not from the npm page, but rather from a code example extracted from one of Stencil's repos, and that one actually worked without crashes during compile time...
• Plus, state-tunnel seems to be quite a big package, although that could just be a fault of the Import Cost extension
• I ended up not relying on the unstable API and went for good 'ol prop drilling, passing it down the component tree 😅

Stuff that might be my own fault:

• I couldn't get auto-completion of components' tags working inside JSX, which is a bummer: it slows down development and makes it more error-prone, as I don't get any error for wrongly-typed names;
  • In fact, I spent a good half an hour trying to debug the router when I finally discovered that I had typed it wrong.
• When running e2e tests, if you don't know what you're doing, having to re-run the app every time is a bit cumbersome;
• In JSX, when adding the tag for a component, VS Code's auto-complete adds a bunch of useless HTML suggestions, making it hard to find the name/type of props you actually want to use;
• I didn't really find a way to have the router redirect to home if the switch doesn't find a possible route, so I had to create a not-found component that redirected on render;

The end result

Even with all the hurdles, I found the experience to be quite enriching, and the end result is quite satisfying:

• It's one of tiniest bundles in the RealWorld repository;
• The code is quite clean and easy to understand (at least for me 👀);
• By providing an ES6+ bundle for modern browsers, I don't feel like I'm downgrading my app during compile time;
  • And, for the hopefully tiny slice of my audience that accesses from IE11 and the likes, Stencil has an ES5 bundle filled with polyfills for everything you might need.
  • I've tested this behavior and got to ~15% bundle reduction when using Chrome when compared to IE
• Typescript integration made my life so much easier and, hopefully, the repository much more maintainable;

Besides the small caveats presented in the previous sections, my only complaint is that, currently, Stencil depends on initial parsing of Javascript to decide which bundle to download, and that culminates in a longer times of white screens before the final app is loaded and poor loading performance on bad connections / slow CPUs 😔

Stencil vs. React

Note: This comparison might serve to other frameworks, but I don't have relevant experience to say so!

First of all, let me say it's a very smooth transition to make and that you can easily apply Stencil to your next hobby project or maybe create components for production work. Without further ado, let's go to pros and cons:

• Pros for Stencil:
  • smaller packages;
  • lazy loading and code splitting without lifting a finger;
  • e2e tests integrated into an official and easy workflow;
  • promise of visual diffing in the future;
  • Less lock-in: if you need to change frameworks, you can reutilize part of your Stencil app without many alterations due to its compiler nature;
  • No need to import everything all the time and pollute your code with "useless" (not) code;
  • Tight Typescript integration and awesome CLI for a great runtime;
  • You can supposedly pre-render stuff, though I'm not sure how.
• Cons for Stencil:
  • First load is a bit slow due to relying on initial parse to fetch first bundle;
  • Still unstable and will probably break things before 1.0.0;
  • Won't (and can't) evolve in React's or Angular's speed, so not sure how long it can remain competitive;
  • React's Context, Hooks and Suspense change the game quite a bit, and made developing in React super fun again and much more effective;
  • The ecosystem is still close to inexistent;
  • And maybe the most worrying: **I'm not sure developing Stencil has a high priority in Ionic's agenda now that they released Ionic 4

The future of Stencil

If Ionic continues to spend resources on Stencil, I see a very bright future for it. I doubt it will one day reach React or Angular's ubiquity or relevance, but it can become quite a powerful and stable option for those looking for frameworks closer to the metal and better aligned to browser APIs.

More important than Stencil, however, is what it can represent and unlock in the front-end scene: As put before, bringing optimizations to compile-time is a necessary step into achieving true performant apps that can reach everyone, and with Stencil's partial lead, the rest can follow.

For the time being, however, it's a fun tool to play, with great abstractions and promising concepts, but I'll keep with React for the "real" stuff 😄

This guide aims to provide some best practices for designing interfaces with the handoff in mind, having the goal of facilitating the communication between designers and developers. This is an ever evolving guide based on our internal processes at Kaordica, and is by no means final - use it as a basis for your own conventions 😉

TL;DR

• Start your design exploration with no rules to avoid hindering your pace, but start structuring the project before doing real production work and never forget to tidy up your workspace before handing it to development teams;
• Provide and follow a thorough styleguide and design around it;
• Think modularly and componentize your work as much as possible;
• Try to have some minimal foundational knowledge on the tech stack that will be used on the project to guide your decisions - after all, the design must be feasible. If in doubt, reach out to your fellow devs, they'll be glad to help;
• Explore and test every possible usage scenario - or as many as you can - for your interface: users don't always have good pictures to upload, and might not fill every info field, for example... how will the product react to that?
• When still images don't cut it in explaining desired behaviors, use transitions. If they aren't enough, write down the explanation and be ready to answer questions;
• Name things properly;
• Be open to feedback from devs and learn from it.

It's a ton of things to remember at once, but they'll fit naturally into your workflow and actually make the design process much more rewarding and the development phase quicker - at least it did for me.

Starting the design

This section is nothing more than you're already used to: when starting the project, provided you already have a direction for the work, begin by letting go of any rules and expectations you might have and just start exploring what you could do. This applies to both the wireframe (the disposition and functionality of things) as well as the visual design (how things look and feel), and should happen without any decision - subconscious or not - being made.

At Kaordica, we create the wireframe carefully together with the clients during a design sprint workshop, as we believe it's the most important part of the design: it's where we think more about UX than making things pretty, allowing for alignment of the product vision with the client. Then, with most oft he flow and copy in place, we gather the (desired) attributes of the brand and relevant references - many of which suggested by clients - and start exploring colors, font faces, and everything else concerning the visual design.


Then, when we start seeing something that can be put forward, we usually create a couple "stylegrams" - a montage with a consistent visual language - and share them with clients to choose. This prevents any surprises down the line and keep us all in the same boat - oh, and clients are also big fans of regular-but-not-too-much updates. If you're on a tight schedule, I'd still say it's worth it 😉

Finally, with these things in place, it's time to start structuring our project for the actual production work to avoid messy documents delivered to developers later on without unnecessary rework. And let me tell you, as a developer myself: if you don't standardize typography, colors, shadows and the like, devs will. Code gets unmanageable if we use distinct variables for each and every different implementation you have, so try to, whenever possible, follow a styleguide - besides a happy developer, you'll also have a more consistent design that users will love!

Following a styleguide

If I've convinced you of the importance of properly following a structure on your projects, then you must first understand what I mean by a styleguide. Also known as a "pattern library", this thing is an area of study in and of itself, and for such I won't go deep into it: just know that it can come in all shapes and sizes and has to do with standardizing the building blocks of your brand's user interfaces. With this terribly broad description I can even fit my personal version of it: a style sheet containing every typographic variation, color schemes, box-shadows, grids and logos.

A styleguide can contain a brand's voice and tone, patterns for content creators, standardized components to use, margins, icons, filters, etc., and you're right in saying my... sorry effort is none of that, but that's beside the point. Call it whatever you want, that's beside the point, the fact is that the above organization is perfect for what I needed for the project - a "simple" website - and really helped me out during development.

So, before going any further in the work, gather what you got in the exploration phase and prepare your own simple stylesheet, containing whatever you know you'll use in the project. Nothing has to be carved in stone, these things may change over the design process and you can add new ones as needed, but doing so at the beginning will force you to be more organized and test more often with different values, as tools like Figma, XD and the likes broadcast updates through the whole design. Feel a color isn't quite there? Just tweak it and see the real results, in real time, till you're satisfied. I grant you this is better than trying to standardize everything at the end for the handoff deadline.

Embrace the modularity - not singularity

Now, speaking of saving time later in the project, you should really start thinking in reusable components, else you'll find yourself cursing when having to fix a margin on a header present in 10 pages - or worse, who knows. I talk a bit more about this philosophy in my React for designers article, and I'm sure you've heard this quite often, so I won't go into much detail here.

Just know that, as much as creating and naming components in your UI design tool can be a hassle at first, it pays off. It sends a clear message to devs about what you were thinking in terms of organization and reusability when you built each thing and helps you test and spread changes throughout the design much easier. Also, it tends to force you to think about the possible scenarios of usage for each of them, preventing impossible or incoherent designs...

Oh, and for often reused pieces, a component will actually speed up your time quite a lot, just look at UI libraries for design tools like Figma's Material Design Theme Kit - they wouldn't sell so much if it wasn't easy, right?

Know the waters you surf in

Besides the reality check brought by the modularity mindset, that drives you into thinking about which properties each component should get - and the availability of each of those -, which can help steer a decision, knowing a little bit about the platform in which the design will be brought to life is a great plus.

Say you're creating a dashboard that will later be a web app... A decent knowledge on HTML and CSS would allow you to see that the following design, seemingly simple, is possible, but hard to pull off and might become quite brittle in some browsers:

The title and body are super straightforward, the problem is the grey dotted line... It's almost invisible in the white background and, though making the layout a bit more interesting, it's a pain to reproduce. Using an image or SVG (a vector file) is possible, but you'd have some problems with screen resize, probably forcing the creation of several different versions; using only HTML elements and CSS is also possible, but would pollute the markup and create the need for several new lines of otherwise useless code.

Other fellow developers might disagree with me in this, but I'd rather not do it: it's an increased overhead in terms of maintenance, page size and mobile performance for a tiny visual gain. By arming yourself with knowledge about the platform, which could be as easy as ~10h of HTML and CSS courses and practices, this type of thing will happen with much less frequency, guarantee. You'll be happier to see your design fully fledged without alterations and devs will be happy for... well, working less 😉

Of course, you won't be able to think about every possible scenario - even myself as a front-end developer don't really know if many designs are feasible until I try it, but having this in mind will, over time, create this comprehension, promise!

Let go of your beautiful, controlled environment

Yes, I know you want to impress clients and give a tap in your back for creating such a gorgeous visual design, but I have to warn you: that professional photography and short description won't be there in real users' profiles. I'm not saying to show ugly stuff to clients or to put away all the nice screens you have, these are great to show what you're capable of in terms of composition.

The thing is, when relying solely on these, you'll end up with really ugly real world results. Trust me, I've learned this in practice, here's what my beautiful design became:

So, when analyzing a wireframe and thinking about the upcoming visual design, be sure to plan what properties are mutable by users (or clients), how they could go missing or how they could be horribly formatted. This might give you a clue as to how to deal with scenarios such as the one above and prevent your devs from having to figure it out on their own. The result will be better and less time and energy will be spent in development 😉

Guide devs through the design

Don't just send a link or PDF and think you're done with it.

Spend some good minutes going through the design with developers in a videoconference, record a video, use transitions and share prototypes for clearer representations of what has to be done, write about what can't be easily explained through still images. Do what you can to make them understand your vision, and be there to help them when that doesn't happen. Be creative.

Point dismissed, next!

Name things properly

I'll can write more on the subject, but, in short, names don't have to be short, they have to be self explanatory! CardOne is so much worse than WhiteRoundedCard when you're passing your work forward - be it to others or to yourself in 3 months - that the hassle of the extra characters is justified.

Visual design doesn't suffer from this need as much as code, as, when you doubt, you can simply take a look at what awesome-tab-1 is, but acquiring good naming habits will surely help your organization... Plus, if regularly working with the same development teams, you can share naming conventions and talk about each component specifically whenever needed:

Hey, the secondary button has the wrong padding in the website.

Oh, that was intentional! I figured it was too far from the rest of the site, should I change it?

With good naming conventions, it'll all be birds, flowers and rainbows 🤗

The old "open to criticism thing"

Well, after all of these points, it should be clear that there's a ton of stuff that can be improved in your workflow when it comes to handing UIs to developers, and this list isn't exhaustive... So, you know, if all we know is nothing, we gotta listen to others.

I try to be both a designer (though more focused on UX, I suck at visual design) and a developer, and this puts me in a place to easily find ways to improve our processes here at Kaordica, but this can only go so far. I've never worked in another design team and my tech stack has been only in the web space since I began coding, and, of course, there's always the blindness to our own mistakes... So do everybody a favor and contribute to this guide with all your experience and knowledge you've accumulated through open listening 😄

Every constructive feedback is welcome, but please keep the hatred away, s'il vous plaît.

The goal of this guide is to explain, in the simplest and shortest way possible, what is React and what does it implies to you as a UI designer.

What is React

Definition: React is a javascript library (framework) that facilitates the construction of dynamic interfaces and websites. Going deeper into this definition:

• javascript is the programming language native to browsers and the web that brings interactivity and logic to websites and apps. It allows, for example, to get a form's data and send it to a server that will, then, update a users info.
• A library is simply a repository of code (a folder with files) that attend a specific need.
• Interfaces and websites, when built from scratch, can be hard to manage, and you end up writing a lot of otherwise-unnecessary code. React gives you a series of tools that facilitates this process, but there are several others in the market. There are a few reasons why we choose React:
  • It was created by Facebook to structure almost all of their products (Instagram, Facebook, WhatsApp...), and, currently, the company pays for a dedicated team to manage and evolve the library;
  • It's the most widely adopted web framework. Everyone in the field knows about it, tons of people use it and it has an extremely strong ecosystem around it, providing us with several tools and resources on the matter
  • It's relatively easy to learn, as well as very flexible and capable, with nice concepts and abstractions that I love using

React's core principles

The library has three foundational principles: the components, props and state. The whole workflow and mindset of working with React revolves around these concepts, and they're crucial even to visual design, as we'll see ;)

Components

You can think of React as a big Lego box: the idea is that you'll gather each individual piece and combine them to create a final, cohesive product. Each little piece, or component, has a format and a role in the structure in a Lego castle, for example, and each of them can be composed of smaller pieces in their own way. This division serves a great purpose: it allows for effortless reusability, as you can use the same standardized component elsewhere, as many times as needed, such as the duplication of a castle's tower.

The image above summarizes well this component relationship:

• You have a castle component that wraps it all;
• This castle is composed, among others, by a tower component, that is used twice;
• The tower has 3 subcomponents: top, secondFloor and base;
• These subcomponents, on their behalf, are also composed by other components. For example, top has a few specific block-types, such as blockRed and blockDiagonal.

Props

The componentization workflow helps saving quite a lot work as we don't have to recreate individual pieces every time... but they can only go so far as to duplicate itself, in the same shape and functionality as always, making them not as useful as they could be. Say, for example, that I have a button that, in the design, could be red or green: would I need to create two components buttonRed and buttonGreen? It'd be quite grindy to do so, right? This is where props come in!

Props, as you'd imagine, are properties that you pass to your components for them to alter their shape or functionality accordingly. This allows you to, in the above example, pass a prop color="red" to your button instead of making a whole new component.

As simple as it its, the above example is a good indicator of the power of components that receive props: they can adapt to different data and become super flexible, turning everything even more modular and reusable! Oh, and it's worth noting that the text between <Button> and </Button> is, itself, a prop. The Button component adapts to this property by using it as the button's internal text 😉

State

If you've already grasped the prop concept, then state will be quite easy: if, on one hand, props come from outside - whatever calls Button defines its text and color, for example - the state is defined inside the component. It's as if the button has a property wasClicked that was internal and controlled solely by the button itself - my button, my rules!

Stateful components can have methods that change or interact with the internal state, and that allows for a series of funcionalities that could range from controlling at which point is a vector in an animation to, for example, if a user is logged in and what is their data in a complex dashboard.

In the above animation (from Novida's website), the FirstSection component has a state shouldStart, that starts as false and, as the site loads, is updated to true, making the background blue (instead of white) and allowing the Tree to show up. This component then has its own state that dictates at which stage the tree currently is, updating it every 150ms or so to the next one in order to simulate a growth animation.

It's worth noting that the props of a component can be defined by the state of a wrapping component (the "parent" component). In the above example, the Tree receives a prop canStart passed down by FirstSection, which controls its value by its own internal state shouldStart. Maybe the code below will make it a bit easier to visualize:

class FirstSection extends React.Component {
    state = {
        shouldStart: false
    }
    render() {
        <Wrapper isBackgroundWhite={this.state.shouldStart}>
        	<Tree canStart={this.state.shouldStart} />
        </Wrapper>
    }
}

As you can see in this simplified example, the FirstSection is a stateful component - which is marked by the class keyword - that holds a shouldStart state and renders a Tree which canStart prop is defined by its parent state. It may sound complicated at first, but you'll get the hang of it!

Following this logic, we get to a very common pattern in React apps: there's a wrapping component that holds the whole project and that contains a huge state, with most of the mutable data of the application. This "root component" then passes down parts of this state to each "child component", as needed. This way, we can distribute a logged-in user's info throughout the header, to show the name and avatar, the user dashboard, and to a input field to leave a message with their name on it, for example.

Slack is a good example of this - and is also built in React: the same information - my username and contact info - is stored in the app's root state, in a central directory that distributes this data to the sidebar, the chat and the profile information.

In summary

React advocates for modularity in code, with the creation of reusable components that interact between each other - able to contain and be contained by others. These can pass down props to their child components and/or have internal states, which they can use to search for data, displaying info, reacting to user interaction, controlling animations, etc. React, then, as the library's own name suggests, reacts to changes in state and props and re-renders the interface to the screen. C'est tout!

What does this mean for you as a designer

You don't have to know how React does it, or even what are the possibilities for sites and apps, but you need to understand the component <> props <> state dynamic. It shapes the way we developers think about the structure of the app, the formation of the data (content) and in the variation of different visual components; and, of course, our code revolves around it. And it should shape your design process as well. In the example below, I try to show you why this is relevant.

Practical exemple: testimonial card

Let's take the testimonial card we created for Selleta's site as an example: the visual design below is what I got from my teammate to develop. As beautiful as it is (great job, Vítor!), it has a few problems, which we'll discuss with the concepts you learned about React.

There are two main things with this design:

• We can't guarantee the quality, orientation or focus of the pictures that will be uploaded about the person, which makes this image mask in the shape of the logo quite fragile: it could be a terrible photo, which focus is outside of the mask, making it impossible for visitors to understand it. So, when using pictures in your design that could be altered by users or clients, work with bad photos and see if they work as well 😉
• A testimonial is already something a bit difficult to obtain and, many times, the info contained in them will be incomplete or in and unexpected format... The props that a TestimonialCard could receive, therefore, aren't very predictable:
  • The person can prohibit the usage of their picture;
  • The text body can be HUGE - testimonials with over 2 paragraphs aren't uncommon;
  • The icon should say something about the person giving the testimonial, and so we need to spend a good time providing a good selection of options for our client to choose from, else, if we leave it to them, they'll provide icons of various styles, breaking the design language. This means quite a lot of work and time dedicated to such a small task;
  • The person's title could be way too lengthy to fit into the card - "Aluno de projetos arquitetônicos" is already quite large, but these particular clients had people with titles such as "Coordenador do projeto 'Casa para todos' da UFMT", which is even bigger 😝

If I were to blindly reproduce this design in code, I could get to the following situation:

The result isn't catastrophic, but the building's image is being cropped at the wrong place, the second card is way bigger than the other and the icon kept the same, making it a bit repetitive... Of course we can limit the number of characters in the content management system (CMS), make a very thorough list of icons for choosing and trying to instruct clients to only upload images with a focus in the middle... but, at the bare minimum, this approach isn't trivial for the developer, who will have to make assumptions. This lack of communication wastes development time and leads to worse results.

And say, for example, that a TestimonialCard didn't get an image prop passed down? Which of the options below the dev should put forward?

Both solutions are easy to implement, the problem isn't code... but they have different implications. When developing, I try to avoid asking "small" questions to the designers in order to avoid wasting their time and to speed up my work, but there are often times I have to revise these tiny decisions later on, wearing me out and slowing the delivery of the project.

So, next time you're creating an interface's wireframe and visual design, think pragmatically about the props that each component needs and start to think about all the possible scenarios. It's going to be a little bit of extra work, but the end result will satisfy you a lot more and your devs will be thankful!

My dream is to find good organization such as the above image in every project 😄

TL;DR: turns out that, even with all the machine learning hype, computers are dense when it comes to understanding what a specific data means and how it's related to the rest of the web... but you can help them - and help yourself with better SEO in the process - by structuring and linking your data with JSON-LD, RDFa and Microdata!

Prelude: computers need clarification on content

Manu Sporny does a great job at explaining the concept of linked data through his video on what is linked data?, check it out if you want to go deeper ;) If you don't, then all you need to know is that with so much content on the web, it's difficult for bots to understand what each page is talking about, leave alone the relationship between them.

For example, if a blog post cites Jair Bolsonaro and links it to an URL, the crawler will have a hard time figuring out if the link refers to the personal website of this person or, say, to a news article on what a monster this manipulator is (not related, but great read, don't let fascism win!). To help the computer, you can use one of the available syntaxes to tell computers what exactly the link is talking about, like so:

<!--
  Example done with a mixture of RFDa (vocab, typeof and property)
  and Microdata (itemscope, itemtype)
-->
<p vocab="http://schema.org/" typeof="Person">
  <span property="name">Jair Bolsonaro</span>,
  member of the <span property="memberOf">PSL party</span>,
  is a <span property="jobTitle">monstrous politician</span> with
  <a href="https://blog.post" property="url"
    itemscope itemtype="https://schema.org/NewsArticle"
  >very controversial opinions</a>.
</p>

This makes it clear that the "person" Jair Bolsonaro is a monstrous politician from the PSL party, whose URL is a news article. In this guide, I intend to show how this is relevant and how to use it, but it's far from a super complete and proven guide, so feel free to give feedback and read more from this articles' references ;)

Why care