DEV Community: Matthew Foley

Collab Lab #54 Recap

Matthew Foley — Fri, 24 Mar 2023 18:04:32 +0000

OVERVIEW:

The Collab Lab is a non profit organization that helps early career developers and, in particular, people in under-represented groups in tech, gain experience they need to break into tech. To achieve that, over the course of 8 weeks a team of 4 junior developers work collaboratively on a software project, under the guidance of volunteer mentors. The goal is for them to gain hands-on experience by working in a professional setting with code reviews, pair programming sessions, weekly meetings and retro sessions.

The project is a “smart” shopping list that learns your behavior over time and prioritizes the things that you are going to need and reminds you to buy them. The developers had to work both on the functionality of the application and the appearance of it. Check out the deployed app
here and the repository here!

Key Technologies and Tools:

HTML/CSS/JavaScript
UI Library: React
Hosting & Database: Firebase
UI Styling: Bootstrap

The Team

Collabies

Mentors

Day in Life of a Collabie

The team of developers (called Collabies) met with the team of Mentors each Saturday for eight weeks, for a one hour "Weekly Sync" call on Zoom. The first order of business during the call was for the Collabies to demonstrate the previous week's work with technical details, and then switching gears to either a Retrospective or a "Learning Module". In Retrospectives, both Collabies and Mentors took time to both celebrate and reflect on their prior two weeks experiences, being sure to document next steps. Learning Modules included talks delivered by Mentors on topics like Pair Programming, Source Control (Git), Communication for Developers, and Accessibility. Lastly during these calls, the Mentors would present the following week's work, managed as issues in GitHub. The Collabies would select their GitHub issues for the week, and get started!

Between Weekly Syncs, the Collabies self-organized for pair programming sessions and technical research, and sometimes divided up work for async tasks. Collabies made a good habit of starting Draft PRs early in their process, so that the Mentors and Peers could easily collaborate with them if they got stuck, or contribute suggestions along the way. Around the middle of the week, each pair of Collabies performed code review on the other pair's PR, and following that, the Mentors made their own code reviews. Once all was approved, the Collabies would SHIP IT, ready to present in the Weekly Sync!

In the 7th and 8th weeks, the routine changed - rather than the Mentors managing the process, the Collabies took over. At this point, the functional requirements were substantially completed, and the Collabies focused on the appearance of the application. They were given a goal of the app having a professional appearance, and they managed the entire process for the final two weeks, driving the project to completion! They created their own acceptance criteria, delegated their own work, did pair programming when necessary, and leaned on each other and the Mentors when they got stuck. They practiced some Product Management skills by managing feature priorities, and they also gained some experience of working in a team with velocity, keeping tabs on each other's work and avoiding merge conflicts.

A Few Words from the Collabies

From Ashelle Cancio

My experience with The Collab Lab was fantastic. The mentors were always helpful and genuinely cared about our success. They shared their own experiences as developers, which was inspiring, and I learned a lot when pair-programming with the other participants. Through the program, I got the hang of the Agile workflow and became familiar with using a Kanban board to manage our weekly issues. While I knew basic Git commands, we encountered some merge conflicts, which was actually helpful because this forced me to learn new commands. I also realized the importance of code reviews. Overall, I am more confident in my coding abilities and feel prepared to review other developers' code in future projects. I am grateful for the experience and the knowledge gained from the mentors and fellow collabies!

From Randall Bustamante

Working with the mentors and collabies on our shopping list app was the most rewarding experience I've had with coding thus far. Bootcamp was stressful and overwhelming. Despite it being in person, I didn't quite get the support I needed. The Collab Lab set this mentorship up perfectly! The mentors guided us perfectly. They didn't solve our problems, but they empowered us to find resources and succeed thanks to our own efforts. I learned A TON of knowledge that solidified skills I felt shaky on. I met amazing humans who gave their time to help others. I will forever be grateful for this experience. Thank you, DJ Taylor, Volha Hancharova and Matthew Foley. To my fellow collabies, huge thanks to Alexandria D'Antonio, Ashelle Cancio, and Sarah Jenkins for your collaboration and leadership! And a final shout out to Alex Morton for watching over us to make sure all was good and healthy.

From Alexandria D'Antonio

Being a part of this cohort was a transformative experience. Imposter syndrome was a huge hurdle I faced starting my journey as a software engineer. However, being a part of The Collab Lab was the clicking piece for me that confirmed I belong on this path. The experiences I've gained prior as a bootcamp graduate have all been short-term projects. Working with this amazing team for the last eight weeks showed me the collaborative dynamic of being in this kind of role. I loved it. I learned and applied new technical communication skills in writing pull requests, code reviews, and giving and receiving feedback. While having a lot of fun working with Sarah, Randall, and Ashelle, I also learned a lot from the different perspectives of my fellow Collabies. Instrumental to our success was the consistent support and guidance of our mentors Volha, Matt, and DJ. Each week, we were using new technical and documenting methods thanks to the mentors' thoughtful comments and recommendations. As a Collabie, I was able to build confidence in myself week by week during this program and will forever be thankful for this opportunity!

Conclusion

To wrap things up, everyone enjoyed the experience and there were all sorts of valuable learnings. The developers worked diligently to deliver a high quality application. Any organization would be lucky to have any of these developers on their team!

If you are an early-career developer, the application for the next cohort is ongoing and this is a huge opportunity. Apply!!!

Converting to Vite (Part 4)

Matthew Foley — Mon, 14 Feb 2022 16:18:49 +0000

In Part 4 of this series, I'll be talking about some of ways the scope of PR #1322 grew to include cloud-based IDEs! As alluded to in Part 1, our conversion from Webpack to Vite all started because of a discussion about opportunities for dependency updates in our project. Between this and us greatly reducing our build script footprint, we saw in this endeavor an additional opportunity for reduced friction in getting setup for Cloud IDE support. To us, Cloud IDE support presents an arguably easier path for prospective contributors, because it allows them to skip the hard parts of preparing their local environment for development.

Based on some back-and-forth in our Discord, we decided to try out a handful of Cloud IDEs. Ultimately, this PR (and some ground-clearing ones that preceded it) introduced support for Gitpod, Replit, Stackblitz, and Glitch.

Exploring and implementing the various implementation details of these was a truly significant lift by @0vortex, and it shows in how he listed out the pros and cons of each Cloud IDE in our README.

One might argue that support for each Cloud IDE should have been its own PR, but I would point out that sometimes it's better to let the technical details agglomerate so that the ancillary benefits of a major change follow directly on the heels of the core benefits. I was personally very affirmed when a contributor was able to move forward with a contribution shortly after this PR landed!

Based on our experience at present, Stackblitz, Replit, Codesandbox, and Glitch are not reliable enough to test significant feature contributions to an application at the scale of Open Sauced. From what we see, the reliability challenges deal with the virtual filesystems in use - Open Sauced is a five year old project, and the codebase has grown. In fact, we feel that the performance benefits of Vite (especially its use of esbuild) made it possible for us to get the Cloud IDE support to the level that it is today.

Let us know in the comments if you'd to see more technical detail about our experiences with the Cloud IDEs!

Photo by İsmail Enes Ayhan on Unsplash

Converting to Vite (Part 3)

Matthew Foley — Thu, 27 Jan 2022 15:39:21 +0000

In Part 3 of this series, we'll talk about our use of various plugins for Vite on the Open Sauced project. Vite provides extensibility in the form of a Plugin API, based on that of Rollup. For reference on which Rollup plugins Vite is compatible with (and to what degree), see Vite Rollup Plugins

Once we were able to get things realigned with our dependencies and we were able to get Vite to build everything correctly for the simplest cases (production build on browsers supporting ESM), we shifted our focus to restoring tooling feature parity to what we had with Webpack (or at least the parts we cared about). Frankly these were some things that I personally wasn't intimately familiar with, so the vast majority of configuring Vite plugins was done by @0vortex. That said, the easiest way for me to talk about this is to just refer to the imports section of our vite.config.ts file.

import ViteReact from '@vitejs/plugin-react'
import ViteEslint from '@nabla/vite-plugin-eslint'
import ViteHtml from 'vite-plugin-html'
import ViteInspect from 'vite-plugin-inspect'
import ViteLegacy from '@vitejs/plugin-legacy'
import { VitePWA, VitePWAOptions } from 'vite-plugin-pwa'
import ViteReplace from '@rollup/plugin-replace'
import ViteTimeReporter from 'vite-plugin-time-reporter'
import ViteVisualizer from 'rollup-plugin-visualizer'

As you might guess, the @vitejs/plugin-react plugin is the one most directly responsible for getting Open Sauced to build in Vite, generally.

We make use of eslint in the Open Sauced project, and it had been part of the Webpack build steps. To reach feature parity on this, we made use of @nabla/vite-plugin-eslint. As mentioned on the plugin's NPM page, it "keeps HMR fast: linting is done asynchronously and doesn't block the transform process."

We make use of the ViteHtml plugin to inject our app version into the page title. Actually, this wasn't part of our original build process, but we like it now!

We make use of the ViteInspect plugin for development purposes in optimizing Vite. This plugin lets us observe the state of the various Vite plugins.

The ViteLegacy plugin is what we use to target browsers not supporting ES Modules.

The Vite PWA plugin was the one I mentioned in Part 2 - we worked a bit to to get our existing PWA implementation working, and we wound up deciding to transfer to use of this plugin instead.

Proving the use case of supporting the same effective Plugins API as Rollup, we are using @rollup/plugin-replace to inject the Netlify build date into a Footer react component.

For vanity metrics, we use vite-plugin-time-reporter in order to gloat about build times.

In yet another showcase of Rollup plugin compatibility (and this one's my favorite), we are using rollup-plugin-visualizer.

Some of the plugins are loaded unconditionally, and others are loaded based on build context (I'll talk a little more about this in Part 4). Below is a snippet from our vite.config.ts:

config.plugins.push(
  ViteTimeReporter(),
  ViteEslint(),
  ViteInspect(),
  ViteReact({
    fastRefresh: !isTest,
    // Exclude storybook stories
    exclude: /\.stories\.(t|j)sx?$/,
    // Only .jsx files
    include: "**/*.jsx",
    babel: {
      plugins: [
        [
          'babel-plugin-styled-components',
          {
            displayName: true,
            fileName: false
          }
        ]
      ]
    }
  }),
  ViteHtml({
    minify: isProd && isBuild,
    inject: {
      data: {
        title: `Open Sauced v${process.env.npm_package_version}`,
      },
    },
  })
);

And here's a snippet of some code used for conditional application:

isBuild && isLegacy && config.plugins.push(
  ViteLegacy({
    targets: [
      'defaults',
      'not IE 11'
    ]
  })
);

isReport && config.plugins.push(
  ViteVisualizer({
    filename: "./build/bundle.html",
    open: true,
    gzipSize: true
  })
);

We'd love to hear in the comments what some of your favorite plugins are for Vite (or Rollup)!

Photo by Nathan Watson on Unsplash

Converting to Vite (Part 2)

Matthew Foley — Thu, 13 Jan 2022 16:08:35 +0000

In this post, I'm going to describe some of the snags that we encountered as we transitioned to Vite - at their best, snags become lessons!

Open Sauced is a Progressive Web Application (PWA), and this includes the use of a Service Worker. In my personal understanding, a Service Worker definition should be packaged as a standalone JavaScript file. When you look at how bundling is done in Vite, it will generate a vendor.xyz.js file, an index.xyz.js file, and otherwise pass through static assets in the public directory as-is. Our webpack configuration on the other hand was configured to handle our src/service-worker.js in a specific way. For that reason, we needed to move our src/service-worker.js file to public/service-worker.js, and move around the associations in our src/index.js file. Another thing we had to learn about was the way Vite handles environment variables. Our application would look at whether the application was in production or development mode (and also whether it was being served locally) in order to decide whether to register the service worker. For a project using Webpack, you usually refer to these as process.env.VARIABLE and the value is statically set in the bundling process. Vite does something a bit different, but instead you would need to refer to import.meta.env.VARIABLE and only a handful of things are pre-set for you and otherwise you need to use a variable naming convention to have something statically included in the bundle. Fortunately, most of the variables we needed to use were included by default, so it was easy to get working (or so we thought). We tweaked and tweaked some more, and in the end, we just ended up using the vite-plugin-pwa extension to handle everything, while moving most of our PWA manifest to vite.config.ts. It's great to know how things work under the hood, but sometimes you just get better results with a plugin!

Another thing that we ran into dealt with the fact that some libraries end up just a little bit differently in development bundling than in production bundling. When developing, Vite takes advantage of ESM to let the browser effectively cache your dependencies, separated out into module files. In production, everything is bundled into one vendor file. Libraries can export different compiled versions between these two situations. We were having a lot of trouble that we isolated down to a specific component, that in turn used the react-markdown library. After reading through issues for this one and its dependencies, we found that there was a circular reference in one of react-markdown's dependencies that only showed up in production bundles.

The most straightforward fix for the circular reference was to update react-markdown through one major revision, but this introduced a new snag. In this major revision, react-markdown changed to ESM only, which would be fine for Vite, but not for our testing approach for jest (other than experimentally, so I learned. @0vortex and I got some help from @jasonericdavis on Discord to mock the react-markdown component in Jest (bypassing the need for ESM support) as part of a preparatory PR, and we got back on track.

One takeaway that I had from this was the practice of stepping beyond running vite dev, and running vite build and vite preview as well, in order to verify what would run in production. We use Netlify deploy previews in Open Sauced, and running both vite build and vite preview helps with reproducing production issues locally. We updated our package.json to reflect these CLI commands.

I would love to hear from others what kind of experience they had switching from Webpack to Vite!

Cover image Photo by william william on Unsplash. I chose this one because I felt like @0vortex and I were the tugboats!

Converting to Vite (Part 1)

Matthew Foley — Wed, 05 Jan 2022 16:41:57 +0000

This is Part 1 of a series about how recently in Open Sauced, we converted the project from using Webpack v4 to using Vite! A lot of what we'll cover in this series deals with PR #1322. @bdougieyo started this as a create-react-app project 5+ years ago and so this conversion certainly turned out to be an undertaking!

You can read in many different places about the benefits of using Vite for tooling, as well as how it works under the hood, but we can unequivocally tell you that it significantly improved on the build times for our project. My fellow contributor @0vortex spent plenty of time with this PR, and he observed going from build times with Webpack around 220 seconds, to full build times with Vite around 9 seconds (and hot module reloads measured in milliseconds at worst).

So how did we get here? Well, it's a good thing to describe alternatives considered when you add issues to a repo! Months ago, @0vortex described in Issue #1131 some opportunities for dependency updates that would require version 5 of webpack with our webpack configuration, and warned that the dependency management would probably be tricky. I fixated on an alternative that he mentioned about converting the project to use Snowpack. I had wanted to learn more about bundling tools, so I took a few days here and there after Thanksgiving and got Open Sauced mostly working with it (see PR #1320).

@bdougieyo looked over that PR on stream, and pointed out that there was a lot more momentum recently with Vite as opposed to Snowpack. He pointed out that Astro was changing from using Snowpack to Vite for bundling, and that these were the same folks responsible for Snowpack.

As it turned out, the conversion steps for getting our project working with Vite were pretty similar to those for Snowpack, so I managed to get a branch mostly working with Vite in about 25 minutes while the stream was still going. Little did I know, there was still plenty to be done!

In Part 2 of this series, I'll talk about some of the snags and learnings we had with the conversion, and in Parts 3 and 4, I'll talk about some of the ways the scope for this PR grew.

Cover Image by Anders Jildén on Unsplash

Highlighting: sync-contribution-graph

Matthew Foley — Wed, 29 Dec 2021 20:39:25 +0000

A couple of weeks ago, I nearly scrolled past this gem on my twitter feed: sync-contribution-graph, by @kefimochi. Go have a look!

You can use this tool to have your GitHub contribution graph accurately reflect contributions from other accounts you make use of. For example, outside of work I use the handle mtfoley, but I have a separate account I use for my job. I like the idea that I could use this to accurately reflect my activity level, and that no private information about that work handle is revealed.

The way it works is pretty straightforward. When you configure it with a username and a time frame (year), it performs an HTTP request to the appropriate URL, and parses the HTML in the response for the dates/counts of contributions (these correspond to those little green squares). Based on this data, it creates appropriate git shell commands. The shell commands are saved to a file that can optionally be run immediately. Here's a snippet that's the meat of it in src/index.js:

import { parse } from "node-html-parser";
import axios from "axios";
import fs from "fs";
import shell from "shelljs";


// Gathers needed git commands for bash to execute per provided contribution data.
const getCommand = (contribution) => {
  return `GIT_AUTHOR_DATE=${contribution.date}T12:00:00 GIT_COMMITER_DATE=${contribution.date}T12:00:00 git commit --allow-empty -m "Rewriting History!" > /dev/null\n`.repeat(
    contribution.count
  );
};


export default async (input) => {
  // Returns contribution graph html for a full selected year.
  const res = await axios.get(
    `https://github.com/users/${input.username}/contributions?tab=overview&from=${input.year}-12-01&to=${input.year}-12-31`
  );


  // Retrieves needed data from the html, loops over green squares with 1+ contributions,
  // and produces a multi-line string that can be run as a bash command.
  const script = parse(res.data)
    .querySelectorAll("[data-count]")
    .map((el) => {
      return {
        date: el.attributes["data-date"],
        count: parseInt(el.attributes["data-count"]),
      };
    })
    .filter((contribution) => contribution.count > 0)
    .map((contribution) => getCommand(contribution))
    .join("")
    .concat("git pull origin main\n", "git push -f origin main");


  fs.writeFile("script.sh", script, () => {
    console.log("\nFile was created successfully.");


    if (input.execute) {
      console.log("This might take a moment!\n");
      shell.exec("sh ./script.sh");
    }
  });
};

I made some suggestions in the setup workflow on the repo and submitted a PR to update the README. I hope you find this and other work by @kefimochi to be of interest!

My first contribution to prometheus

Matthew Foley — Wed, 22 Dec 2021 16:41:41 +0000

Several weeks ago I joined Virtual Coffee, and I really love that community. I shared during one of the weekly sessions that I was hoping to learn some more about backend by contributing to open source software. One of the more seasoned members suggested that I try contributing to prometheus/prometheus.

Taken from the description on the repo:

Prometheus, a Cloud Native Computing Foundation project, is a systems and service monitoring system. It collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results, and can trigger alerts when specified conditions are observed.

As I started looking at the project issues, I didn't find many good first issues that I personally felt comfortable with, so I decided to take advantage that I had a completely fresh set of eyes on the project! As I followed along with the Getting Started guide, something immediately jumped out at me! When opening http://localhost:9090/metrics and opening the Metrics Explorer, I was presented with a really long list of metrics that I could view the time series data for. I thought to myself "with such a long list, it would be nice if there was a search field!" I opened an issue about this, and then a subsequent pull request. Here's a screenshot of at least the first iteration of what I implemented:

This project uses Developer Certificate of Origin (DCO) as one of the checks it does for PR. This makes sure that all commits are signed off to include the contributors name and email address. I learned the hard way about amending commits and using git commit -s to sign off commits.

Beyond that, the reviewer GitHub user @juliusv was very friendly and engaging and asked me to implement the use of Fuzzy search with @nexucis/fuzzy, which had been used on an adjacent component. I was also able to add appropriate tests for the new component!

Since this PR, I've gotten a couple more merged to the project, including some contribution to the Go codebase, so I'm starting to dig into the backend side which is what I had wanted to do!

Cover image by Timon Wanner. Picked it on account of the story of Prometheus.

Implementing Dark Mode (Part 3)

Matthew Foley — Thu, 16 Dec 2021 15:57:20 +0000

In contributing to Open Sauced and other OSS projects as well, I've found time and time again that there are such ample opportunities to learn. However, contributing a feature and sticking with it on a longer term can cause those opportunities to multiply! In Part 3 of this series, I'm going to talk about some of the after-effects of implementing dark mode on Open Sauced in PR #1020.

It was around this time that @bdougieyo had really been wanting to flesh out the existing documentation. In the interest of keeping the project moving, the PR was merged with the caveat that we needed to make sure it was well documented so future contributors could work with it.

Seeing as this PR had a big impact on look and feel of the app, and touched so many files, it's not surprising there were 32 comments on the PR when it was all said and done. Some of those were scoping the feature, some of them were thinking critically about colors, and some of them were talking about the approach in general (i.e. code review). To have this much commentary in the PR made it really easy to document the feature! The opportunity to learn and contribute multiplied and that brings us to a follow-on documentation PR.

A more obvious case of learning opportunities multiplying is the fact that having authored the feature, you'd be pretty well suited to make little fixes to it (and there will be little fixes needed). Case in point, there was an issue filed by @0vortex where the hover style for some components still had light coloring and this made the text unreadable in dark mode. I loved reading his issue description of

Hovering over a repository in the dashboard gives a user a surprise sunburn.

Having learned some of the syntax for styled components and knowing how they were organized in the project, I was able to make a subtle but easy fix in PR #1060.

Last point I'll make here, the feature you author might reach further than you think. Looking back now, it was fairly obvious that our design system for Open Sauced (Storybook) should allow toggling dark mode. What was not obvious was how to make all that work. Storybook supports this conceptually but in a newer version than we had. I did a lot of learning as I worked on PR #1061 to get it up and running, since I didn't have a lot of experience with dependency updates in a React app.

Learning with a goal in mind is powerful, and sticking with features you contribute can supercharge your learning because the goals multiply!

Implementing Dark Mode (Part 2)

Matthew Foley — Thu, 09 Dec 2021 15:36:38 +0000

This is Part 2 of the series on Implementing Dark Mode. This was done in open-sauced/open-sauced#1020, and handily demonstrated to me the wealth of learning opportunities in contributing to Open Source. I for one have learned a ton! On this one, I got the opportunity for learning in several areas. I was still pretty new to React (and I still am), so I had not yet used the Context API. For a lot of the same reasons, I hadn't used the styled-components library before.

Throughout the rest of these points, the thing to bear in mind is that for the most part, the app being in dark mode just means that the HTML body element has a CSS class name including "dark".

One implementation detail that I feel was a win was that the only React component that had any kind of interaction with the ThemeContext was a set of buttons that toggle the theme. I like to think this helps with separation of concerns. Here's a code snippet from the buttons component:

import React, {useContext} from "react";
import ThemeContext from "../ThemeContext";
import {FlexCenter} from "../styles/Grid";
import darkMode from "../images/darkMode.svg";
import lightMode from "../images/lightMode.svg";
import themeAuto from "../images/themeAuto.svg";
function ThemeButtonGroup() {
  const [theme, setTheme] = useContext(ThemeContext);
  return (
    <FlexCenter style={{marginRight:"0.5rem"}}>
      <a
        style={{margin:"0 .5rem"}}
        disabled={theme === "dark"}
        onClick={(event) => {
          event.preventDefault();
          setTheme("dark");
        }}>
        <img
          src={darkMode} 
          alt="dark mode" 
          style={{
            backgroundColor:(theme === "dark") 
            ? "#ccc" 
            : "transparent"
          }}/>
      </a>
// ...
    </FlexCenter>
  );
}

Another implementation detail was related to coloring of images. Open Sauced makes use of many SVG images, of differing flavors. In the cases where SVG files are in the static assets of Open Sauced (e.g. <img alt="open sauced" className="svg" src={mortarBoard} />), the coloring of these is controlled using the filter CSS property. On the other hand, we also make use of @primer/octicons-react.

Here's a sample of one of these icons in component code:

import {SearchIcon} from "@primer/octicons-react";
// ...
<SearchIcon size="large" verticalAlign="middle" className="svg" />

These inject code directly into markup as <svg>...</svg>, requiring use of CSS property fill.
Finally here's the CSS code snippet where the <img> and <svg> tags are handled differently.

body.dark img.svg {
  filter: invert();
}
body.dark svg.svg {
  fill: var(--lightestGrey);
}

I referred quite a bit to this article: Color Control of SVGs.

One last fun implementation detail was working with our use of react-loading-skeleton (I love this effect, and I feel it really does work in keeping the user engaged and under the impression of the app working while data loads). To make this effect still work well in dark mode, I took the opportunity to crack open the source, and replicate a few key values as found in this snippet of our CSS.

body.dark .react-loading-skeleton {
  background-color: var(--backgroundGrey);
  background-image: linear-gradient(
    90deg,
    var(--backgroundGrey),
    var(--grey),
    var(--backgroundGrey)
  );
}

Again, working on this PR really cemented my personal belief and experience that contributing to Open Source Software can provide amazing opportunities for learning by doing!

Implementing Dark Mode (Part 1)

Matthew Foley — Tue, 16 Nov 2021 15:34:47 +0000

I'd like to share the story behind one of my favorite contributions to Open Sauced so far, which is the addition of "Dark Mode", PR #1020. This PR touched 25 files and was pretty substantial in scope, so I'm going to break this up into 3 parts. Part 1 is here is just the background - the what and the why, as @bdougieyo sometimes says. If there's one takeaway though, it's the value of opening a PR early in your process - you can share your progress and your roadblocks, and maintainers can help you get unblocked!

With that, the original idea for the dark mode feature came from @filiptronicek in Issue #607, and I decided to try to take this one on for a few reasons:

1) I'd read an article once about prefers-color-scheme, and that was my level of knowledge about dark mode.
2) I wanted to learn the ins and outs of how the project handled styles.
3) My Macbook was set for the color preference following the time of day, so based on #1, I knew I was going to test the feature with (literally) endless delight!

In this project I picked up a habit of starting talking about the PR relatively early in the cycle. So as I got started on things, I had inferred that the intention was to fall back to the system preference but that the user could override it to either or light or dark mode and have that setting persisted to local storage. The more I read articles, the more I saw a pattern that they either just simply followed the system preference, or they would start with a default and toggle back and forth. So there were some cases using a single state for user preference, and some with two states, but none with three states.

Talking with other contributors about it, @0vortex pointed out a post on the StackOverflow blog, and it talked in passing about a three-state solution. I was sold! I felt compelled to see this thing through with a three-state solution, and I'm glad I did because since then I've seen a handful of blog posts and examples in the wild, which I really like.

Stay tuned for Part 2 where I'll cover some implementation details and learnings, and Part 3 were I'll cover some of the unexpected things about this PR!

because copy & paste is tough

Matthew Foley — Tue, 09 Nov 2021 17:05:32 +0000

Following up on my post last week about the first aspect of a PR contribution to explore.opensauced.pizza, I'm going to talk about the second aspect of that PR - joyfully implemented as an HTML <select> element (I really like these).

So as I mentioned in the post before:

We also wanted to let users quickly reproduce the queries we use in Open Sauced... this way, when its time to iterate on an existing feature, there's very little friction to finding that starting point.

About a week before this, I had been working on a PR for tabulating the GraphQL API calls in the Open Sauced docs, so a lot of the details about API calls were pretty fresh.

Side note, if you want line breaks inside a table in markdown, you'll need to use a <br/> element, but don't forget to use a self closing tag in the event your markdown file is parsed and used by a tool like Docusaurus, :cough, cough:. Shout out to @0vortex for cleaning up my messes!

Anywho, after looking around at GraphiQL implementations, I came to the belief that most define a fetcher with the correct API endpoint/headers and otherwise things just work out of the box. Once the introspection query is run and the schema parsed and validated, the combination of the Explorer pane and the Query Editor pane make it really easy to build up and run valid queries. There's also a common pattern of using a default query so when the client first loads up, the query is pre-populated. What these two don't help with is reproducing and working with multiple queries.

The approach I wound up taking was to store all of the dynamic queries in an object, and then generate a <select> element in the toolbar, which updates the query contents and query name with the onchange event. Here's the piece of code that does the job...

<GraphiQL.Toolbar>
    <select
        defaultValue={""}
        onChange={(e)=>{
            const key = e.target.value;
            this.handleEditQuery(Queries[key]);
            this.handleEditOperationName(key);
        }}
    >
        <option value="">Choose a Query</option>
        {Object.keys(Queries).filter(key => key !== 'ALL').map(key => {
            const isMutation = Queries[key].trim().indexOf('mutation') === 0;
            return <option key={key} value={key}>{isMutation?"(Mutation) ":""}{key}</option>
        })}
    </select>
    // ...
</GraphiQL.Toolbar>

And here's a screenshot of what it does.

The thing I still want to see work for this repo is supporting persisted queries - really just for the sake of completeness. I have some ideas on how to do it, but perhaps someone reading has done this before?

sifting thru the types

Matthew Foley — Fri, 05 Nov 2021 14:33:21 +0000

Flow state is a rare treat for me these days. The last time I can remember being in that zone was working on a GraphiQL implementation for Open Sauced, https://explore.opensauced.pizza. The Open Sauced project makes use of OneGraph, to handle authentication and persisted query features in working with the GitHub GraphQL API. This was the first I had worked on any kind of GraphiQL implementation, so for those of you at the point I was at then, GraphiQL is an Open Source project that can be used to interact with a GraphQL API in an ad-hoc and dynamic way, allowing a developer to iterate quickly on features from a data retrieval standpoint. This post is about the PR #2 in the repo.

@0vortex had laid a lot of the groundwork for this implementation and as he brought myself and @bdougieyo up to speed on the where things were at, the problem to solve was having too much stuff to interact with. OneGraph brings a lot of value to the table in working with GraphQL, and this is evident in the number and breadth of APIs that it works with. For some reference, take a look at this image (or play with their GraphiQL tool).

The vision for https://explore.opensauced.pizza was to have a rapid prototyping tool specific to Open Sauced, and that's why having all these other services in the explorer tool is too much. We also wanted to let users quickly reproduce the queries we use in Open Sauced so that when a feature calls for an adjustment - this way, when its time to iterate on an existing feature, there's very little friction to finding that starting point. For reference, here's what the Explorer portion on our implementation looks like.

Before I forget to explain this part, the flow state came from the fun challenge of chopping up OneGraph's GraphQL schema, on the client side. I searched around, and I really couldn't find any practical examples of this. So now I got to venture into data science-y territory of manipulating a dataset iteratively :-)

When you look at a GraphQL result of an introspection query (where a GraphQL endpoint describes itself), it's mainly a long flat list of "types". These types refer to each other in different ways, and the GraphiQL tool uses all of this data to build up a dynamic UI to work with valid GraphQL queries. Also, a GraphQL schema gets validated in handling all of the cross references and such. In order to get things the way we wanted it, we needed to modify the schema to only include the pieces we absolutely needed. I tried unsuccessfully to take the approach of picking the parts of the schema I wanted and followed the links outward to extrapolate the required parts. Don't remember exactly why but it DID NOT WORK. So I settled on the opposite - tear out the parts I didn't want and work with whatever was left. This explains the wicked long regex I used!

Normally, the way GraphiQL React components would work with the schema would be something like this line:

this.setState({
  schema: buildClientSchema(result.data) 
});

But instead, the way the changes read:

// To modify schema, we follow this process:
// 1) Remove all the types we don't want, based on regex match
// 2) Strip out all of the dependencies that matched the same regex
// 3) Remove types of kind=OBJECT that have had their fields emptied out (to satisfy schema validation)
const filteredTypes = result.data.__schema.types
  .filter(nodeBlackListFn)
  .map(stripPrefixedDeps) 
  .filter(emptyObjectFilterFn);
const filteredData = {
  __schema: {
    ...result.data.__schema, 
    types: filteredTypes
  }
};
this.setState({ schema: buildClientSchema(filteredData) });

And now utility functions that make this work:

const blacklistRe = /(adroll|airtable|apollo|asana|box|brex|bundlephobia|chargebee|clearbit|cloudflare|contentful|crunchbase|descuri|devTo|dribbble|dropbox|eggheadio|emailNode|eventil|facebookBusiness|fedex|firebase|google|googleAds|hubspot|immigrationGraph|intercom|logdna|mailchimp|meetup|mixpanel|mux|netlify|notion|npm|openCollective|orbit|productHunt|quickbooks|rss|salesforce|slack|spotify|stripe|trello|twilio|twitchTv|twitter|ups|usps|ynab|youTube|youTubeSearch|youTubeVideo|zeit|zendesk)/i;
const typeBlackListFn = (f) => {
  return !(
    (f.type && f.type.name && blacklistRe.test(f.type.name))
    || (f.name && blacklistRe.test(f.name))
    || (f.type && f.type.ofType && f.type.ofType.name && blacklistRe.test(f.type.ofType.name))
  );
}
// Filter function for picking things that are not blacklisted
const nodeBlackListFn = (f) => {
  return !(
    (f.type && f.type.name && blacklistRe.test(f.type.name))
    || (f.name && blacklistRe.test(f.name))
  );
}
// Strips out dependencies that are blacklisted
const stripPrefixedDeps = (type) => {
  return {
    ...type,
    fields: type.fields ? type.fields.filter(typeBlackListFn) : type.fields,
    inputFields: type.inputFields ? type.inputFields.filter(typeBlackListFn) : type.inputFields,
    possibleTypes: type.possibleTypes ? type.possibleTypes.filter(typeBlackListFn) : type.possibleTypes
  }
};
// Removes OBJECT types that have had all of their fields stripped out.
const emptyObjectFilterFn = (type) => {
  return type.kind !== "OBJECT" || type.fields.length > 0;
};

There was one other feature in the same PR, that I'll talk about next week!