DEV Community: Nicolas Goutay

Building a Component Library in Rails With Storybook

Nicolas Goutay — Mon, 26 Apr 2021 14:59:05 +0000

In recent years, the Rails ecosystem improved by leaps and bounds and is catching up with the evolutions that developers use and love in JavaScript frameworks.

Under the code name NEW MAGIC (now known as Hotwire), the Basecamp team released Turbo and Stimulus in 2020, adding powerful capabilities such as near-instant navigation, first-party WebSocket support, lazy-loading parts of your application, and many others.

However, the Rails development I’m most excited about is the ability to build your own component library, powered by View Component and Storybook.

A component library is a set of components (buttons, alerts, domain-specific widgets, etc.) that can be reused throughout the app, reducing the need for duplication and improving the consistency of our UX and codebase.

This article will explain how to create your own component library of View Components and deploy it with Storybook, enabling all your team members to try, tweak and audit them in isolation.

A Primer on View Components and Storybook

Last fall, I stumbled upon a great RailsConf talk called Encapsulating Views by Joel Hawksley, introducing the View Components gem—GitHub’s take on making React-like components in Rails a reality.

View Components make it easy to build reusable, testable & encapsulated components in your Ruby on Rails app. We will not dive deeply into View Components in this post, but if you’re not familiar with them, I highly recommend taking a look at the first few paragraphs of the docs before continuing—they do a great job at explaining their benefits and use cases.

At Orbit, we are slowly building a list of View Components that we reuse across the app—buttons, selects, dropdowns,… However, as the list grows, it’s becoming harder for the whole team (engineering, design, and product) to know what is already available and reusable. We needed a way to organize this library.

A common (and honestly amazing) tool for such component libraries in JS-based apps is called Storybook. Storybook is an interface that provides an interactive playground for each component, alongside its documentation and other niceties. Here are some examples of Storybooks:

Here’s the one from The Guardian
The one from GitLab
From Shopify
And our very own at Orbit!

Storybook used to be only compatible with Single Page Apps created with JavaScript frameworks: React, Vue, Angular, and many others. Fortunately for us, the recent V6 release of Storybook introduced the @storybook/server package, which allows for any HTML snippet to be used as a component in Storybook. Theoretically, this allows for a Rails backend to render the components for Storybook. But how does that work in practice?

For the purpose of this article, we’re going to work off of a fresh Rails project and work our way through installing the required gems, create our first ViewComponent, display it in Storybook, and deploy it alongside our app. The source code for this Rails project is available on GitHub: https://github.com/phacks/rails-view-components-storybook.

If you’d rather jump into a particular section (as you might already be familiar with some of the concepts we’ll cover), here’s the outline for the rest of the article:

Setting up a fresh Rails install
Creating our first View Component
Setting up component previews
Setting up Storybook with the ViewComponent::Storybook gem
Writing a story for our ButtonComponent
Deploying our Storybook alongside our app
Conclusion

Setting Up a Fresh Rails Install

Let’s create a new Rails project by following the steps listed in Section 3.1 in the Rails Getting Started guide, then run

rails new rails-view-components-storybook
cd rails-view-components-storybook
rails webpacker:install

# in one terminal window
bin/webpack-dev-server

# in another terminal window
rails server

That should get a Rails project up and running at http://localhost:3000

We’re going to add a static page to our Rails app which will serve as a kitchen sink to view and interact with our upcoming View Components. To do so, we can create or update the following files:

app/controllers/pages_controller.rb

class PagesController < ApplicationController
  def show
    render template: "pages/#{params[:page]}"
  end
end

config/routes.rb

Rails.application.routes.draw do
  get "/pages/:page" => "pages#show"
end

app/views/pages/kitchen-sink.html.erb

<article class="prose m-24">
  <h1>ViewComponents kitchen sink</h1>
  <p>This page will demo our ViewComponents</p>
</article>

We should now see that new page over at http://localhost:3000/pages/kitchen-sink. Great!

In order to add styles to our upcoming components, we’re going to add TailwindCSS (a utility-first CSS framework). Please note that it is not a requirement for either Storybook or ViewComponents—we only install it here for conciseness and convenience in styling our component. You do not need to have any prior knowledge of Tailwind to continue reading this article.

Replace the contents of app/views/layouts/application.html.erb with:

<!DOCTYPE html>
<html>
  <head>
    <title>RailsViewComponentsStorybook</title>
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <%= csrf_meta_tags %>
    <%= csp_meta_tag %>

    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
    <link rel="stylesheet" href="https://unpkg.com/tailwindcss@^2/dist/base.min.css" />
    <link rel="stylesheet" href="https://unpkg.com/tailwindcss@^2/dist/components.min.css" />
    <link
      rel="stylesheet"
      href="https://unpkg.com/@tailwindcss/typography@0.2.x/dist/typography.min.css"
    />
    <link rel="stylesheet" href="https://unpkg.com/tailwindcss@^2/dist/utilities.min.css" />
  </head>

  <body>
    <%= yield %>
  </body>
</html>

Note: although using unpkg is the simplest way to install TailwindCSS, it is not recommended to do so for production applications as it will cause performance issues. Should you want to install TailwindCSS for a production application, I’d recommend following their instructions.

Creating Our First View Component

Buttons are one of the most commonly used UI components throughout web applications, and are usually one of the first that comes to mind when the time comes to create a component library. Let’s build a Button ViewComponent!

In the Gemfile, add

 gem "view_component", require: "view_component/engine"

Then run bundle install and restart the Rails server to finish installing the ViewComponents gem.

We want our button to have different styles depending on how we’re planning to use it: primary, outline and danger. Let’s create a new ViewComponent called Button with a type property:

# in another terminal window
bin/rails generate component Button type --preview

This command generates four files:

app/components/button_component.rb: the ViewComponent itself;
app/components/button_component.html.erb: its template;
test/components/button_component_test.rb: its test suite;
test/components/previews/button_component_preview.rb: its preview.

We’re not going to cover ViewComponents testing in this post; if you’re curious, the relevant docs page is a great resource to get started.

Let’s define our component template so that it outputs a styled <button> rendering the content passed into the ViewComponent:

app/components/button_component.html.erb

<button class="<%= classes %>">
  <%= content %>
</button>

Then, we can add the logic to apply different classes for the different types:

app/components/button_component.rb

# frozen_string_literal: true

class ButtonComponent < ViewComponent::Base
  attr_accessor :type

  PRIMARY_CLASSES = %w[
    disabled:bg-purple-300
    focus:bg-purple-600
    hover:bg-purple-600
    bg-purple-500
    text-white
  ].freeze
  OUTLINE_CLASSES = %w[
    hover:bg-gray-200
    focus:bg-gray-200
    disabled:bg-gray-100
    bg-white
    border
    border-purple-600
    text-purple-600
  ].freeze
  DANGER_CLASSES = %w[
    hover:bg-red-600
    focus:bg-red-600
    disabled:bg-red-300
    bg-red-500
    text-white
  ].freeze
  BASE_CLASSES = %w[
    cursor-pointer
    rounded
    transition
    duration-200
    text-center
    p-4
    whitespace-nowrap
    font-bold
  ].freeze

  BUTTON_TYPE_MAPPINGS = {
    primary: PRIMARY_CLASSES,
    danger: DANGER_CLASSES,
    outline: OUTLINE_CLASSES
  }.freeze

  def initialize(type: :primary)
    @type = type
  end

  def classes
    (BUTTON_TYPE_MAPPINGS[@type] + BASE_CLASSES).join(' ')
  end

end

And finally we can instantiate all three types of buttons in our kitchen sink page:

app/views/pages/kitchen-sink.html.erb

<article class="prose m-24">
  <h1>ViewComponents kitchen sink</h1>
  <p>This page will demo our ViewComponents</p>

  <h2>ButtonComponent</h2>
  <h3>Primary</h3>
  <%= render(ButtonComponent.new(type: :primary)) do %>
    Submit
  <% end %>

  <h3>Outline</h3>
  <%= render(ButtonComponent.new(type: :outline)) do %>
    Cancel 
  <% end %>

  <h3>Danger</h3>
  <%= render(ButtonComponent.new(type: :danger)) do %>
    Delete
  <% end %>
</article>

We have our ButtonComponent all ready for others to use!

Setting Up Component Previews

ViewComponents come ready with a handy feature: component previews. They allow us to get a URL in which to view and interact with our ViewComponent in isolation.

We can see the preview for our ButtonComponent at the following URL: http://localhost:3000/rails/view_components/button_component/default

The default preview instantiates the ButtonComponent without any parameters, which explains why we see the :primary button type and no content. We can update the preview file to teach it about the different variants:

test/components/previews/button_component_preview.rb

class ButtonComponentPreview < ViewComponent::Preview
  def default(type: :primary)
    type = type.to_sym if type

    render(ButtonComponent.new(type: type)) { 'Button' }
  end
end

We can then control our component through the type and content query params. For example, http://localhost:3000/rails/view_components/button_component/default?type=danger will render a red button, and http://localhost:3000/rails/view_components/button_component/default?type=outline will render an outlined one.

Let’s also add individual stories for each button state. That makes it easy to reason about as the component grows in supported states because it reduces ambiguity about which props are intended to be used together:

test/components/previews/button_component_preview.rb

class ButtonComponentPreview < ViewComponent::Preview
  def default(type: :primary)
    type = type.to_sym if type

    render(ButtonComponent.new(type: type)) { 'Button' }
  end

  def primary
    render(ButtonComponent.new(type: :primary)) { 'Submit' }
  end

  def outline
    render(ButtonComponent.new(type: :outline)) { 'Cancel' }
  end

  def danger
    render(ButtonComponent.new(type: :danger)) { 'Delete' }
  end
end

We can check that these previews work as intended by visiting the following URLs:

This mechanism will be leveraged in the next section to control our ViewComponent through Storybook controls. It’s time to add Storybook to our project!

Setting Up Storybook With the `ViewComponent::Storybook` Gem

The view_component_storybook gem is the bridge between Ruby on Rails land and Storybook. It gives us a Ruby DSL in which we can write stories (Storybook’s main concept: think a specific state of a UI component), that will then be translated in Storybook parlance. It also takes care of gluing together the ViewComponents previews and Storybook’s API.

Important note: the instructions below differ from the view_component_storybook official docs. This version allows for easier deployment of the Storybook to a public URL, which will be discussed in Deploying our Storybook alongside our app. If you don’t plan on deploying your Storybook, you might want to follow the official docs instead.

First, in our console, we can install the following Storybook packages. This is required to get the Storybook interface up and running:

yarn add @storybook/server @storybook/addon-controls --dev

Then, let’s add the view_component_storybook gem to your Gemfile and declare it in our application:

Gemfile

gem "view_component_storybook"

config/application.rb

require_relative "boot"

require "rails/all"

# Require the gems listed in Gemfile, including any gems
# you've limited to :test, :development, or :production.
Bundler.require(*Rails.groups)

module RailsViewComponentsStorybook
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 6.1

    # Configuration for the application, engines, and railties goes here.
    #
    # These settings can be overridden in specific environments using the files
    # in config/environments, which are processed later.
    #
    # config.time_zone = "Central Time (US & Canada)"
    # config.eager_load_paths << Rails.root.join("extras")

    require "view_component/storybook/engine"

    # Enable ViewComponents previews
    config.view_component.show_previews = true
  end
end

We can then create the Storybook configuration files in a new .storybook folder located at the root of the project:

.storybook/main.js

module.exports = {
  stories: ["../test/components/**/*.stories.json"],
  addons: ["@storybook/addon-controls"],
};

.storybook/preview.js

export const parameters = {
  server: {
    url: `${location.protocol}${location.hostname}${
      location.port !== "" ? ":3000" : ""
    }/rails/view_components`,
  },
};

We’ll wrap up the setup by adding shortcuts in package.json to build the Storybook files:

package.json

 {
  "name": "rails-view-components-storybook",
  // ...
  "scripts": {
    "storybook:build": "build-storybook -o public/_storybook"
  }
}

We can then restart the Rails server to account for the new gem.

Phew! That was quite a lot of configuration—fortunately, we only have to set everything up this one time. We should now be all up and running. Let’s check that Storybook is properly set up by running yarn storybook:build and visiting http://localhost:3000/_storybook/index.html

While we have Storybook up and running, you might notice that our ButtonComponent is nowhere to be found. That’s totally normal: we need to write a story for it first.

Writing a Story for Our Button Component

In Storybook, a story represents the state of a UI component. A component can have one or many stories, usually depending on its complexity: one can imagine a Select component with a few options, or a lot, or not at all. In our case, we’ll create a story for each state of our Button component (:primary, :outline and :danger) and another, default one that will allow us to control the type interactively.

A story can also define one or more controls: those will define the interactive bits of our components. In our default story, we can define a control for the button type. That control will be a select as we want the Storybook visitor to be able to select the type between the three available options. There are a lot more controls available in the view_component_storybook gem, and the full list is available here.

Let’s create a story for our component using the Story DSL of view_component_storybook:

test/components/stories/button_component_stories.rb

class ButtonComponentStories < ViewComponent::Storybook::Stories
  story(:default) do
    controls do
      select(:type, %w[primary outline danger], 'primary')
    end
  end

  story(:primary) {}
  story(:outline) {}
  story(:danger) {}
end

We can now ask view_component_storybook to convert that Ruby story to a JSON one, which will then automatically get picked up by Storybook:

rake view_component_storybook:write_stories_json

This generates a new button_component.stories.json file alongside the Ruby story that is compatible with Storybook’s API.

Let’s re-build our Storybook instance to see that story in action:

Now, http://localhost:3000/_storybook/index.html should display our Button in the different state, and the associated controls to interactively change its type for the default story.

Congratulations—we have created our first component in our Rails component library!

Deploying Storybook Alongside Our app

A component library works best when the whole team—engineers, designers, product folks—can see which components are available, know which variants and customization options are available, and get a sense of how they can be used by using them directly. A publicly accessible URL is a great way to achieve this, as one can then include a link to a particular component variant when discussing an upcoming feature.

At its core, Storybook is a React app—which means that deployment is a matter of hosting a static website. We aimed for a simple setup for our Storybook, and found one right under our nose: Rails is very capable of hosting static webpages itself!

As you might have noticed, you had to run yarn storybook:build for our story to appear in Storybook. We defined that command in package.json as followed:

"storybook:build": "build-storybook -o public/_storybook"

What this command does under the hood is compile all the files from Storybook and storing them under the public/_storybook directory of our Rails application. Because files under public are accessible publicly in Rails, this results in the Storybook being accessible at the URL <YOUR_APP_ROOT_URL>/_storybook/index.html. That’s the reason why we were able to see our local Storybook instance at http://localhost:3000/_storybook/index.html!

The main advantage of that solution is that deploying Storybook is now completely transparent and integrated into your Rails deployment pipeline. When adding a new component, updating a story, or installing a Storybook Addon, we only need to run yarn storybook:build and commit the resulting files for those updates to be deployed alongside the rest of our Rails app.

To illustrate that point, let’s take the example of the Rails app we’ve been using for this article. You can visit the Rails app itself at https://rails-view-components-storyboo.herokuapp.com/pages/kitchen-sink, and the Storybook we just built at https://rails-view-components-storyboo.herokuapp.com/_storybook/index.html. Ain’t that cool?

Conclusion

In this article, we saw how we can leverage the view_component and view_component_storybook gems to build a Storybook component library in a Rails app.

The setup described here is admittedly simple, but our team at Orbit is happily using and refining it, and it helps us iterate faster on UI components. We also rely on Storybook Addons for automatic accessibility audits, components documentation, inline Figma designs, and more. If you’re curious about our setup or would like to discuss this article, feel free to reach out on Twitter—I’d be happy to chat! And if you enjoy

The intersection of Rails, ViewComponents, and Storybook is an exciting, burgeoning, and fast-evolving space. If you’re curious, you can learn more about how GitHub uses ViewComponents for its Primer design system in this Ruby Blend episode (podcast), take a deep dive to understand how they are implemented in this RailsConf 2020 conference talk (video), or get inspired by the components used by Gov.UK (docs).

P.S. We're hiring! Check out our careers page and read our key values.

Declaring multiple sets of scopes for the same provider with Devise and OmniAuth in Rails

Nicolas Goutay — Wed, 06 Jan 2021 12:45:01 +0000

Photo by Stephen Phillips - Hostreviews.co.uk on Unsplash

If you’re familiar with the Rails ecosystem, the names Devise and OmniAuth might ring a bell: the former is a gem that handles (nearly) everything related to authentication; coupled with the latter, it makes implementing popular Social Login providers (e.g. Login with Facebook, or Twitter, or GitHub…) a breeze.

They can also be used to abstract away the whole OAuth dance that developers need to wrangle with every time they want to connect to a third-party API. We use it extensively at Orbit to authenticate with the GitHub, Twitter, Discourse, and Slack APIs, allowing us to build powerful integrations on top of those.

Take Slack, for example. Our Slack App connects Orbit to our users’ Slack workspaces to send notifications and provide a handy /orbit command.

Here’s what the OmniAuth provider for that looks like:

config.omniauth :slack,
                ENV['SLACK_CLIENT_ID'],
                ENV['SLACK_CLIENT_SECRET'],
                scope: 'commands,chat:write,chat:write.public,channels:read'

In some cases, however, you might need two different sets of scopes for two distinct integrations with the same service.

As we’re building our Slack Integration, which will allow users to gather and analyze the activity in their community Slack, we realized that we needed users to authorize to Slack twice: once on their team Slack, for the Slack App, and once on their community Slack, for the Slack integration. Moreover, the required scopes would differ wildly: as the Slack App needs to post messages and respond to slash commands, the Slack integration would only need to listen to events (e.g. somebody joined, or posted a message).

Adding both sets of scopes to our single OmniAuth provider would have worked, but it is considered (rightly) a security risk to ask for too broad a scope: in our case, the Slack App has no business listening to new messages and the Slack Integration shouldn’t be able to post messages in a channel.

So we needed to create two sets of scopes (one for the App, one for the Integration) for the same provider (Slack).

The first step was to rename our existing provider (the one above) to :slack_app. By doing this however, we lose the implicit binding of that provider to the Slack strategy—which we can hopefully add back with the strategy_class option:

config.omniauth :slack_app,
                ENV['SLACK_APP_CLIENT_ID'],
                ENV['SLACK_APP_CLIENT_SECRET'],
                scope: 'commands,chat:write,chat:write.public,channels:read',
                strategy_class: OmniAuth::Strategies::Slack

This gets us close, but not yet there: this config will set the provider attribute of the OAuth return payload to slack, not slack_app—meaning the callback route cannot know whether this particular user authorized the Slack App or the Slack Integration.

We can get around this by adding the name: slack_app option, which will do two things:

Set the provider attribute of the OAuth return payload to the right value, and
Change the OAuth callback route to /users/auth/slack_app/callback instead of /users/auth/slack/callback. (If you’re curious, here’s the bit of code in OmniAuth that’s responsible for inferring the callback URL.)

After changing the app/controllers/users/omniauth_callbacks_controller.rb to reflect the change in the URL (slack becomes slack_app), everything is running smoothly again.

We can now add our second provider for the Slack Integration, with its distinct name and scope.

config.omniauth :slack_app,
                ENV['SLACK_APP_CLIENT_ID'],
                ENV['SLACK_APP_CLIENT_SECRET'],
                name: 'slack_app',
                scope: 'commands,chat:write,chat:write.public,channels:read',
                strategy_class: OmniAuth::Strategies::Slack

config.omniauth :slack_integration,
                ENV['SLACK_INTEGRATION_CLIENT_ID'],
                ENV['SLACK_INTEGRATION_CLIENT_SECRET'],
                name: 'slack_integration',
                scope:
                  'channels:history,channels:read,reactions:read,users:read.email,users.profile:read',
                strategy_class: OmniAuth::Strategies::Slack

Tada! Our users can now authorize only minimal scopes for the App, the Integration, our both—a win for security!

OAuth can often feel confusing, and I want to take this opportunity to thank the Devise and OmniAuth maintainers and contributors who are doing a remarkable job to make it easier for the rest of us.

Hope this article can help folks facing the same issues we did!

How to: add Twitter and Instagram Embeds on an Eleventy website using Sanity

Nicolas Goutay — Mon, 13 Jul 2020 13:43:01 +0000

Cover image credits: Photo by Luismi Sánchez on Unsplash

At Orbit, we recently rebuilt our website from the ground up using a Jamstack approach and more specifically using Eleventy as our Static Site Generator and Sanity (https://sanity.io) as our CMS. I’ve talked a bit more about our approach and tech stack in the following Twitter thread:

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

One thing we wanted to keep from our old blog was the ability to easily embed Tweets or Instagram posts, as they can allow us to provide context, color, or variety to what could otherwise be a wall of text.

See how this tweet from David breaks up the text nicely?

In this post, we will walk through the Sanity setup and the Eleventy configuration that makes this possible—and even more importantly, really simple to use for editors!

Note: this post is aimed at developers who are already comfortable with both Sanity and Eleventy, as I am not going to explain how to set up either one of these tools. Fortunately, Sanity already has a template handy to get started in minutes!

Step 1: the Sanity Studio setup

Our first order of business will be to teach Sanity what a “Twitter” or “Instagram” block consists of.

As is usually the case in embeds, we’re going to refer to specific tweets or Instagram posts by their ID, visible in their URL:

https://twitter.com/Phacks/status/1281221982613311496 # ID: 1281221982613311496
https://www.instagram.com/p/CB-yYetJ4ky/ # ID: CB-yYetJ4ky

This is the approach taken here on DEV, as you would display those Twitter or Instagram embeds with the following Liquid tags:

{% twitter 1281221982613311496 %}
{% instagram CB-yYetJ4ky %}

We can then define our Sanity schemas, saying that both a twitter block and an instagram have only one field, id:

// ./schemas/objects/twitter.js

export default {
  name: 'twitter',
  type: 'object',
  title: 'Twitter Embed',
  fields: [
    {
      name: 'id',
      type: 'string',
      title: 'Twitter tweet ID'
    }
  ]
}

// ./schemas/objects/instagram.js

export default {
  name: 'instagram',
  type: 'object',
  title: 'Instagram Embed',
  fields: [
    {
      name: 'id',
      type: 'string',
      title: 'Instagram post ID'
    }
  ]
}

And import them to the available schemas in Sanity Studio:

// First, we must import the schema creator
import createSchema from 'part:@sanity/base/schema-creator'

// Then import schema types from any plugins that might expose them
import schemaTypes from 'all:part:@sanity/base/schema-type'

import bodyPortableText from './objects/bodyPortableText'

// We import 
import instagram  from './instagram'
import twitter  from './twitter'

// Then we give our schema to the builder and provide the result to Sanity
export default createSchema({
  name: 'default',
  // Then proceed to concatenate our document type
  // to the ones provided by any plugins that are installed
  types: schemaTypes.concat([
    // ... other schemas
    bodyPortableText,
    // Will be available as { type: 'typename' } in bodyPortableText
    instagram,
    twitter
  ])
})

One last step before we can see our new blocks available in Studio: we need to import them into bodyPortableText:

// bodyPortableText.js
export default {
  name: 'bodyPortableText',
  type: 'array',
  title: 'Body',
  of: [
    // ... other blocks 
    {
      type: 'twitter'
    },
    {
      type: 'instagram'
    }
  ]
}

We can now see our new blocks right inside Sanity Studio’s editor, nice!

Step 2: previewing embeds in Sanity Studio

The editor experience is not satisfying yet, as there’s little visual feedback on the tweet or the Instagram post that is embedded. This can be solved using previews in Sanity Studio: we’re going to tell Studio how we want those blocks to look like inside the editor.

We won’t reinvent the wheel here and rely on the react-twitter-embed and react-instagram-embed packages to handle the previews for us.

After installing the packages with npm install --save react-twitter-embed react-instagram-embed, let’s define the previews in twitter.js and instagram.js:

// schemas/objects/twitter.js
import React from 'react'
import { TwitterTweetEmbed } from 'react-twitter-embed';

const Preview = ({value}) => {
  const { id } = value
  return (<TwitterTweetEmbed tweetId={id} options={{ conversation: "none" }} />)
}

export default {
  name: 'twitter',
  type: 'object',
  title: 'Twitter Embed',
  fields: [
    {
      name: 'id',
      type: 'string',
      title: 'Twitter tweet id'
    }
  ],
  preview: {
    select: {
       id: 'id'
    },
    component: Preview
  }
}

// schemas/objects/instagram.js
import React from 'react'
import InstagramEmbed from 'react-instagram-embed';

const Preview = ({value}) => {
    const { id } = value
    return (<InstagramEmbed url={`https://www.instagram.com/p/${id}/`} />)
}

export default {
  name: 'instagram',
  type: 'object',
  title: 'Instagram Embed',
  fields: [
    {
      name: 'id',
      type: 'string',
      title: 'Instagram post ID'
    }
  ],
  preview: {
    select: {
      id: 'id'
    },
    component: Preview
  }
}

And there we go! Twitter and Instagram embeds are now nicely displayed inside the editor. Sweet!

Step 3: displaying embeds in Eleventy

With the ability to add Twitter or Instagram embeds in Sanity Studio, we now turn to our Eleventy setup to try and display them in our blog posts.

Sanity uses a specification called Portable Text to allow editors and developers to extend the semantics of Markdown or HTML and allow for custom blocks of content, like our embeds there.

One way to translate those custom blocks into actual markup for websites is to use a serializer pattern that takes the JSON representation of the blocks as inputs and outputs the proper HTML. For example, here is the serializers.js file that comes with the Sanity Eleventy blog template, which translates the blocks authorReference, code and mainImage:

const imageUrl = require('./imageUrl')

// Learn more on https://www.sanity.io/docs/guides/introduction-to-portable-text
module.exports = {
  types: {
    authorReference: ({node}) => `[${node.name}](/authors/${node.slug.current})`,
    code: ({node}) => '```

' + node.language + '\n' + node.code + '\n

```',
    mainImage: ({node}) => `![${node.alt}](${imageUrl(node).width(600).url()})`
  }
}

Our objective in this section will be to add two new serializers, twitter and instagram, that will take care of rendering the embeds.

Displaying Twitter embeds in Eleventy

We are going to use the official twttr.js library to embed Tweets into our blog posts. We do not reuse twitter-react-embed here, because that would require a React runtime. For performance reasons, it is best to not include a JavaScript framework if one does not really need it.

Following the Twitter documentation, inserting the following Javascript snippet inside our _includes/layout/post.njk template will load the twttr.js library, and turn all <div class="tweet" id="123456789"> nodes into full-blown twitter embeds:

<script>
  if (document.getElementsByClassName('tweet').length > 0) {
    window.twttr = (function (d, s, id) {
      var js,
        fjs = d.getElementsByTagName(s)[0],
        t = window.twttr || {}
      if (d.getElementById(id)) return t
      js = d.createElement(s)
      js.id = id
      js.src = 'https://platform.twitter.com/widgets.js'
      fjs.parentNode.insertBefore(js, fjs)

      t._e = []
      t.ready = function (f) {
        t._e.push(f)
      }

      return t
    })(document, 'script', 'twitter-wjs')
  }
</script>

<script>
  if (window.twttr !== undefined) {
    twttr.ready(function (twttr) {
      Array.from(document.getElementsByClassName('tweet')).forEach((tweet) => {
        const id = tweet.getAttribute('id')
        twttr.widgets.createTweet(id, tweet, {
          conversation: 'none', // or all
          cards: 'hidden', // or visible
          linkColor: '#cc0000', // default is blue
          theme: 'light', // or dark
        })
      })
    })
  }
</script>

We can now turn to our serializers.js file and turn each block into the corresponding <div class="tweet" id="<tweetID>"> node:

// utils/serializers.js
module.exports = {
  types: {
    authorReference: // ...
    code: // ...
    mainImage: // ...
    twitter: ({ node }) => `<div id="${node.id}" class="tweet"></div>`,
  }
}

Tada! Tweets that we embed in Sanity Studio are now directly embedded, at the right place, inside our blog posts:

Displaying Instagram embeds in Eleventy

Instagram embeds will work very similarly to Twitter ones: using the official library, we’ll add a JavaScript snippet that will turn specific DOM nodes into proper Instagram posts.

Following the Instagram documentation, we can append this snippet to the _includes/layout/posts.njk template:

<script>
  Array.from(document.getElementsByClassName('instagram')).forEach(
    async (instagram) => {
      const url = instagram.getAttribute('data-url')
      const response = await fetch(
        `https://api.instagram.com/oembed?url=${url}&maxwidth=480&hidecaption&omitscript`
      )
      const { html } = await response.json()
      // https://stackoverflow.com/a/35385518
      instagram.innerHTML = html
      var tag = document.createElement('script')
      tag.src = '//www.instagram.com/embed.js'
      tag.setAttribute('async', true)
      document.getElementsByTagName('head')[0].appendChild(tag)
    }
  )
</script>

and update our serializers.js file accordingly:

// utils/serializers.js
module.exports = {
  types: {
    authorReference: // ...
    code: // ...
    mainImage: // ...
    twitter: ({ node }) => `<div id="${node.id}" class="tweet"></div>`,
    instagram: ({ node }) => `<div data-url="https://www.instagram.com/p/${node.id}" class="instagram"></div>`,
  }
}

We now have Instagram embeds available in our blog posts!

Conclusion, source code, and further reading

In this article, we learned how to add Twitter and Instagram embeds to Eleventy blog posts using Sanity’s Portable Text capabilities.

The source code for the resulting Eleventy blog and Sanity Studio is available here: https://github.com/phacks/sanity-eleventy-twitter-instagram-embed.

Should you want to dig further on the topic, I can recommend the following resources:

How to add a custom YouTube block by Knut Melvær on Sanity’s website;
This Eleventy plugin to embed tweet directly with a custom directive by Kyle Mitofsky, which makes the tradeoff of better performance (the tweets are fetched at build time) for a slightly more difficult set up (you need a Twitter API token) and a minimal Twitter integration (no like or retweet counter, no conversations).

The rocky road to implementing link prefetching in Rails

Nicolas Goutay — Tue, 19 May 2020 14:41:28 +0000

Cover image credits: Photo by Melanie Dretvic on Unsplash

Web performance matters for many reasons: a better, more inclusive user experience; less waste of resources (your user’s devices will thank you); and an increase in business metrics like conversion, SEO traffic, and even revenue.

It also happens that it is one of my favorite technical topics, and I fell down the rabbit hole of optimizations (and got to talk about it) more than one time.

Yesterday, I found a new itch I had to scratch, and it all started by the release of InstantPage v5 by Alexandre Dieulot.

Alexandre Dieulot

@dieulot

⚡⚡⚡ Make your site’s pages FASTER THAN INSTANT.

In 1 minute.

👉🏼 instant.page/v5

14:30 PM - 16 May 2020

Instant Page has a very enticing promise: what if, by dropping a single line of code into your app, you could make it feel instant?

InstantPage achieves this by using a technique called link prefetching. Traditionally, a website loads the HTML contents of a new page when the user has clicked on its link. InstantPage takes full advantage of the fact that to click a link, the user has to get there, and usually spends a few hundred milliseconds hovering on it. By triggering the page load on hover, instead of on click, we can shave off those few hundred milliseconds of load time, making the transition to the new page feel instant.

You can see this pattern in action on this very website, dev.to! Feels fast, doesn't it?

So I set up to implement that in our Ruby on Rails application, and boy was it a wild ride. Buckle up!

Note: Although my engineering background is heavily leaning on JavaScript, I joined the fine folks at Orbit a few weeks ago and this is my first experience with Ruby on Rails. So please, if I made a mistake somewhere, or missed an opportunity for a more idiomatic solution, let me know in the comments! Consider this my first attempt to #LearnInPublic.

The naive approach: using InstantPage itself

So, InstantPage says that a single line of code can make this work. Well… in our case, it didn’t. I could see the prefetching happen in the DevTools, but clicking on a link resulted in the same experience as before.

It turns out that InstantPage and Turbolinks (Rails integrated library to make navigation faster and Single Page App-like) do not pair well together:

Comment for #52

dieulot commented on Oct 12, 2019

I’ve talked privately with @dhh and he said he’s interested in bringing the just-in-time preloading mechanism into Turbolinks. I also plan to make an alternative to Turbolinks that uses them (in fact I already did so with InstantClick, but it lacks good documentation and a bunch of other things, I plan to reboot it). So maybe I won’t make instant.page compatible with Turbolinks in the next version, it will depend on ease of implementation, we shall see.

View on GitHub

Damn. Well, maybe Turbolinks already solved that problem and I don’t even need InstantPage?

A prefetching solution based on Turbolinks

A quick search in the Turbolinks repository issues showed that I was not the first one to want link prefetching:

turbolinks "instantclick" #313

Enalmada posted on Aug 09, 2017

I want to use turbolinks but there is something it isn't doing that others seem to be doing...fetching content on hover and using that on click.

This is the main idea behind instantclick.io and the concept seems critical to unlocking the full performance potential of turbolinks. Note that there seems to be some past discussion about prefetching in general that went to dark places (https://github.com/turbolinks/turbolinks/issues/84) talking about plugins and not universally supported hints. I feel like hints and plugins are overboard...I feel like doing the same thing as instaclick deserves to be natively supported...even the default behavior (with an opt-out attribute for server side analytics or mutable links).

If turbolinks did a fetch of link on hover (rather than click), and used that content on click, it would reduce up to several hundred milliseconds of latency for the average user. It is hard to believe at first but it is true...try it for yourself: http://instantclick.io/click-test. For a properly tuned backend just dealing with network latency, that amount of time can be the difference in user perception between a site being fast and being instant. (Note that barbajs also has similar option)

So turbolinks, can you please consider doing this?

View on GitHub

Reading through that 50+ comments discussion (!), I found that GitHub user
hopsoft helpfully shared a gist implementing a link prefetching strategy leaning on Turbolinks cache.

We’re making progress! I can see the prefetch request going out as I hover a link, and the navigation after I click feels faster.

However… I was not 100% convinced by this approach. Leveraging Turbolinks cache meant relying on Turbolinks preview behavior: if a page is warm in the cache, then Turbolinks will show that cached version as a preview (a static, non-interactive version) and then trigger a new request, using its results to really update the page.

With that in mind, this solution had the drawback of making two requests:

One on hover, which would warm Turbolinks cache;
One on click, which would be displayed after “flashing” the cached version.

This seemed a bit wasteful, as there was a very small chance that those two requests would differ—they were triggered a few hundred milliseconds apart after all.

Back to the drawing board!

Getting closer with InstantClick, InstantPage’s predecessor

In the GitHub comment highlighted previously, Alexandre piqued my curiosity:

I also plan to make an alternative to Turbolinks that uses them (in fact I already did so with InstantClick, but it lacks good documentation and a bunch of other things, I plan to reboot it).

Undeterred by the lack of documentation (I can’t decide if that’s brave or just plain dumb), I set out to try InstantClick and see if it could solve that duplicate request issue.

The InstantClick repository is pretty straightforward: an instantclick.js file that implements link prefetching, and a loading-indicator.js file that takes care of showing a fake loading indicator if a page load takes too long. Fake because it doesn’t reflect the real progress of the page, it just goes forward until the page finishes loading. This is a technique used by GitHub and dev.to that is easy to set up and is good enough for the vast majority of use cases, so that’ll do!

I copied and pasted both those files, and after a bit of Rails plumbing (I had to remove Turbolinks as it was clashing with InstantClick) and fixing some problems with React and forms (more on that later), it was all set up.

And… it worked!

Prefetching happened on hover, and no extra request went off on click. The app felt much faster, with most page transitions appearing instant. Happy times!

However, I noticed something off: hovering the same link multiple times triggered multiple requests. Again, this seemed a bit wasteful! I was curious about whether dev.to showed this behavior (they use a custom implementation of InstantClick). I fired up the Dev Tools on this very website, and lo and behold, it didn’t. Meaning that they found a way to fix it.

How? Well, let’s find out!

The beauty of Open Source: diving into dev.to’s codebase

The dev.to codebase is open source (which, by the way, is awesome), which meant that the solution to my problem was somewhere in the repository.

A quick GitHub in-repository search for InstantClick led me directly to their custom implementation which, to my surprise, was quite heavily integrated with their codebase. So copy-pasting the whole file wasn’t an option, and I had to put on my detective hat and figure out what is going on.

I knew I was looking at some kind of cache pattern, so I tried and find the method that was responsible for making HTTP requests—I figured that that method would check whether the results were already in said cache.

That was a hit!

The dev.to folks added a variable $fetchedBodies to InstantClick code that would save the URL, title, and body of any preload, which would then be available as a cache for subsequent requests.

Here is a simplified representation of that mechanism:

var $fetchedBodies = {}

function processXHR(xhr, url) {
  // Makes the XHR call, the response body and title are available
  // Use that response to add a new cache entry
  $fetchedBodies[url] = {body:body, title:title};
}

function preload(url) {
  // Responsible for preloading URLs
  // If the URL is already in the cache, then do not make the request
  if (!$fetchedBodies[url]){
    $url = url
    $xhr.open('GET', internalUrl)
    $xhr.send()
  }
}

function removeExpiredKeys(option) {
  // Handles the cache expiration
  if ( Object.keys($fetchedBodies).length > 13 || option == "force" ) {
    $fetchedBodies = {};
  }
}

Once I felt I had sufficiently grasped how it worked on dev.to, I ported it to our codebase, nearly as is. The only difference is in the cache expiration mechanism, where we forced an expiration with removeExpiredKeys("force") after each navigation to make sure that users do not see stale versions of a page.

Hurrah! No more multiple requests if a user hovers the same link multiple times. We just got ourselves a working, optimized, and mobile-friendly link prefetching implementation in Rails.

Getting it to work with React and interactive navigations

As mentioned previously, we had a bit more work to do to make InstantClick work with our existing app. In case it might help anyone else, I’m going to go over those bumps in the road and the fix we found.

First, it appeared that our React components were broken after navigating a link. According to this issue, React Rails do not automatically mount components when using prefetched links and we had to do that ourselves by calling ReactRailsUJS.mountComponents() in the JS initialization step.

Second, after the initial move to InstantClick some of table filtering/searching features stopped working, because they relied on programmatically tell Turbolinks to visit a URL with the proper query params:

<select onchange="if(event.target.value) Turbolinks.visit(event.target.value);")>…</select>

The InstantClick source code does not provide a method to navigate to a given URL. Luckily, this GitHub comment offered a clever solution: have JavaScript create a new link in the DOM with that URL and click on it.

InstantClick.go = function(url) {
  var link = document.createElement('a');
  link.href = url;
  document.body.appendChild(link);
  link.click();
}

We can now change the previous HTML code into this:

<select onchange="if(event.target.value) InstantClick.go(event.target.value);")>…</select>

Unfortunately… this crashes the JS of the page: the console tells us that InstantClick is undefined. The workaround to that came from Stack Overflow, and required some Webpack black magic to make InstantClick available as a global variable:

// in webpack.environment.js

// run yarn add --dev expose-loader exports-loader beforehand

const { environment } = require("@rails/webpacker");

const webpack = require("webpack");

environment.loaders.append("InstantClick", {
  test: /instantclick/,
  use: [
    {
      loader: "expose-loader",
      options: "InstantClick",
    },
    {
      loader: "exports-loader",
      options: "InstantClick",
    },
  ],
});

module.exports = environment;

It took many different helpful answers from around the internet, but all our problems are now solved!

Going further

Our custom InstantClick setup is available as a gist, feel free to use it!

We are pretty happy with our implementation for now, but it is important to point out that it can be improved even further:

Featured in the tweet that sparked all this (but absent from our implementation), the new release of InstantPage uses a clever trick: trigger the click event on mousedown, instead of the usual mousedown then mouseup. While this is promising in terms of perceived performance, I’m curious to hear about people’s reaction to this change in such a foundational experience as a click;
Our implementation does not respect the Save Data header, which might be an issue for users looking to reduce their bandwidth consumption (e.g. when traveling abroad);
Guess.js is a library that takes this whole idea of link prefetching one step further: using your analytics data and machine learning, it prefetches links the user is most likely to click on next. Ain’t that amazing?

Thanks for reading!