DEV Community: Orbit

Making Our Open Source Communities More Like Starfish

Ben Greenberg — Wed, 16 Jun 2021 07:51:43 +0000

Starfish are incredible animals.

Perhaps you never took the time to fully appreciate the complex simplicity that is a starfish. You may have enjoyed seeing them at the beach or the aquarium. You may have appreciated their beauty and their stillness, but underneath that beauty and that quiet tranquility, is a great deal of insight waiting for us to uncover.

Unlike us, starfish do not have a central organizing brain that manages executive decision making. Rather, starfish operate on the ultimate distributed system.

An entire new starfish can be grown from any single limb. Why is that? Because there is no one place, no one seat, where all decisions for the organism happens.

Starfish are also keenly aware of the resources in their environment. Which leads us to the next incredible fact. Starfish don't have blood to circulate nutrients and the like through their system. What do they use instead? Seawater!

Ocean water is, well, abundant in oceans. Why not take advantage of that resource and adapt accordingly?

Starfish, in their resourcefulness, awareness, and decentralization, are exemplars for our open source communities.

How so?

Ori Brafman and Rod Beckstrom in their work, The Starfish and the Spider: The Unstoppable Power of Leaderless Organizations demonstrate several key insights to be gleaned from the biological wonder of starfish.

I believe they can be encapsulated in the following four principles for open source software communities and the people who are invested in them:

Decentralization
Keeping it Simple
Adaptability
Everyone Contributes

Decentralization

"When you give people freedom, you get chaos, but you also get incredible creativity."
^{- The Starfish and the Spider}

Removing overly restrictive leadership structures and processes can be terrifying. As a community organizer and someone who has maintained several open source projects I can very much relate to that.

Do you know the people who care about your project? How will you enforce pull request standards? Code conventions? Testing coverage? Who will make sure every feature request is properly vetted and reviewed?

Decentralizing decision making does not mean that decision making does not happen. It means that there is not a single person or a few people deciding everything.

At Orbit we firmly believe that the future of community is distributed and decentralized.

When the character of Aaron Burr sings "I want to be in the room where it happens" in Hamilton, he is striving to be part of a classic leadership model where there are a few folks in a backroom somewhere who decide it all. If you want to have a voice in that process, you need to be in "the room where it happens".

Our open source projects should not have backrooms for decision making.

Tools like GitHub Discussions, and vehicles like committees, can help distribute and make transparent that load. A clear, simplified and streamlined process to join those work groups or committees is integral for decentralization.

Radical formulations of decentralized decision making removes the veto from "the leaders" and relies on communal consensus to discern project goals and aims. You may not be ready for that step, but you can certainly create committees/working groups that distribute the tasks and the decisions to the greatest number of people.

Keeping it Simple

As software developers many of us are familiar with the acronym of K.I.S.S., "Keep it Simple Stupid" or "Keep it Stupid Simple". We know what that means for our code, but what does that mean for our projects themselves?

There are three fundamental questions you should be asking regularly of your community:

What do people need to know to be involved and be successful?
What do people need to do to get involved successfully?
Why should people care?

These three questions require that you do your homework. The keeping of good notes, tracking activities and engagement, and understanding the overall health of your community is integral to its success. Tools like Orbit empower you to do that.

Each of those three questions necessitates clarity and proper process. To help someone move from a casual observer of your community to a participant, you must know the pathways they can traverse. For an open source software project that could be a process like:

Consumer of the project -> Raise an issue -> Asked to code review proposed solution -> Join Discord server -> Invited to a working group

What your pathways will look like are highly dependent on the unique circumstances of your community. Every single community, though, has them. However, not every single community is aware of what they are. If you are not aware you can't move people through them, and you can't track their success in engagement.

Adaptability

Starfish left blood behind and embraced seawater because of its abundance as part of the evolutionary process.

The currents around us are always changing. It is often said that there is no treading water. You are either swimming or you are sinking. The difference is your ability to adapt to the ever changing circumstances of your environment.

Case in point: When is the last time you visited a Blockbuster Video?

The lifecycle of open source software projects often follow a certain trajectory.

First, there is a small group of people or even a single builder who invests a tremendous amount of time and effort into it.

At some point, it catches the interest of a larger group of people, and builds an organic community of users and developers. Then, either it joins the list of incredibly popular projects and becomes a global developer phenomenon or it stays for a while at that stage of modest growth.

Lastly, as it happens in every other sector in society, so too does it happen to open source software, interest starts to wane. Indeed, in software it seems to reach this stage even more quickly than in other areas. The project is still vital to a lot of people, but it is no longer trending. We can all think of tooling that fits this category.

What an open source project needs at each of these stages is going to be different. The resources available to it will also be dramatically different at each stage. The project that knows its internal and external resources at any given time, and can pivot based on that information, is one with great potential for longevity.

Everyone Contributes

If you want user contributions, build platforms that are familiar and easy. Lower the barriers to participation; focus on helping users to understand what you want from them
^{- Nieman Journalism Lab}

It almost can go without saying that communities that involve the maximum number of people are more likely to succeed in persevering, growing, adapting, and remaining relevant for the long term.

A culture of contribution underpins everything else. Open source projects that see the same people raising every issue, opening every new pull request, suggesting every new feature, are not indicative of a culture of contribution.

The circles of engagement should be broadening not remaining static.

From the ground floor level, deep in the weeds, it can be hard to know if your project's circles are growing. You often need to take a balcony perspective. This is where tracking and analyzing all activities and members becomes vital. You can do so with elaborate spreadsheets, or you can use automated tooling to make that possible and save you some headache.

Starfish in their quiet, still and contemplative ways can end up teaching us quite a lot on organizing our open source communities. What we have uncovered is only the beginning.

The Starfish and the Spider: The Unstoppable Power of Leaderless Organizations, contains a lot more valuable insights that are applicable to our communities.

If you are interested in these sort of conversations and discovering ways to continue to grow healthy open source communities consider joining us on June 30th for a fireside virtual chat with Brian Douglas, an open source community leader, mentor and developer advocate at GitHub.

How to Add DEV Comments to Your Orbit Workspace With Ruby

Ben Greenberg — Tue, 27 Apr 2021 07:11:16 +0000

The DEV community has become one of the fastest-growing developer blogging platforms. Whether you are posting primarily on the DEV blog or cross-posting your content there from your primary content source, keeping on top of the comments left by users is critical. Few things can be more frustrating to someone trying to engage than receiving no response.

In this step-by-step tutorial, we are going to use both the DEV API and the Orbit API to retrieve blog post comments and add them as a custom activity into Orbit.

tl;dr If you wish to skip the tutorial, the entire code for this project as a Ruby gem that can be installed in your project can be found on GitHub.

Prerequisites

You will need the following to complete the steps in this tutorial:

Ruby 2.7 or greater installed locally.
An Orbit account. If you don’t have one already, you can sign up today and start building with the Orbit API. Once you have an account, you can find your API Token in your Account Settings.
A DEV Community account. Once you have your DEV account, you can generate an API Key in your Account Settings.

Connecting to the DEV API

There are two separate API endpoints we need to access on the DEV API in order to get our blog posts comments. Namely, we need to retrieve a list of our articles, and then, we need to retrieve the comments for each article.

Get List of Published Articles

The first operation, GET Published Articles, accepts several query parameters. We will be using the username parameter. The username parameter allows us to narrow our article search for a specific user's articles.

The following is the HTTP request for our DEV articles:

url = URI("https://dev.to/api/articles?username=#{@username}")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)

response = https.request(request)

articles = JSON.parse(response.body)

In your code, replace #{@username} with the username of the DEV user you are searching for.

We are now ready to use the articles list to retrieve the comments for each article.

Get Comments for Each Article

Once we have our list of articles from DEV, we can go ahead and access the next DEV API endpoint of GET Comments by Article ID. This endpoint requires the article ID as a query parameter.

We will build an iterator in our code to loop through the list of articles and request the comments for each one:

comments = articles.each do |article|
  get_article_comments(article["id"])
end

def get_article_comments(id)
  url = URI("https://dev.to/api/comments?a_id=#{id}")
  https = Net::HTTP.new(url.host, url.port)
  https.use_ssl = true

  request = Net::HTTP::Get.new(url)

  response = https.request(request)

  comments = JSON.parse(response.body)

  return if comments.nil? || comments.empty?

  filter_comments(comments)
end

First, we iterate through each article in articles invoking a method called #get_article_comments passing in the article's ID as the method's parameter.

Next, we create the #get_article_comments method. The method makes an HTTP request to the DEV API endpoint. At the end of the method, we execute another method that we have not yet created called #filter_comments. Inside this next method, we can add any sort of datetime filtering we want to the data as a way to limit the scope if we are working with a lot of DEV blog post comments. In the following example, I restrict the data set to anything less than or equal to one day ago:

def filter_comments(comments)
  comments.select do |comment|
    comment["created_at"] <= 1.day.ago
  end
end

Note: The 1.day.ago functionality in the code snippet above comes from ActiveSupport. To take advantage of it you need to add require "active_support/time" at the top of your Ruby script.

We now have all of the comments that we want to add as custom activities to our Orbit workspace! Let's go ahead and start doing that.

Working with the Orbit API

The Orbit API lets you perform a wide range of activities in your Orbit workspace programmatically. The API reference guide is a good starting point for exploration. For our purposes, we will be using the create a new activity for existing or new member API operation.

API access is included with every account! Try it out by signing up today.

Creating a New Custom Activity

The Orbit documentation informs us that when we send a new activity to Orbit through the API, it will also either retrieve an existing member in our workspace or create a new member if an existing one cannot be found. This means we only need to send one HTTP request to Orbit to both create the blog post comment as an activity and attach it to a member!

According to the API reference we need to define an activity_type and a title for the activity, along with member identity information. We will also send more descriptive information to further supplement the record in the workspace, such as a description and a link.

Constructing the Custom Activity Data Object

Let's first construct the request body that we will send in the HTTP request. We will create two methods first, #sanitize_commentand #construct_commenter. They both will clean the data we received from the DEV API and put it in the proper format for Orbit.

The #sanitize_comment method removes all the HTML tags from the comments to leave us with just the body of the message.

The #construct_commenter method forms a hash representing the identifying information of the commenter. If the DEV commenter has a Twitter or GitHub username in their DEV profile we add it to the information we send to Orbit.

  def sanitize_comment(comment)
    comment = ActionView::Base.full_sanitizer.sanitize(comment)

    comment.gsub("\n", " ")
  end

  def construct_commenter(commenter)
    hash = {
      'name': commenter[:name],
      'username': commenter[:username]
    }

    unless commenter[:twitter_username].nil? || commenter[:twitter_username] == ""
      hash.merge!('twitter': commenter[:twitter_username])
    end

    unless commenter[:github_username].nil? || commenter[:github_username] == ""
      hash.merge!('github': commenter[:github_username])
    end

    hash
  end

  def construct_body
    @commenter = construct_commenter(@commenter)

    hash = {
      activity: {
        activity_type: "dev:comment",
        key: "dev-comment-#{@comment[:id]}",
        title: "Commented on the DEV blog post: #{@article_title}",
        description: sanitize_comment(@comment[:body_html]),
        occurred_at: @article[:created_at],
        link: @article[:url],
        member: {
          name: @commenter[:name],
          devto: @commenter[:username]
        }
      },
      identity: {
        source: "devto",
        username: @commenter[:username]
      }
    }

    hash[:activity][:member].merge!(twitter: @commenter[:twitter]) if @commenter[:twitter]

    hash[:activity][:member].merge!(github: @commenter[:github]) if @commenter[:github]

    hash
  end

In the #construct_body method we create a hash with all the data we plan to send to Orbit.

The activity_type is dev:comment
A custom ID in the key field interpolating the string dev-comment with the DEV comment ID
The title of Commented on the DEV blog post interpolated with the blog post title
The comment itself in the description field stripped of all of its HTML tags
The URL to the DEV blog post in the link field
The member and identity objects with the user's name and DEV username
If the commenter has a Twitter or GitHub username in their profile those are added to the HTTP request body as well in the member object

Posting the Activity to Orbit

We are now ready to make the POST request to Orbit with our data. This will be a standard Ruby HTTP request using the net/http library:

url = URI("https://app.orbit.love/api/v1/#{@workspace_id}/activities")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
req = Net::HTTP::Post.new(url)
req["Accept"] = "application/json"
req["Content-Type"] = "application/json"
req["Authorization"] = "Bearer #{@api_key}"

req.body = construct_body

req.body = req.body.to_json

response = http.request(req)

JSON.parse(response.body)

Once the activity has been sent to the Orbit API, you should see it soon after in your workspace!

Using the Ruby Gem

The code in this tutorial comes from a fully-featured Ruby gem that abstracts a lot of the work for you. It also includes a command-line interface (CLI) to make execution even more straightforward.

The code for the gem can be found on GitHub. To install the gem in your project add it to your Gemfile:

gem 'dev_orbit'

Then, run bundle install from the command line. Once the gem has been included into your project, you can instantiate a client by passing in your relevant DEV and Orbit API credentials:

client = DevOrbit::Client.new(
  orbit_api_key: '...',
  orbit_workspace: '...',
  dev_api_key: '...',
  dev_username: '...'
)

To fetch all new comments on your DEV blog posts within the past day, you can invoke the #comments instance method on your client:

client.comments

This method will gather all the comments in the past day from DEV, format them for activities in your Orbit workspace, and make the POST request to the Orbit API to add them.

Automating with GitHub Actions

What if you would like to run this gem once a day to fetch all your latest DEV comments and add them to your Orbit workspace? You could manually run it daily, or you can use GitHub Actions to automate it for you!

GitHub Actions is an environment to run all your software workflows provided by GitHub for free for any public repository. You can use it to run your code's testing suite, to deploy to the cloud or any one of numerous use cases. In our example, we will use GitHub Actions to run this gem once a day on a cron schedule.

Inside your GitHub repository create a folder called .github, and another one called workflows inside the first one. Within the workflows folder create a YAML file called dev_comments.yml. Add the following YAML text into the file:

name: Check For New DEV Blog Post Comments and Add to Orbit Workspace
on:
  schedule:
    - cron: "0 0 */1 * *"
  workflow_dispatch:
    branches:
      - main
jobs:
  comments-workflow:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with:
        fetch-depth: 0
        submodules: recursive
    - name: Set up Ruby 2.7.2
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: 2.7.2
    - name: Ruby gem cache
      uses: actions/cache@v1
      with:
        path: vendor/bundle
        key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
        restore-keys: |
          ${{ runner.os }}-gems-
    - name: Bundle Install
      run: |
        gem update --system 3.1.4 -N
        gem install --no-document bundler
        bundle config path vendor/bundle
        bundle install --jobs 4 --retry 3
    - name: Check for New Comments
      run: |
        bundle exec dev_orbit --check-comments
      env:
        DEV_API_KEY: ${{ secrets.DEV_API_KEY }}
        DEV_USERNAME: ${{ secrets.DEV_USERNAME }}
        ORBIT_API_KEY: ${{ secrets.ORBIT_API_KEY }}
        ORBIT_WORKSPACE_ID: ${{ secrets.ORBIT_WORKSPACE_ID }}

This YAML workflow assumes that you have uploaded your Gemfile with the dev_orbit gem listed inside of it.

The above workflow creates a Ruby developer environment inside your GitHub Actions instance. It then installs the dependencies listed in your Gemfile, and finally, uses the gem's CLI to check for new blog post comments and add them to your Orbit workspace.

The only other task you need to do in order for this automation to work is to add your credentials for DEV and Orbit into your GitHub repository's secrets settings. You can find your secrets by navigating to "Settings" from within your repository and clicking on "Secrets" in the side navigation bar.

Once your secrets have been added, this workflow will automatically run once a day for you! You can simply go to your Orbit workspace and find the latest DEV blog comments in your member activities without needing to do anything else.

Want to learn more about using the Orbit API? Check out these other resources:

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.

My Surprising Journey To Working At Orbit

Ben Greenberg — Mon, 19 Apr 2021 06:46:06 +0000

I was not looking for a new job, but somehow I ended up with one anyway.

My journey to Orbit as a developer advocate was a bit off the beaten path. I did not apply through a job listing or initially reach out about an open role. Rather, my path to Orbit was manifest through developer and user experience.

As a member of the developer relations team at a communications API company, we constantly pursued more and better ways to understand and grow our community. We knew that real sustained community did not happen through short-term transactional experiences but by creating long-term value for the users of our product and services.

Orbit offered something unique

It was not long before Orbit became visible on our radar. It promised not only a useful platform to deepen understanding of the community. It put forth an entirely new conceptualization of community-building. In fact, the platform -- the product -- only came after the ideation and thoughtful work of crafting the Orbit Model. Deliberate systematized methodologies don't usually take precedence in emerging start-ups. This was something different.

The majority of my work was concerned with developer experience, developer tooling, and the developer platform. As such, I was often brought into conversations on how we could incorporate the questions, concerns, and overall feedback of developers into the larger view of our community's health. In that framing, I began working on connecting the feedback users left on the developer documentation and developer portal into the company's Orbit workspace.

The thoroughness of the docs immediately struck me as I began my work project. In my experience, docs are often an after-thought for fast-growing companies. Yet, as I started building the new API service for the developer platform, I had everything I needed in front of me. The docs were thorough with customizable code snippets, an exportable Swagger definition I could use in Postman, and more.

I knew right away I was interacting with a company that took developer experience seriously. You could say I was intrigued!

Then, something really unusual happened

I reached out to one of the co-founders to ask some follow-up questions on the Orbit Model, and he responded. How many times have I sent feedback or questions to a company and never received a response? I have lost count. Not only did Josh, the CTO and co-founder, write back to me promptly, he even sent me a link to schedule a video chat. At that point, I was genuinely blown away.

It was after the conversation with Josh that I seriously began to think about working at Orbit. Up to that point, I was still in the developer's mindset building an integration with the product and looking to offer feedback. However, I was ready to see if my career goals could align with Orbit.

I reached out again to Josh, this time expressing interest in discussing a possible future at the company. He set me up with a conversation with Patrick, the CEO and other co-founder. Patrick was equally thoughtful, impassioned, and driven about both what the Orbit Model offered to community builders and the product's potential to help those builders grow and understand their communities tremendously.

A short while after those conversations, I signed my offer letter with Orbit!

What attracted me to Orbit is, I believe, intrinsically tied to the DNA of the company. A place that lives and breathes feedback. A place where a co-founder will respond to an unknown developer sending them a message asking to talk about the product. A place where every team member, regardless of function, is deeply tuned in to the overall user experience.

User experience is at the center of it all

Developer Relations, as a field, and developer advocates as practitioners in that field, are consumed with a drive to bring the user's experience into product development. We understand that users, and in our case, developers specifically, are at the center of everything. To do that work in a company that has elevated that idea to the level of company truth is a true joy.

A conversation that starts with product feedback can end up in unexpected places. You may even walk away with a brand new job.

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

How to Add Docs Feedback to Your Orbit Workspace With Ruby On Rails

Ben Greenberg — Mon, 12 Apr 2021 10:33:46 +0000

Developer engagement can come from many places. It can be a discussion on Slack, a question raised on Twitter, or an issue opened in a GitHub repository. Each of those represents active participation by a person in a community. Yet, while Twitter, Discord, Slack, and other mediums take prime focus, what often gets overlooked is documentation.

Studies have shown that documentation is the preferred medium for developers seeking answers as they build. Often, the key difference between a positive product experience and a negative one is the state and accuracy of the docs. A clear and ongoing relationship with the developers who use them can significantly improve the feedback loop helping to ensure a more consistently positive experience.

The documentation of an API, product, or service is one of the pivotal meeting places between the people that orbit the community and the product that the community gravitates around. Capturing that engagement is crucial to gaining a more full understanding of a community. Orbit provides a platform and an open API to enable and grow the work of developer engagement.

Creating with the Orbit API

Using the Orbit API, we are going to build a Ruby on Rails service that will automatically connect new documentation feedback to an Orbit workspace. The code is in production and is being used by the team at Vonage as part of their open-source developer portal platform.

(tl;dr You can find the full code for this Rails service on GitHub.)

API access is included with every account! Try it out by signing up today.

Building the Feedback Notifier Service

Creating the Class

The first thing we are going to do is create a new class in our Rails services folder called OrbitFeedbackNotifier:

class OrbitFeedbackNotifier
end

This class will be responsible for gathering the data from our documentation's feedback system, and creating a POST request to the Orbit API with it. The Vonage developer platform utilizes custom-built feedback tooling. However, regardless of the specific feedback tooling you use, you only need to expose the data collected to our new service for it to work.

We will use the #initialize method in the class definition with the feedback data from our feedback collection tooling:

class OrbitFeedbackNotifier
  def initialize(feedback)
    @feedback = feedback
  end
end

There are several different design options we can use in structuring our service. In this case, we will build a #call class method that will do the work of instantiating an instance of our class and creating the HTTP request. This allows us to skip the work of instantiation in the actual implementation of our new service:

class OrbitFeedbackNotifier
  def self.call(feedback)
    new(feedback).post!
  end

  def initialize(feedback)
    @feedback = feedback
  end
end

The new class #callmethod creates an instance of the OrbitFeedbackNotifier with the feedback data we passed into it and then invokes a #post instance method, which we will be building shortly. Before we can build that method though we need to structure our data to create a new activity in our Orbit workspace using the Orbit API. Let's do that next!

Constructing the Data

When we look at the Orbit API documentation, we see that we need to know our workspace ID. We can find that in the URL of our Orbit workspace, it's the end of the website address. For example, the URL might be: https://app.orbit.love/example, and then your workspace ID would be example.

The API endpoint gives us a lot of ability to customize the kind of activity and data we want to associate with it. We are going to create a params object that will contain our data and we'll send that in our API request.

First, let's define the activity. then we'll define the member data after.

def params
  @params ||= {
    activity: {
      activity_type: "docs:feedback",
      key: "docs-feedback-#{@feedback.id},
      title: "Offered feedback on the docs",
      description: @feedback.feedback_body,
      occurred_at: @feedback.created_at || Time.zone.now.iso8601
    }
  }
end

Before we go forward, we'll take a moment to break down the different fields in the code snippet above:

activity_type: This is the reference for the custom activity you are introducing to your Orbit workspace.
key: A unique ID for this specific activity. If you do not supply one, Orbit will generate one for you. In the example above, I mock using the data from the feedback.
title: The title for the custom activity
description: This is the descriptive body of the activity. You can put anything in here, or nothing at all. In the example, I mock a parameter of the actual feedback contents.
occurred_at: The date and time when the activity happened. If you do not provide a value, the API defaults to the time when it received the HTTP request.

Now, we'll construct our member identity data:

def params
  @params ||= {
    activity: {
      activity_type: "docs:feedback",
      key: "docs-feedback-#{@feedback.id},
      title: "Offered feedback on the docs",
      description: @feedback.feedback_body],
      occurred_at: @feedback.created_at || Time.zone.now.iso8601
    },
    identity: {
      source: "email",
      source_host: @feedback.base_url,
      email: @feedback.email
    }
  }
end

Similar to the activity, we can provide a good amount of customization on the member identity. In our case, we are using the following fields:

source: Where the member data is coming from, Orbit recognizes some predefined options (github, twitter, discourse, email, linkedin, devto), and also any custom value.
source_host: The URL from where the member data is coming from.
email: The email of the member, which is used here as the identifier. You can also replace this with username or uid for a user ID, if either of those are more appropriate for your context.

There are other possible fields you can supply for your activity and identity constructs. I recommend checking out the API reference guide for a description of each of them. The API reference guide lets you also supply some sample data inline with the guide and get a fully formed code snippet you can copy and paste into your code.

Preparing to Make the HTTP Request

One last step before we create the #post! method, which will connect to the Orbit API and pass the data to our workspace. We need to create a small method to create a URI for the request, we'll call this #uri:

def uri
  @uri ||= URI("https://app.orbit.love/api/v1/#{ENV['ORBIT_WORKSPACE_ID']}/activities")
end

Now we're ready to put it all together in our #post! method:

  def post!
    return unless ENV['ORBIT_WORKSPACE_ID']

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true
    req = Net::HTTP::Post.new(uri)
    req['Accept'] = 'application/json'
    req['Content-Type'] = 'application/json'
    req['Authorization'] = "Bearer #{ENV['ORBIT_API_KEY']}"

    req.body = params

    req.body = req.body.to_json

    http.request(req)
  end

That's it! You now have a fully working Rails service to introduce feedback on your docs as an integral component of the understanding of your community through Orbit. How you use it in your codebase will depend on the architecture of your feedback implementation. You might want to invoke it when a new feedback item is posted to your database, for example.

Feedback, perhaps especially the negative or constructive kind, is an invaluable act of community expression. It demonstrates engagement on behalf of a person with your API, product, or service, and adding that data to your Orbit workspace will only enhance your overall picture of your community.

Further Exploration

Do you want to explore further the things you can do with the Orbit API? Check out the following resources:

From Cybercafe to Rocketship: My First Month at Orbit

Ulrich Sossou — Mon, 01 Mar 2021 09:37:43 +0000

My journey at Orbit started with this funny tweet by Josh.

Josh Dzielak

@dzello

Slack is down. That means you can't work. If you can't work, it means you need a new job. Orbit is hiring people who want new jobs, people just like you. Please see our careers page, since you can't be on Slack right now anyway. Thank you.

orbit.love/careers

15:55 PM - 04 Jan 2021

I wasn't looking for a new job but his tweet caught my attention.

The mission of Orbit, right there on the careers page, made me curious to learn more about the company. Building thriving communities and developer tools was very much aligned with my past career path and current interests. That ultimately led me to join the team.

My background

I started my career as a self-taught software developer who didn’t own a computer. I worked from a cybercafé in a small African country with a very bad internet connexion. I quickly gained plenty of technical experience and contributed to products used by millions of people across the world. I even wrote a technical book and had a small startup exit! I attribute a large part of that growth to being involved in gaming and developer communities where I made friends, met mentors, and found clients.

After about ten years of basically 100% online life, I spent the past five building up the tech community in my country of origin, Benin, by serving as vice-president and CTO of the leading tech innovation hub, and co-founding a small product studio over there. It was awesome contributing to projects with real-world impact on tens of thousands of people. Over time, my involvement decreased as we were able to build a talented team that could continue moving the mission forward.

So, when COVID hit, I knew the next step of my professional career was due, and it was about the online-first life again. I spent the best part of 2020 helping Irawo, a community of more than 50.000 talents and creators in francophone Africa, launch new programs and develop a sustainable business model.

Meeting Orbit

When I saw Orbit's homepage and model, something clicked. The Orbit Model was in line with my own experience of contributing and growing communities. I’d also long dreamed of building a CRM-like solution that’s centered around each customer’s experience as an individual. I think the Orbit Model captures the multi-dimensional aspect of how people interact in a community, or with organizations, products or services. It’s a refreshing break from the linear view of traditional sales and marketing funnels.

Needless to say, I was drawn to Orbit and decided to email the founders right away. I wasn’t looking for a full-time job, but they were looking for part-time consultants to help with integrations and other stuff.

Josh, the co-founder and CTO, replied a couple of days later, and, about a week after my email, we were on a call. The call was awesome! That’s when I knew I wanted to join the team instead of just contributing some integrations. Talking with Josh sold me on the vision. It also helped that the team was great at execution. They had made enormous progress in terms of traction and product development. And they were backed by some of the top VCs in Silicon Valley.

The opportunity to join this rocket ship about to take off was amazing. For me, this is the ideal time to join a startup in its growth trajectory, and I am very confident that Orbit is going to grow even faster and be successful. It was the best learning opportunity I could have at this step of my career.

The Interviews

After the call with Josh, he introduced me to Nicolas, who is a software engineer and the first non-founder team member. We scheduled a technical interview for the next day. It was not your typical algorithmic coding interview. It was a pair programming session where we worked together on actual production code to implement a new fun feature in the product. We had a great time together! Nicolas was happy to have another French-speaking programmer in the team so we spoke French. I learned a lot about the team culture, how technical decisions are made, etc. I could get a taste of what it would be like to work together.

After the interview with Nicolas, I went into my last interview with Patrick, 100% convinced Orbit was the next step in my journey. Patrick is the other co-founder and CEO of Orbit. He's a very high-energy guy. We talked about the company vision and the plans for the next months. I could feel his enthusiasm and how he was dedicated to reaching the goals. After our chat, he told me right away that I would receive an offer in the next few days. The offer came a couple of days later and, after a short negotiation, I signed it. It took less than a week from the first call to signing the offer, and I was starting the next Monday!

Orbit 💜

@orbitmodel

It's been a busy few weeks onboarding new crew members. If you haven’t met them already, here are the friendly new faces you’ll see around the Orbit community.

Please help us welcome @alexlsaltt, @sorich87, and @chance 🚀

17:01 PM - 02 Feb 2021

The First Days

Onboarding remote employees can be difficult but, for a young company, Orbit onboarding is pretty solid. A few days before I started, Josh had shared access to all the communication and collaboration tools: Miro, Slack, GitHub, Airtable, Trello, and more. I went through basically everything and learned so much about the company, what product and strategic decisions were made in the past, why they had been made, most major events, the company values, the processes, and many more key points.

Being an early riser, I was even able to submit a small pull request before anyone in the Paris or San Francisco timezone was up on the first day! I got a handful of pull requests merged in my first week overall. This is how fast a team member can onboard when there are great asynchronous communication processes in place. It was like someone had onboarded me on the basics before actually talking with anyone in person. The calls with team members on the next few days were mostly around getting to know each other and getting help on my tasks.

The Hard Parts

The technical aspects of my new role are going very smoothly, and I haven’t had any difficulties with them so far. The hard parts were mostly around some emotional aspects of stepping into new shoes. Working with Orbit is my first full-time role not being in a founder or executive position, so it came with its challenges. Around the middle of the month, I was hit by a bunch of insecurities and, for 2-3 days, I wasn’t as productive as I would have loved. Would I be able to adjust to a different culture? Would I be able to perform at my full potential? Would my integration into the team go smoothly? Would I be given the kind of responsibilities I’m looking for?

I think it’s normal to have such interrogations when joining a new role. They would differ from one person to another, but they are frequently addressed with good communication with other team members, and some amount of self-reflection. The team has been handling the communication aspect very well so far. I have 1:1s with Josh every two weeks where I’m able to openly discuss all I have in mind. It also helped that Josh, Nicolas, and I were able to meet in person once for lunch.

Conclusion

Overall, my first month at Orbit has been an awesome experience. The team is made of caring and driven people with great product and business chops. I learned a lot in just a few weeks and I look forward to learning, growing and contributing more over the next months.

We're looking for more awesome people to join the Orbit team! See our open positions.

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!

Developer Love #1: Unintentional Gatekeeping with Brian Douglas of GitHub

Patrick Woods — Thu, 23 Jul 2020 19:20:32 +0000

In this inaugural episode of Developer Love, host Patrick Woods speaks with Brian Douglas of GitHub.

They discuss the developer advocate role, leveraging open source knowledge, and improving inclusivity within communities.

🎧 Listen now

In this episode

Brian DouglasFollow

Brian founded OpenSauced, a platform for turning open source into opportunity. Try it out and let me know what you think.

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:

Nicolas Goutay

@phacks

Our team at @OrbitModel is polishing a huge release we’re very proud of, jam-packed with new features and improvements.

As part of this effort, we set on building a new website, from scratch. A perfect opportunity to hone my #JAMstack skills and try out new tech!

🧵👇

18:46 PM - 23 Jun 2020

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).

Slack vs Discord vs Discourse: The best tool for your community

Patrick Woods — Tue, 26 May 2020 15:40:11 +0000

“What platform should I use for my startup’s community? Should I move from Slack to Discourse? Wait...there’s a Discourse and a Discord?”

Now is a great time to build a community online, and there’s no shortage of really great tools to help.

But despite the many options, there’s no single tool to rule them all. There are just too many variables, including community size, engagement model, the size and capabilities of the team building the community, and more.

While there’s no silver bullet for building and growing a community online, there are a few key questions to consider that will help guide your tooling decisions and your Developer Relations strategy.

In this article, we’ll discuss the key factors to consider when choosing a community platform, compare the three most popular options, and make recommendations based on a few different community scenarios.

Jump to these sections:

The TL;DR recommendations
The 3 key factors to consider when choosing
In-depth feature comparison grid
Detailed recommendations

The TL;DR Recommendations

We’ll discuss plenty of details, but here are the high-level recommendations.

Use Slack if…

You want to take advantage of Slack’s large library of integrations, bots (limited to 10 on free plans), or use their no-code workflow builder (only paid plans).
You want threaded conversations in your realtime chat.
You don’t care that only the last 10,000 messages are retained (on free plans).
You and your community members already use Slack for work.

But keep in mind:

On the free plan, Slack only retains the most recent 10,000 messages, which means they automatically archive messages above that threshold.
Slack paid plans start at $8 per user per month. Every community we’re aware of uses the free plan. Compare Slack pricing plans here.
Slack offers no real tooling for moderation. It’s specifically designed for workplaces, and they don’t appear interested in building features for moderation.

Use Discord if…

You need realtime chat with advanced permissions and moderation.
You need unlimited message history.
Making users sign up for yet-another-Slack group is a concern.
Integrations and bots are less important.
Your community won’t mind the casual gamer-centric aesthetic.

But keep in mind…

With Discord, community members use a single account to login to multiple communities. This user model means you can join new communities with a single click (versus creating a new user account for every community). But it means it’s impossible to use different avatars for different communities, which could be a concern for folks who have used Discord primarily for gaming in the past. It’s possible that some might not want to use their stormtrooper headshot in a professional setting.
Discord’s design and copy is playful and gamer-centric, which could be confusing for community members who aren't familiar with Discord’s gaming roots.

Use Discourse if…

Many community members will likely have similar questions or issues, and you’d like to point them to a library of common answers
You’d like community-generated content to be indexed (and thus findable in search engine results). This helps new members discover the community while reducing the core team’s support burden.
Moderation and fine-grained permissions are important.
You have enough community members for chat to be counterproductive.
Synchronous communication isn’t important, for example, if your community is distributed across many time zones.
You don’t mind paying to host the forum software, or are capable of hosting it yourself
You want to use an open source platform.

But keep in mind…

There are many technical options for starting a community on Discourse, including deploying the open source code on your own servers, paying a third party for hosting, or paying Discourse.org for a fully hosted solution.
For new members, starting a new thread in a forum can be perceived as a higher barrier of entry, versus simply saying “hello” in a chat channel.

Use both chat (Discord or Slack) + Discourse if…

You want indexed content (Discourse) along with realtime vibes (chat).
Have the bandwidth to manage multiple platforms.
Want separate spaces for distinct groups, for example a chat for your champions and a forum for everyone else.
Note: Discourse offers a plugin for integrating with chat platforms.

Three key factors to consider when choosing a community platform

When picking a platform, you’ll likely weigh some factors more heavily than others based on your situation. The factors here will provide you with a framework for assessing the options.

The size of your community

Starting from scratch (or close to it)

In the early stages of a community’s life, it’s important for the organizers to build strong connections with the first handful of members, since early adopters are more likely to join discussions, answer questions, and contribute in ways that make the community seem active and vibrant. Chat is good for this. Scalability and governance are less of a concern at this stage.

Hundreds of community members

At this point, chat platforms can start to feel unmanageable for a few reasons. First, moderation becomes an issue, since it’s hard for a small group of community managers to keep up with the volume of conversations happening (Discord beats Slack on this point).

Second, most community members complain that, on chat platforms, they often answer the same question or address the same concern many times over. The conversations just disappear too quickly for others to easily find, and since they’re not indexed or perma-linked, it’s difficult to reference previously answered questions.

Many thousands of community members

For large, well-established communities, forums are often the right choice, since live chat is difficult to manage and large scales.

Discourse provides fine-grained permissions and moderation that large communities will appreciate. Additionally, since large communities create lots of content, they especially benefit from indexed and shareable content.

One caveat for large communities: big communities are often staffed by large teams, which means they may have the bandwidth to manage more than one platform, such as a forum _and _a chat tool.

The size of your team

Your choice of community platform should take into account your team’s ability to manage multiple channels, their timezone availability, and the number of folks available to interact on your chosen platform—all of which are a function of the team’s size.

Small teams

Small teams tend to start with a single platform, since that’s what they can manage given their bandwidth. In general, teams of three or smaller should commit to a single platform to focus their time and keep overhead low.

Medium teams

These teams are more self-sufficient compared to small teams and won’t need to depend as much on other teams for support. They may be able to handle multiple platforms, but often choose to go deeper with a single platform, such as more clearly defining roles and responsibilities within the team, and designating team members to focus on specific parts of the platform.

Large teams

Larger teams can handle multiple platforms and different sub-communities, such as a Slack for your MVPs and a Discourse forum for everyone else—but doing so introduces substantial overhead in terms of process management, identity resolution, and governance. That said, larger teams inside bigger companies tend to be better equipped to plan for and manage these situations.

Your community’s engagement model

What are the behaviors and norms you want your community members to model? Are you hoping for a casual vibe where members can congregate, discuss, and debate? Or are you more interested in cultivating deep knowledge sharing and collaboration? Once you decide, you should factor your engagement model into your tool choice.

In People Powered, Jono Bacon outlines three engagement models that we think are useful to consider when choosing a platform:

Consumers

These communities revolve around ephemeral and emergent discussions about common interests, and emphasize connection based on those topics. Examples include communities about art, gaming, or general technology trends.

Champions

In this engagement model, community members share knowledge and insights about a common tool or technology, with an emphasis on leveling-up one’s expertise and experience. Members often teach each other through demos and examples, driving further participation from other community members.

Examples include company-specific communities, like the Roam Research Slack group, where members share custom CSS and browser extensions as well as how-to videos to share their knowledge and help others excel.

Collaborators

In communities of collaborators, members work together on shared projects. The primary example is open source software, where diverse people from around the world work together to build and improve a common codebase.

Comparing Slack, Discord, and Discourse

In addition to the key factors above, it’s important to understand the actual feature set each platform offers. The grid below assumes features for the baseline plans for each platform, and includes call-outs when features are offered only on paid tiers.

›› View the full image
›› Download the PDF

Detailed Recommendations

We’ll now look at detailed recommendations based on the key factors and the pros and cons of each platform.

Of all the factors to consider, we think a community’s engagement model should have the most influence over which platform is used, so we’ve organized this section along those lines with caveats for size of community and team.

Consumer communities

Suggestion: Discord

Rationale

Casual communities should lower the barrier to involvement and focus on building close connections between users. For those reasons, we suggest using Discord. With Discord, new members can join with the click of a button (versus creating new accounts, as with Slack and Discord), which means they can get started quickly.

For servers managed by an official brand account, Discord also offers a verification program, which unlocks additional features, like custom branding and short URLs, a verification check mark, and higher quality voice service.

Tradeoffs

Discord is strong out-of-the-box, but doesn’t offer the depth of integrations and bots that you get with Slack. Additionally, content isn’t public and indexed, as with Discourse, though public content isn’t always as important for casual communities compared to the other engagement models. Finally, the gamer aesthetic can be polarizing, depending on the culture of the community members.

Champion communities

Suggestion: Slack

Rationale

Champion communities need to strike a balance between causal connection between members and deeper sharing of information, learning, and projects.

For those reasons, we suggest Slack. It’s widely adopted and understood, and enables the real-time communication crucial to building loyalty among community members. Threaded chats enable community members to follow interesting digressions without distracting the whole channel, and link unfurling makes shared content standout in the flow.

Finally, Slack offers tons of integrations that are useful for sharing work, like the GitHub and Trello integrations.

Tradeoffs

Slack will let you go fast early in the life of your community, but expect to hit a wall around 1,000 active users. At that point, you’ll likely want better moderation and permissions, and you’ll start to bump up against Slack’s 10,000 message retention limit.

From a community member standpoint, it’s annoying to create a new account for every Slack community you join, and for Slack to force you through the same onboarding, even if you’re already a member of dozens of other groups.

So why start with Slack? It takes most communities years to grow to thousands of members, if they make it there at all. That said, given Slack’s ease of startup and widespread adoption, it makes sense to take advantage of it for the speed early on, then consider a transition plan in the future once the pain points become prohibitive.

Collaboration communities

Suggestion: Discourse

Rationale

Communities focused on collaboration usually want to foster deeper participation from existing community members, lower the bar for new folks to get involved, solve problems as a group, and publicly share the solutions.

Discourse stands out in each of these areas. Since all content is public and indexed by search engines, members can reference previously answered questions and discussions, which means the core team can avoid answering the same questions repeatedly. New members can quickly learn the basics and overcome common challenges, and existing members can pose more complex questions and receive help from the broader community.

Discourse is especially powerful for large communities, which face plenty of challenges related to moderation, permissions, and governance, as well as the difficulty of delivering a great experience for all community members.

To address these challenges, Discourse provides granular permissions and moderation, which enables members of the community to progress to higher levels of access and trust.

For communities backed by medium or large teams, we also recommend implementing a live chat platform in addition to Discourse to foster a closer relationship with core team members, or as we call them, members of their Orbit One.

Tradeoffs

Self-hosted, large Discourse instances require ongoing maintenance and performance tuning, and hosted instances cost money. Managing multiple tools can become burdensome, but as long as the team has the bandwidth, these issues should be solvable.

Conclusion

More communities are moving exclusively online, and more tools for managing online communities emerge each day.

While the landscape of community platforms continues to evolve, Slack, Discord, and Discourse can reliably meet the needs of most communities.

But as much as we love debating the nuances of our tools, we can’t forget that “community" really just means “people.” David Spinks reminds us:

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

If you’d like help tracking your community’s growth and measuring its ROI—no matter which platform you choose—signup for early access to Orbit.

Have opinions? Share them in the comments 👇

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!

The Observatory #3: Hot takes and cool tools for building community remotely

Patrick Woods — Tue, 24 Mar 2020 22:54:21 +0000

As community leaders grapple with the fallout from cancelled events worldwide, tons of folks have shared in-depth guides and tutorials for ways to move events online.

Below, we've pulled together a few shorter reads—call them hot takes and cool tools—that bring a unique perspective to the conversation and hopefully inspire some creativity and energy for your own communities.

🏎️ On the move

But first, our regular round-up of comings and goings in the DevRel and Community space. Have a tip for us? Drop a note to observatory@orbit.love.

Stefan Judis joins Contentful as head of DevRel from Twilio (more).
Vishwa Mehta joins Hasura as as Community Associate (more).
Domitrius Clark joins Cloudinary as Advocate Engineer (more).

The 🔥 takes and ❄️ tools

Have you tried AuxParty? It's a super fun social listening room where you can enjoy music live-curated by others, or step up to the DJ booth yourself.

👌 Try spinning-up a room and asking community members to take turns DJing throughout the workday.

Speaking of jams, TIL how to add a little ambiance to status meetings:

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

I for one am looking forward to surprising, even delighting, our community members with unexpected background music on future calls.

The biggest question now will be how to pair Zoom background music with the perfect Zoom background image. To spruce up your space, check out this Zoom background gallery from Unsplash 🖼️

While we're at it, I'd like to give Josh a shoutout for always staying way ahead of the curve, and using Zoom backgrounds well before they were cool:

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

On a more serious note, as more events move online, though, organizers need to stay vigilant against bad actors. As we've seen, lots of folks are hosting large Zoom events without realizing these potential risks, so here's a 🧵 about how to configure Zoom for community safety:

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

Finally, everyone's trying to figure out how online events can create the impact of their offline counterparts. For many, the answer seems to be something like, "The same great content, now online!"

But David Spinks challenges community leaders to reimagine events for our new online reality:

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

I hope you've enjoyed these tips and takes. If you've come across something interesting or useful we should share, please post in the comments.

📐 Measure your community with this Orbit Model Airtable template

Measuring community ROI has always been a crucial topic among DevRel and community practitioners, but with the specter of tightening budgets on the horizon, the best teams will find ways to clearly demonstrate their impact.

That's why we made this detailed Airtable template to help communities measure their impact, communicate their value, and focus on what's working for their communities.

Read the blog post and download the template 🚀

What tips or resources have we left out?

Share your own advice for building remote community in the comments below, and please reach out to us at observatory@orbit.love if we can be helpful in any way 💜

🗞️ Previous editions

Don't miss the next edition of The Observatory 🔭

Subscribe here to get an email for each new edition.
Follow Orbit on DEV to see all of our posts.

DEV Community: Orbit

Making Our Open Source Communities More Like Starfish

Decentralization

Keeping it Simple

Adaptability

Everyone Contributes

How to Add DEV Comments to Your Orbit Workspace With Ruby

Prerequisites

Connecting to the DEV API

Get List of Published Articles

Get Comments for Each Article

Working with the Orbit API

Creating a New Custom Activity

Constructing the Custom Activity Data Object

Posting the Activity to Orbit

Using the Ruby Gem

Automating with GitHub Actions

Building a Component Library in Rails With Storybook

A Primer on View Components and Storybook

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 Button Component

Deploying Storybook Alongside Our app

Conclusion

My Surprising Journey To Working At Orbit

Orbit offered something unique

Then, something really unusual happened

User experience is at the center of it all

How to Add Docs Feedback to Your Orbit Workspace With Ruby On Rails

Creating with the Orbit API

Building the Feedback Notifier Service

Creating the Class

Constructing the Data

Preparing to Make the HTTP Request

Further Exploration

From Cybercafe to Rocketship: My First Month at Orbit

My background

Meeting Orbit

The Interviews

The First Days

The Hard Parts

Conclusion

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

Developer Love #1: Unintentional Gatekeeping with Brian Douglas of GitHub

🎧 Listen now

In this episode

Brian DouglasFollow

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

Step 1: the Sanity Studio setup

Step 2: previewing embeds in Sanity Studio

Step 3: displaying embeds in Eleventy

Displaying Twitter embeds in Eleventy

Displaying Instagram embeds in Eleventy

Conclusion, source code, and further reading

Slack vs Discord vs Discourse: The best tool for your community

The TL;DR Recommendations

Use Slack if…

Use Discord if…

Use Discourse if…

Use both chat (Discord or Slack) + Discourse if…

Three key factors to consider when choosing a community platform

The size of your community

The size of your team

Your community’s engagement model

Comparing Slack, Discord, and Discourse

Detailed Recommendations

Consumer communities

Champion communities

Collaboration communities

Conclusion

Have opinions? Share them in the comments 👇

The rocky road to implementing link prefetching in Rails

The naive approach: using InstantPage itself

Comment for #52

A prefetching solution based on Turbolinks

turbolinks "instantclick" #313

Getting closer with InstantClick, InstantPage’s predecessor

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

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