The first thing developers come across when trying to learn about how to "code accessibly" is ARIA.  Little do they know, ARIA is actually the last resort method we should turn to.  Let's go over ways we can make our code accessible!

DIV Hell.  Sometimes, we just don't know or care to look up what the best element is to use, so we fallback to a simple DIV. The problem is that the overuse of DIVs means missing out on a lot of native accessibility and functionality that semantic HTML provides:

ATs try to convey this information to its users by reading the role of the element. Roles can be defined by adding a 

, etc have inherit roles assigned to them so we don't need to take that extra step.  It even goes a step further by providing additional information like heading level, tab indexing, and default keyboard handlers depending on the accessibility API provided by the browser, all of which we would need to define ourselves when using DIVs.

None of this is to say that you can't use DIVs! Using a 

 would be appropriate when we want to style individual pieces within a semantic element, or if no native semantic tag exists for the type of content we need.

// Bad heading - this gives no indication to non-sighted users that this is a heading element
<div class="heading-2">Semantic HTML</div>

// Okay heading - we can use a role attribute to indicate this element is a heading, 
// but we also need to use aria to indicate level, which is just extra steps
<div role="heading" aria-level="2" class="heading-2">Semantic HTML</div>

// Best heading - using the native HTML heading tag provides both the role and level to the user, 
// and if browsers update their accessibility API to change what additional information is provided to ATs, 
// no additional dev work is needed.
<h2 class="heading-2">Semantic HTML</h2>

// Best heading with div layout - an example where we would want the heading to still read as one word, 
// but maybe we want the layout to be styled differently
<h2 class="heading-2 display-flex-column">
  <div>Semantic</div>
  <span class="red-text">HTML</span>
</h2>

Making your code more semantic is probably one of the easiest fixes you can start applying by simply switching some of your DIVs to something more meaningful.  It's also much easier to follow along with code if you can read that the section is a 

 and start applying the most appropriate ones to your code! 

If you've researched how to make code accessible, you've probably come across 

 and maybe even started to think about adding it to all of your elements. 

The first rule of ARIA is to avoid using ARIA.

  Semantic HTML is already natively accessible (it's often that we just aren't using or structuring it properly), but using ARIA overrides the information presented to ATs, which can inhibit users if you don't know what you are doing.

ARIA attributes are most often needed when we start adding interactions or states to our elements.  We use visual design to convey to users with sight that an element is loading, has toggled something on the page, or is currently selected, but we also need to convey this information programmatically for users without sight.  We can do this by adding appropriate ARIA properties that will communicate the information to ATs.

Let's use a simple accordion component as an example:

const Accordion = () => {
  const [isOpen, setIsOpen] = useState(false);
  const toggleOpen = () => setIsOpen(!isOpen);
  return (
    <>
      <button 
         onClick={toggleOpen} 
         aria-expanded={isOpen}
         aria-controls={isOpen ? "panel" : null}>
           Toggle Content
       </button>
      {isOpen && <p id="panel">This is some panel text</p>}
    </>
  )
}

Accordion? Drawer? Toggle? Whatever you want to call it.  But here it is.  A button that when activated, will show or hide additional content.  To make this accessible for all users, we've added two ARIA properties:

With just these two properties, we've managed to make our component more accessible.  Yay!  Now when users are focused on the button, it will announce "expanded" or "collapsed" depending on the state, and users will understand that this button is hiding/showing other content on the screen (assumedly content that appears immediately after/next to this button).

Programmatic names refers to the textual label or content of an element and are useful to users for distinguishing between elements.  Names are the alt text we give images,  the inner text of an element, and the 

  element.  Here are some ways to program an element's name:

// Inner Text (preferred)
<p>This is a programmatic name</p>

// Alt Text for images (preferred)
<img src="some-image.png" alt="This is also a programmatic name" />

// Label of input (preferred)
<label for="inputId">This is a programmatic name</label>
<input id="inputId" name="notProgrammaticNameFYI" type="text" />

// aria-labelledby
<h2 id="formHeading">This is the Programmatic Name for the Form element</h2>
<form aria-labelledby="formHeading">
  <input id="consentCheckbox" type="checkbox" value="agree" />
  <label>I understand that the aria-labelledby attribute changes the programmatic name of the form element from all this inner text content to just the inner text of the heading element.  This content is still reachable if a user moves focus to the children element within the form.</label>
  <button type="submit">Submit</button>
</form>

// aria-label
<a href="#" aria-label="This is the programmatic name">This text is ignored</a>

// BAD BAD BAD - aria-label - BAD BAD BAD
<a href="#" aria-label="">This text is ignored. As long as an aria-label attribute is present, it WILL override the inner text</a>

I've thrown in some ARIA attribute methods in that example, but as we know by now, those methods aren't as preferable as non-aria methods.  It's more common to use those methods when retrofitting inaccessible code.

The most common accessibility issues arise around images. Between not knowing what constitutes appropriate alt text to when to even add alt text, it's easy to get confused about the rules around accessible images.  So let's clear this up.

Done.  Honestly, that's the bulk of a developer's job: just make sure an alt tag is present.  The confusion is around what the tag should read.  There are several types of images, and if you can discern the type, you'll have a better idea of what content should fill the tag:

Decorative images are images that are used to simply add atmosphere to a design, and most often will be most of the images you encounter.  Generally, if you can remove or replace the image, and the page doesn't lose any of the meaning or context it's trying to convey to its user, then it's decorative. Since it's not vital to the context of the page, we want to suppress the image for users using assistive technologies (ATs) so that it doesn't create unnecessary noise.  We can do this by providing an empty alt tag to images like so:

// Image used for background pizazz
<img src="lovely-background.png" alt /> // or alt=""

// Image where the alt text would be the same as visible text next to it.  
// In this case, even if you removed the image, a user would still know what the button does.
<button>Search <img src="magnifying-glass.png" alt /></button>

Even though we aren't adding any content to it, the alt tag 

 be present so that users and ATs know that the image was intentionally suppressed.  Otherwise instead of skipping over the image, ATs would focus on the image and either read the file name, or announce "image", either of which would cause the user to feel confused or FOMO.

So you might have guessed that "meaningful" images are the opposite of decorative: they provide context or are supplemental to other content on the page.  Meaningful images could be infographics, figures, iconography, images with text, or any other image that if removed, would lessen the user experience.

// Infographic example: try to summarize what the image is trying to convey instead of describing the actual image
<img src="map-of-travel-route.png" alt="Route starts in Venice, Italy, continues to Flourence, then Rome, with an optional trip to Sorrento Peninsula." />

// Iconography example: once again, write what is trying to be conveyed instead of describing the image
<button><img src="magnifying-glass.png" alt="Search" /></button>

// Image with text example: images of text such as logos should have alt text conveying the words in the image
<img src="EF-GAT-logo.png" alt="EF | Go Ahead Tours logo" />

// Gallery example:  when showing off photography as part of an art gallery, 
// a related figure to the content, or any other reason you might believe that the image 
// is important for understanding or selling context, try to describe the image as best as possible.
<img src="photo-in-art-gallery.png" alt="5 Zebras scattered across the golden fields of Africa with a single tree in the distance under a cloudless blue sky" />

The main thing to remember for developers is that 

 image element will need an alt tag, and if you can discern the type, you'll know whether you can just apply an empty alt tag, or if you need to make sure that authors can set the text if integrating with a CMS.  If you have trouble figuring out the type of an image, this handy 

There are two things to know about focus: it must be visible and sometimes managed.

Achieving a visible focus is easy.  In fact, it's already done!  You know that outline that appears when you click on a link?  That's a visible focus.  Sighted keyboard users depend on that outline or some visual indicator to keep track of where they are on a screen.  The problem is often when we intentionally remove that indicator using 

 , making navigation nearly impossible for some users. Instead of removing the outline entirely, you can remove it for just mouse clicks!  Check out 

  which allows developers to style the focus indicators for mouse vs keyboard activation.

Now let's talk about focus management.  Usually, a keyboard user navigates a page sequentially by just hitting the tab key (or shift+tab to go in reverse order), but sometimes we need to hijack their focus to take the user to where they want (or need) to be.  A simple example would be skip links: usually an anchor link a user can click to scroll to the appropriate place on the screen.  The thing about scrolling...is that it only helps mouse users.  To create the same experience for keyboard users, we need to also use something like 

 to programmatically move focus as well.*  

But what about something more complex like a modal?  Often we overlay modals front and center of the screen and prevent interaction with anything behind it...but only visually.  To replicate that same kind of experience for keyboard users, we need to use Javascript to 

...which sounds like a lot, but honestly there are tons of library packages that will just do this for us like 

There are lots of situations where a dev might need to manipulate the focus, and the best way to determine if you need to manage focus would be to simply try navigating solely with a keyboard.  If at any point you can't get to an element without knowing exactly where it is on the screen, then you may need to shift focus.

There's sooooooo much.  I think this covers some of the larger things?  But I'll list some more resources I like to reference.  If this is all new to you, honestly don't expect to learn and remember it all in one day.  If you start getting in the habit of asking yourself "well what if a user can't do X," you'll start looking up solutions the same as any old problem you encounter.  Read blogs, attend webinars, and ask questions!

Notable accessibility vendors (sign up for their newsletters to get related webinars and news)

Follow some awesome accessibility dev experts

 can only be used on elements that are tabbable (e.g. buttons, links, inputs).  To move focus to elements that are not inherently tabbable, try adding 

 , which will allow focus, but not add the element to the tab order.  To add elements to the tab order you can use 

 (useful for when you have an element within an element that scrolls or something). Avoid setting a tabindex to anything greater than 0, as you begin to manipulate the focus order, which should be determined by the structure of your code.

Read about common accessibility issues in code and how to fix them

Creating Accessible Components

When I was an intern I got my first accessibility audit back from a 3rd-party auditor. It listed out issues with the website I was working on and provided recommendations on how to make my code more accessible.  Then when it came to future features, I would copy-paste the same techniques to other parts of my code, but I wouldn't fully understanding why or when those techniques were needed.

Since then I've learned how much context I was missing around users and how they actually use and experience the web, part of that context being how to accurately test my work.  So let's talk about how we can check for accessibility!

Yay! Yes! Tools!  Gotta love it when you can just run testing software that tells you what's wrong with your code.  

 can be run by anyone and will scan a page and produce a list of code-level issues such as if an 

 tag, an invalid value has been passed to an ARIA attribute, and if an element has no programmatic text. There are also linters like the 

Automated testing tools are super easy to include into your development workflow and a quick way to learn about common issues and fixes.  However, while automated tools are great for correcting your implementations, they won't necessarily alert to when a feature needs some extra a11y love.  That's because automated tools don't necessarily know what it is that you're trying to achieve.  For example, there are certain ARIA attributes that a toggle button needs to be made accessible to all, but automated tools don't know that you're trying to build a toggle button, so it won't tell you what you're missing.  But 

 know.  And that's where manual testing comes in.

Manual testing is something we do all the time.  We interact with a feature or component and see if it does what we expect it to do.  But as mentioned in my post on 

the different ways people navigate the web

, there are so many different tools and methods that people use to interact with our websites and apps.  So 

 we should be testing our work with as many assistive technologies (ATs) as we can get our hands on, right?! Wrong. Since most ATs consume and make standard calls to the same accessibility APIs, we can usually say that if it works with one AT, it'll work for most others.  So we can easily cover most cases by testing with a few tools we likely already have at our disposal.

A lot of us are used to using a mouse to point and click our way through the web, but that's hard to do for users who have trouble seeing where elements are on a page, or even users who have difficulties with the minute movements a mouse can require.  Instead users should have the option to navigate solely with a keyboard.  When navigating with a keyboard, it's typical to scroll via Arrow keys, navigate to interactive elements using the Tab key (and Shift+Tab to reverse it), activate buttons with the Enter or Space keys (for link elements, only the Enter key is used), and use the Esc key to close menus, modals, etc.  The 

 is a great reference for how users expect to interact on a per component basis using a keyboard (and also a great place to view accessible versions of common components). During testing, you'll want to ask yourself the following:

Honestly, if at any point you're trying to use a keyboard and you get frustrated, it's a good indicator that your user will get frustrated as well. 

This is the most common tool used when navigating the web, but it's often overlooked how much we use the keyboard as well.  Most people without disabilities are hybrid users and will seamlessly switch between mouse and keyboard.  Just as there are those who only use keyboards, there are those who rely solely on "point and click" methodology.  

 is a popular speech recognition software that allows users to navigate via dictation, and the most preferred method of interaction is "saying and clicking" (check out this 

 if you need visualizations).  When, say, a quick search form in the header is only submittable by pressing the Enter key, it becomes harder for these users to perform the desired functionality.  We also want to keep in mind target size.  We don't all have the steady hand of a surgeon, so the general rule is to make sure that all interactive elements have a width of at least 44 pixels. Other than that, there aren't too many out of the ordinary things to test for with a mouse, but if you're looking for more rules like the keyboard list from earlier or you deal with crazy custom interactive components, you can check out the 

 section in the WCAG 2.1 for related rules.

Making sure that your website or app is resizable and customizable ensures that users with low vision can use your product.  Honestly this is a pretty big one considering people with low vision tend to be those who are older or even those who have lost their glasses to the sea while swimming at the beach after an earthquake...anyway, it's just to say that this helps more people than we think.  Users with uncorrectable low vision might use magnification software such as 

, which comes with a bunch of features like zooming in 200x, and enlarging text of webpages and apps.  We can check if our products will respond correctly in a few ways:

tl;dr Resize your browser window, zoom in 200%, and resize your text.  That's it.  That's how you test.  If anything looks wonky or unreadable, then it probably needs some fixing!

Okay.  So if you need one take away from this blog, it should be that you should 

 on your website.  It'll cover keyboard functionality and text-to-[insert preferred sense here] accessibility, which will pretty much cover 90% of your issues (I put a random percentile in there for the drama.  Please don't quote me!).

A screen reader is software a user can use to translate written text on a page to audible speech.  But it's not just the visible written text that it can announce.  If a website or app is marked up correctly, screen readers will announce 3 important pieces of information:

If you're testing with a screen reader and you don't hear those three things (save for exceptions noted earlier), then it's a good indication that you have an accessibility issue to log.  A lot of the success criteria of the WCAG relate to these three pieces of information being accessible, and if it works with one screen reader, it's likely to work with a majority of other ATs.

If you're on a Mac, the Voice Over screen reader is already installed and you can start using it right away.  For Windows or other OS's, popular screen readers are JAWS (subscription based) and NVDA (free and open-sourced). When using one of these screen readers, it's important to make sure you're testing with proper screen reader/browser pairings.   Based on the most recent 

, you should test your desktop sites with at least one of the following:

Just as Voice Over is available on Macs out of the box, it's also available on iPhones, and even most Androids come with preinstalled with TalkBack:

You'll want to test with the most popular pairings to determine if any bugs are implementation issues or compatibility issues, as it's often the case to report a bug with the AT for compatibility issues instead of trying to find a workaround on your end.

I would say that what we've covered so far will catch most accessibility issues.  If you're doing dedicated accessibility testing, there are a few other methods you could use to get more coverage.

This is actually a pretty big thing to test for, but I'm putting it in this section because it only applies to when you have animations, videos, or movement in general on your website or app.  Users with certain cognitive disabilities may have trouble using a product that has distracting movement and content on the site, and those who use a screen reader will have difficulty hearing if there's any audio content that plays automatically.  To help with this, pretty much all 

operating systems come with a way to reduce or turn off motion on their device

, and if implemented correctly, will also apply to websites and apps.

When it comes to animations, videos, and audio, make sure to check the following:

Windows users have a control setting called "High Contrast Mode" that enables them to set a sort of theme for their display.  They have the ability to decide what the color of their background, buttons, links, static text, selected text, and disabled elements.  This setting helps users with low vision and photosensitivity by allowing them to choose their own color scheme and set contrast levels of their preference.  Since essentially this mode overrides the CSS of apps and websites, it's useful to check to make sure that no meaningful content is loss.  

 is a subscription based testing tool that emulates many of the popular software-based ATs, and it has a good description of 

Phew!  That was a lot, and maybe even more information than you wanted.  But I swear: understanding what the issues are and how to reproduce them will help you understand the best approach towards fixing them.  Or even just helps you know what to search for.  Like "how to reduce motion based on user settings," ya know?  But if not, I'll talk about the most common accessibility issues on websites and how to fix them in another post.  For now, thanks for reading!

* You might be wondering if you should care about an AAA guideline when often websites only try to meet AA guidelines.  The answer is "yes," though they are more often considered as "best practices" to help provide an even better experience for users.  It might be helpful to think of conformance levels in this way: A = minimum needed to unblock users from using your site; AA = minimum needed to prevent users from rage quitting your site; AAA = minimum needed to provide a decent experience for users. It should be noted that it's near impossible to meet all AAA guidelines, as some actually may conflict with legacy systems, modern designs, and security practices.  So it's best to consider them as "best practice" and do what you can.

** I know y'all are itchin' to see some code and learn how to implement this, but that'll be in another post.  Look at how much text is already on this page!!

Learn about the tools you can use to check if a website is accessible to a variety of users

How to Test for Web Accessibility

One of the wildest myths I've heard about people with disabilities is that "they can't use the internet."  As if we've somehow managed to get toasters to tell us the weather to solve whatever problem that was, but when it comes to navigating a website without the use of sight, it's all shrugs.  Obviously none of that is true. People with various disabilities use the web every day, just in a way that's different than people without disabilities would.

Okay, there was some sass in my first few sentences, but during my second internship as a developer I was asked to remediate a litany of accessibility issues on a banking website, and it was then that I was informed that people with disabilities who use my websites don't just "figure it out".  They utilize assistive technologies that depend on me building software properly so that in turn it can convey the necessary information to users. Assistive technology (AT) is any device or piece of equipment that can be used to help improve one's capabilities: wheelchairs, canes, screen readers, and much more, but in this post we're only going to focus on the ones that help with navigating software.

Since there are a broad range of disabilities, it stands to reason that different users have different ways of using websites.  So let's talk about some of them:

This is probably the most common type of disability people think of when it comes to web accessibility.  Blindness refers to a significant and uncorrectable loss of vision. Since they usually can't see the elements on a web page, people with this type of disability often rely on screen readers like 

 to read aloud the information displayed on screens. Users who use a screen reader often use a keyboard to sequentially navigate through the elements on a page.  When a document is properly structured, more advanced users are able to quickly navigate by headers, sections, images, links, etc.  Since screen readers rely on textual information, it's important that any meaningful images and icons also have a programmatic text alternative.

People with low vision do have some sight, but that sight may be restricted, blurry, or dim. Some choose to be aided by the use of screen readers, but most often users with low vision still rely on their sight.  To assist with this users may simply zoom up to 200% of the default web page size, or there's magnification software that allows user to zoom in on the part of their screen where the mouse pointer is.  Users are also able to customize and enlarge the text size from their OS settings to adjust the display on websites and app.  People with low vision also rely on inclusive designs to ensure that text and elements have enough contrast against their backgrounds.

Color-blindness often isn't considered a disability by some, but when information is conveyed using only color as the means, a barrier is created that prevents people with color-blindess from accessing.  Often people with this type of disability do not use or have any corrective means and rely on inclusive design to obtain the information they need (e.g. a line graph differentiated by colors could also use different line strokes or differently-shaped point markers).

Deafness refers to the complete loss of hearing, and users with this type of disability often rely on sight to experience the world.  Barriers largely comes into play in regards to media with audio.  People without hearing rely on captions, transcripts, and even sign language to convey the spoken word.  While some screen readers also have speech to text capabilities, most of the time users rely on proper captioning when it comes to time-based media.

Deaf-blindness is a good example of how users can have multiple or compounding disabilities.  Those without sight or hearing rely on braille devices to convert the text on a website to braille that they can feel.  Braille devices work in a similar manner to screen readers, where as long as there is text that the technology can consume, there is information that the device can produce for the user.  When it comes to multiple disabilities, usually making your website accessible for each individual disability will also help those with multiple disabilities.  One exception here for those with deaf-blindness is that they can only consume time-based media via transcripts, and not captions.

Motor disabilities is a broad term to group different kinds of impairments such as loss of limbs, mobility and muscular limitations, and even just sensations of pain when moving. There are a variety of assistive technologies available to help users navigate websites such as specialized mice and keyboards to accommodate limb differences, mouth-sticks, eye-gaze systems, voice-command systems, sip-and-puff devices, switches, and so on.  The most famous example of some with a motor disability would be Stephen Hawking, who used a cheek-device that would move the element focus across the screen, and when it was focused on the desired element, he would trigger an action based on the slightest movement of the muscle under his eye. (Or instead of trying to interpret my bad explanation, you can watch a 

video of Hawking using the device (Opens in new window)

.)  Devices like specialized mice, voice-command, and eye-gaze systems depend on being able to use a website with solely the use of mouse pointers.  The other mentioned devices depend on websites being navigable using solely a keyboard.

Speech disabilities can include difficulty producing speech that is recognizable by some voice recognition software, either in terms of loudness or clarity. Someone with a speech disability needs to be able to use an alternate input mode such as text entered via a keyboard.

This is probably the broadest group, ranging from learning disabilities to memory impairments to seizure disorders.  There's no one assistive technology this group uses to navigate websites, but there are a range of element and functionalities that a website can utilize to help make websites accessible to a wide variety of users.

Honestly this was me trying to keep it short when talking about users with disabilities and the web.  There's much more to consider like the technical difficulties and barriers they encounter on the daily, how to ensure that your website can accommodate a variety of assistive technologies, the differences between technological barriers and best practices, and a lot more. But those are for another post and hopefully this provides a good start to your accessibility journey. Thanks!

Get to know the ways people with different disabilities experience the web and the tools they use to navigate it.

Understanding How People with Disabilities Use the Web

Understanding How People with Disabilities Use The Web

One valuable feature of Apollo Client is 

 fields.  These fields are redacted from an operation that is sent to the server by an application, and then computed and added to the server response to generate the final result.  The 

 clearly explain how to leverage this feature for local state management, but it's less clear on how to derive 

 local-only fields solely from other fields on the operation result.

Suppose we have an operation that queries for the current user.

const USER_QUERY = gql`
  query User {
    user {
      id
      firstName
      lastName
      department {
        id
        name
      }
    }
  }
`;

We use the result of this operation in some 

 component to render a display name in the format of 

As time goes on, we find ourselves using this same 

 format in numerous places throughout our application, duplicating the same logic each time.

We consider how best to reuse this formatted name across our application.  Our first thought might be a server-side resolver, but this isn't always feasible.  We might want to make use of client-side data - local time, for example - or maybe our calculation will use fields from a variety of subgraphs that are difficult to federate between.  Our next thought is a React component, but this won't work very well either.  We want a consistent 

 for our displayName, but usage or styling might vary considerably depending on context.  What about a hook, then? Maybe a 

 hook that encapsulates the query and display logic?  Better, but inelegant: we'll probably find ourselves invoking both the 

 hook in the same components, over and over.  What we'd really like is not logic 

 from the query result, but rather logic 

The first requirement for a local-only field is a corresponding field policy with a 

 function in our cache. (Technically, a field policy could be omitted in favor of reading to and writing from the cache, but we'll save that for another post.)

const cache = new InMemoryCache({
  typePolicies: {
    User: {
      fields: {
        displayName: {
          read(_) {
            return null;  // We'll implement this soon
          }
        }
      }
    }
  }
});

 function is the existing field value, which will be undefined for local-only fields since by definition they do not yet exist.

The other requirement for a local-only field is to add it to the operation with the 

 directive.  This directs Apollo Client to strip the field from the server request and then restore it to the result, with the value computed by the 

const USER_QUERY = gql`
  query User {
    user {
      id
      firstName
      lastName
      displayName @client
      department {
        id
        name
      }
    }
  }
`;

 hook, but of course, it always returns null right now.  Our desired format requires three fields from the server response: the user 

, a helper provided by the second "options" argument of the 

 function.  This helper will provide the requested value (if it exists) from the parent object of the field by default, or from another object if it's included as the second argument.  This helper will also resolve normalized references, allowing us to conveniently nest 

 invocations.  Note that we can't really force the operation to include the fields on which the local-only field is dependent, and thus 

 always has the potential to return a value of undefined (even if it's a non-nullable field).

Now, it's trivial to use this formatted display name anywhere in our application - it's just another field on our query data!

const BlogPost = () => {
  const { data } = useQuery(USER_QUERY);

  return (
    <div>
      <BlogTitle />
      <p>Written by {data.displayName}</p>
      <BlogContent />
    </div>
  );
}

Bonus: Local-only fields with GraphQL Code Generation

It's trivial to include local-only fields if you're using 

, too.). All you need to do is extend the type to which you're adding the local-only field in your client-side schema file.

const typeDefs = gql`
  extend type User {
    # Don't forget to return a default value
    # in the event a field dependency is undefined
    # if the local-only field is non-nullable
    displayName: String!
  }
`;

Computing Apollo Client local-only fields purely from other operation fields.

Computed local-only fields in Apollo Client

In this post, I'll cover the "why" of gRPC, the structure of protobuf files, and some of the Typescript interop offered by two NodeJS packages for gRPC: 

This post assumes some familiarity with microservice architecture and RESTful API calls. With all APIs, including the well known REST and SOAP flavors, there are two players:

A deep discussion on the "how" and "why" of RESTful microservices (statelessness, etc.) is best left for another post. Instead, we'll dive into gRPC, an alternative to REST and SOAP that's been gaining some traction recently. gRPC is another protocol for two back-end services can use to communicate that confers some unique advantages.

gRPC is an efficient means of service to service communication and is an alternative to REST and SOAP. gRPC sends messages over HTTP/2 using a binary serialization standard called protocol buffers. Google initially released the gRPC serialization standard in 2016. Protocol buffers are often referred to in the shorthand "protobufs". 

RPC is a ubiquitous term that stands for "Remote Procedure Call", a fancy way of saying that we want to run some code on another machine. The "g" doesn't actually stand for "Google", even though they created and continue to maintain gRPC. They use the letter G to name releases, such as version 1.12, 

Like any HTTP request made with a library like Axios/Fetch in Node or HttpClient in .NET, gRPC is language agnostic. As such, clients needn't concern themselves over the implementation details of the API on the server. Rather, they need only be aware that the gRPC service exists to serve the request, as well as the name and shape of the request and response.

gRPC comes with a couple of advantages, or rather, use cases in which it might be preferable to REST.

Now that we know a little more about what gRPC is and when we might consider it for a project, let's dive into an example using Typescript.

"Hello, World" for the tiny gRPC service we'll build starts with our service definition. Whatever language our caller or server are using isn't really important just yet. Google maintains reference 

 for protocol buffer version 3, the newest production-ready version of the syntax. In our contract, we want a single function that accepts a 

// greeter_service.proto

syntax = "proto3";

package greeter_service;

service GreeterService {
    rpc Greet (GreetRequest) returns (GreetResponse) {}
}

message GreetRequest {
    string name = 1;
    string location = 2;
}

message GreetResponse {
    string greeting = 1;
}

Pretty straightforward, but let's break this down.

syntax = "proto3";

package greeter_service;

You'll see something like this at the top of most protobufs. 

service GreeterService {
    rpc Greet (GreetRequest) returns (GreetResponse) {}
}

 methods/functions that some service must provide, as well as the types of the request and response messages. A single .proto file can contain multiple logical  

 keywords, and a single service can have as many 

message GreetRequest {
    string name = 1;
    string location = 2;
}

message GreetResponse {
    string greeting = 1;
}

 keyword specifies the shape of the messages that will be passed back and forth. It's possible to nest messages, just like nesting objects in JSON. Arrays are there as well. This allows for some pretty robust messages with structures that everyone who's used to JSON should be familiar with.

The only thing that should stand out as a little unusual here are the things that look like assignment operators (=) with a number after them. These numbers specify the 

 for each field in the message. This is the order in which the binary data will be arranged before the messages are transmitted. Having a mismatched field order between client and server 

 cause errors, or might not. Imagine having two string fields with mismatched field order. The server would just see two strings, but we might end up with data from the 

 field on the server! Quite tricky to debug. 

Now that we've got a protobuf definition, let's build a Typescript service that can handle the request. I ran a few commands to set up my dependencies in a brand new Node project.

For this project, we start with an empty npm package that I've called 

. The project consists solely of the following:

npm i @grpc/grpc-js @grpc/proto-loader ts-node

npm i --save-dev rimraf typescript ts-node-dev

Of these, the two gRPC packages and rimraf will be part of our build workflow. We'll also need a couple of scripts:

"scripts": {
  "dev": "tsnd --transpile-only --ignore-watch node_modules ./src/main.ts",
  "generate": "rimraf ./proto && proto-loader-gen-types --longs=String --enums=String --defaults --oneofs --grpcLib=@grpc/grpc-js --outDir=proto greeter_service.proto"
}

 will generate the types necessary for us to write code for our handler and server setup. 

 script looks a little daunting, but that's largely due to the number of 

 folder at the project root that consists of several helper types. Since we added 

 to .gitignore, we won't source control this folder. Furthermore, any time our protobuf definition changes, we can simply run the script again.

A handler refers to a function on the server that will be invoked whenever a client calls a given RPC. The handler's job is to accept the request message specified in the protobuf, and provide the required response message. For our simple case, we'll need a Greet function that accepts an object with 

 properties, that returns an object consisting of a single 

With Typescript, we can use the generated type 

 to specify what the shape of our handler (a Javascript object) should look like:

// ./src/greeter.handler.ts

import { GreeterServiceHandlers } from "../proto/greeter_service/GreeterService";

export const greeterHandler: GreeterServiceHandlers = {
	Greet: (call, callback) => {
		const { name, location } = call.request;
		callback(null, {
			greeting: `Hello, ${name}, how is the weather in ${location}?`,
		});
	},
}


When the handler is invoked, the request data is available on the 

 function is used to "return" the response to the client, in lieu of the return statement you'd typically see in an Express REST API. The first parameter in 

 is reserved for an error, if the server happens to catch an Exception and wants to report it back to the caller. If we had more than one RPC in our protobuf, we'd just implement them as siblings of 

Finally, we're ready to start the server by writing the implementation for 

// ./src/main.ts (Server project)

import { Server, ServerCredentials } from "@grpc/grpc-js";
import { loadSync } from "@grpc/proto-loader";
import { loadPackageDefinition } from "@grpc/grpc-js";
import { ProtoGrpcType } from "../proto/greeter_service";
import { greeterHandler } from "./greeter.handler";

const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;

const grpcServer = new Server();
grpcServer.addService(proto.greeter_service.GreeterService.service, greeterHandler);
grpcServer.bindAsync("0.0.0.0:50051", ServerCredentials.createInsecure(), (err, port) => {
	if (err) {
		console.error(err);
	} else {
		console.log(`gRPC Server bound on port: ${port}`);
		grpcServer.start();
	}
});


There's a lot to unpack here, but the actual code is only around 6-8 lines long.

// Loading the service definition from the protobuf
const proto = loadPackageDefinition(loadSync("./greeter_service.proto")) as unknown as ProtoGrpcType;

 function, which constructs a utility object for us based on the service definition that it parses from the specified .proto file. We'll use this in a bit.

// Construct the server and add the Greeter Service, mapping greeterHandler 
const grpcServer = new Server();
grpcServer.addService(proto.greeter_service.GreeterService.service, greeterHandler);

 helper object by adding the GreeterService to our gRPC server. Importantly, this step is where we set up the mapping between the gRPC service and the handler that we created earlier to handle requests to this service.

grpcServer.bindAsync("0.0.0.0:50051", ServerCredentials.createInsecure(), (err, port) => {
	if (err) {
		console.error(err);
	} else {
		console.log(`gRPC Server bound on port: ${port}`);
		grpcServer.start();
	}
});

Lastly, we start the service using 0.0.0.0:50051 as an alias for localhost, port 50051. When using SSL on a production server, 

, but this will suffice for dev work. In the callback, we show a helpful message and finally start the server.

 on our server, we'll be able to make Greet requests to the handler using any gRPC client like 

. To finish the example, though, let's create a new project and make our own client using Typescript.

For the initial setup, I created an npm package called 

When developing  an API, we very often reach for REST.  In some cases, however, we can instead take advantage of a structured and speedy standard called gRPC.

blog.

Creating Accessible Components

How to Test for Web Accessibility

Understanding How People with Disabilities Use the Web

Computed local-only fields in Apollo Client

gRPC Services with a Type Generation Example for NodeJS and Typescript

Why every product design team needs a UX writer

How I got here: Amanda, UX designer

Analytics Bad News: The 😬 Emoji In Real Life

GraphQL Codegen: What is it?

Using GraphQL as an anti-corruption layer in front of legacy services

NestJS Dependency Injection with Abstract Classes

Optimizing React Native offline mode using Apollo Cache Persist