DEV Community: Sheelah Brennan

Lessons from Ten Years in Web Development

Sheelah Brennan — Wed, 01 Nov 2023 02:00:27 +0000

It’s hard to believe that my blog has posts that are now ten years old. That also means that I’ve been working in web development for 10 years! Back in 2013, I transitioned from working in site reliability engineering to working in frontend engineering. I spent most of the prior year ramping up on web technologies during a leave of absence from work that I was lucky to get, and in 2013 I started working in the field. That’s when the “real” learning — the learning-on-the-job phase — started.

So what have I learned in the past 10 years of working in this field, and maintaining my (infrequent) web dev blogging?

Blogging and Note Taking Pays off

Writing short blog posts (or notes somewhere at a minimum) on how you were able to troubleshoot and resolve a particular web dev issue is useful. These help your future self when you inevitably encounter that same issue later on. They also help people like you who are facing the same problem and are desperately searching the web for a solution. For example, I have a short blog post from 2014 (yes, a whopping nine years ago from now!) on how to handle PHP errors that can crop up when including SVG files. That post still gets frequent views today!

Tech Changes but the Underpinnings Remain

Technologies come and go, but the underlying web tech -- HTML, CSS, and JavaScript -- remains. Back in 2013, I was way into Sass and Compass. I also loved building projects on top of Foundation, a Bootstrap competitor that was Sass-based, and Susy, a Sass-based grid framework. While these were my ride-or-dies at the time, the web has changed since then. For example, we can do so much more now with plain ol' CSS, with tools such as CSS grid and flexbox for layouts.

I also was a diehard Grunt user, and then a Gulp user, and then later a Webpack user. These were all different tools for running tasks and compiling code. The landscape changed pretty rapidly.

I was way into jQuery when I was first learning web development in 2012. Now, we have a lot of JavaScript frameworks (see below) at our fingertips, and with the advent of ES6 and more recent releases, vanilla JavaScript has gotten so much more powerful.

The fundamental web technologies remain though, and if you're able to get comfortable with those, I've found you'll be able to pick up new web technologies and tools fairly quickly.

JavaScript Frameworks Come and Go

JavaScript frameworks definitely come and go, but JavaScript fundamentals are always useful.

Soon after I had gotten decent at jQuery, AngularJS was the hotness. I learned Angular (v1) at my first web development job and quickly saw how that road was paved with footguns. While the 2-way data binding was magical, it was so easy to end up with global state everywhere!

React felt like a revelation when I tried it a couple years later. While that Angular-specific knowledge like directives was no longer relevant, the fundamentals of JavaScript like array map() , loops, object destructuring, and other ES6 features were still very useful knowledge to have.

Interests Change

Your interests also will eb and flow. Ride the wave and follow your curiosities. Back in 2013, I got into PHP and WordPress, and even migrated my site from Octopress, an early static site generator, to WordPress for awhile. I got into building custom WordPress starter themes and used that for freelance projects. Then within a couple years I got really into JavaScript frameworks — first AngularJS and then React.

These were fairly different libraries, but with some time learning and experimenting, I was able to ramp up on them and really enjoyed using them in turn.

I then ended up migrating my blog back to a static site, this time based on Gatsby. I have no regrets that I followed my curiosities and dove into these different JavaScript frameworks, leaving the PHP and WordPress world behind.

Your career interests may change too, and that's expected. "Don't die wondering!" is something I like to remind myself when considering a pivot. I went from frontend engineering in a giant tech company, to frontend engineering in a media startup, to frontend engineering in a product-turned-ecommerce startup, to design systems engineering at a fintech startup, to my current role as a design technologist at an enterprise software company. Changing roles like this, either by transferring within a company or by switching companies completely, is how you find out what you really like and really don't like.

User Needs Remain Unchanged

It's easy to get wrapped up in different tech stacks and JavaScript frameworks, focusing on the developer experience at the expense of everything else. At the end of the day, the user experience is most important. Taking the time early on in your projects to consider the UX, web performance, and accessibility goes a long way to making the web a better place. Your users will thank you!

Featured image by Lan Gao via Unsplash

Favorite TypeScript Resources

Sheelah Brennan — Tue, 20 Dec 2022 21:40:47 +0000

TypeScript has become a mainstay in a lot of open source projects these days, and it's also a "preferred skill" in many web development and front-end engineering job posts.

I started learning TypeScript a couple years ago, when i started a new job on a design systems engineering team with a entire codebase written entirely in TypeScript. I remember worrying about being impossibly slow at building new components because of my lack of TypeScript experience.

In the end, it wasn't that bad, as I had teammates point me in the direction of some useful TypeScript learning resources, and I've found some more great ones since then. I will say that having the opportunity to learn TypeScript while working on a team is probably the best scenario. You will at times get stuck on something with a cryptic TypeScript error, and having someone at work to pair with when you're stuck is invaluable.

Here's some TypeScript learning resources that have been helpful for me.

Base Resources

These are some useful base resources to get your started.

TypeScript Deep Dive (free): A great overall reference. If you prefer learning via videos, the author, Basarat, has a lot of YouTube videos available as well.
TypeScript in 50 Lessons (paid): I learned all the TypeScript fundamentals from this book. I love that it's broken up into bite-size lessons, so you can learn a little bit at a time. Also, the examples use real-world scenarios, so they're easier to follow.
TypeScript Docs (free): A great starter resource to learn terminology, so that you can do a web search with the right words :)
TypeScript Fundamentals, v3 (paid): If you like learning by watching video courses and you have access to Frontend Masters, this is a great course. I took the v2 one but this is an updated version which will cover all the latest TypeScript features. Mike North is a solid instructor. If you are interested in learning how to convert an existing JavaScript project to TypeScript, check out the v2 version of this course.
Kent C. Dodds Blog: Kent C. Dodds has a fair number of blog posts about TypeScript that are useful as well.

React & TypeScript Resources

There are a lot of best practices that exist for using TypeScript in React projects. I highly recommend checking some of these out if you're using React and are new to TypeScript.

React TypeScript Cheat Sheet (free): This is my go-to React & TypeScript resource. This covers the basic best practices for doing things like creating components, creating types for React component props, etc. Even the TypeScript documentation links to this site, so you know it's a good one.
TypeScript for React Developers (free): This FreeCodeCamp course covers all the fundamentals.

Bonus: TypeScript Error Message Decoder

The error messages given by the TypeScript compiler can be very hard to understand. To help with this, try this awesome VS Code Total Typescript plugin. You won't regret it!

Featured image by Kimberly Farmer via Unsplash

So What is a Design Technologist, Anyways?

Sheelah Brennan — Mon, 28 Nov 2022 04:30:03 +0000

As you've browsed the tech job boards this year, you may have started noticing postings for a role called "design technologist." So what exactly is a design technologist, anyways?

After spending the last ~9 months working as a design technologist, I wanted to share some insights on this role, and why it may or may not be a great fit for you.

Core Focus

The core focus of a design technologist role is usually to serve as a liason (or "glue", if you like analogies) between design and engineering teams. Since designers and engineers, even those in front-end engineering roles, often come from very different backgrounds and have different skill sets, there is often a gap in understanding between these two roles or teams. This is where design technologists come in.

Design technologists often have a hybrid skillset of both design and front-end engineering. However, because the UX/UI design and front-end engineering fields are so broad even on their own, it's very common that a design technologist will be stronger in either design or front-end engineering. For example, I have taken a bunch of design courses and have done some UI design work, but I'm definitely stronger on the front-end engineering side of things.

Common Responsibilities

Design technologists commonly serve as key partners to a design team, empowering them to do their best work. What can this look like in practice? Here's some common responsibilities for a design technologist.

Design System Champion And/Or Contributor

Design technologists often are found at companies that have a design system and design system component library. They may serve as a champion for the design system component library, helping teams to adopt the library in their own projects or even contributing new components to the component library. They also may help designers ramp up on the library and contribute additional design system documentation.

Design Tools Developer

Designers often have workflows and processes that could benefit from automation. That's where design technologists can come in. Design technologists often build tools to support designers, such as custom Figma plugins or entire web applications for internal use.

Over the past 9 months, this category has been where the majority of my time has been spent.

Prototyper

Designers can easily create designs for a new product or new workflow for an existing product, but how do they know if its the right design and something that's feasible to build for the web? Design technologists can work in a prototyping capacity, collaborating closely with designers to build out a new UI feature in code. The goals of the prototype can vary quite a bit! A prototype can be created to help designers visualize what a design will look like on the web, allowing them to explore multiple ideas. Prototypes may also get created to help make sure that a UI feature will be performant, intuitive, and accessible, or even to serve as a UI to use for user testing by UX researchers. The fidelity of the prototype also varies quite a bit, depending on how it will be used.

In my time as a design technologist, this category has been another one that I've spent time in this year, and it's my personal favorite 🙂

Accessibility Specialist

Design technologists can also have a specialty in a certain area, such as accessibility. For example, a design technologist well-versed in WCAG standards may help designers to design with all accessibility concerns in mind, or they may help front-end engineers to built fully accessible UI components.

Is the Design Technologist Role for You?

If you like design and front-end engineering, and you enjoy collaborating with designers and engineering teams, the design technologist role might be a great fit for you. It's a great role for "unicorns", often called hybrid designer/developers or UX engineers. In addition, it's a great fit for front-end engineers who want to try something a bit different from design system engineering work, and who enjoy working on a couple of different things at once, instead of having a single focus.

If you prefer primarily interacting with engineering teams, are focused on having a specific engineering job title, or concerned about not being considered a "real" engineer in what would be a hybrid role, a design technologist role may not be a great choice for you.

For more food for thought, check out the design technologist club's description of the role.

That's all for now! I hope this provided some insight into the design technologist role. If you have thoughts or questions on this role, drop a note in the comments.

Image by Jess Bailey via Unsplash

Frontend Engineer vs Design Systems Engineer

Sheelah Brennan — Fri, 10 Sep 2021 20:52:51 +0000

You've probably heard about design systems and seen job posts for design systems engineers or for UX engineers, who often work on a design system.

First of all, what is a design systems engineer? It's an engineer working on a design system, who may have some interest or experience in design fundamentals like colors and typography. A design system is a set of reusable components along with usage guidelines which can be used to create all kinds of new layouts and pages. It can really speed design and development for product work, since designers and engineers will use the components as building blocks instead of starting from scratch.

Is this type of role for you? Today I'm going to highlight some of the differences between a frontend engineering role and a design systems engineering role.

Collaboration with designers is extra important

In a design systems engineering role, you'll spend a lot of time collaborating with designers. You'll review component designs and and work together with designers during new component builds. You may even prototype new component UIs during the development phase in order to get early feedback from design systems designers. Communication skills are important!

More planning before component development

In product work, frontend engineers often move straight into the development phase when building a new feature. This is quite different from design system engineering, when there is normally a lot of planning that takes place before any code is written.

During this planning phase, design system engineers will review the final component designs and decide on the best API to use for the component. The goal is to help ensure that the final component is easy for other frontend engineers to use, in addition to having all the needed functionality.

Other engineers are your customers

As an engineer on a design systems team, your customers are the consumers of your system -- other engineers. This contrasts with being an engineer on a product team, where your customers may be external users of the product. Being able to talk often with engineers using your design system in order to get their feedback is really important. Being in touch with your customers also helps to gauge any pain points that design systems users are encountering.

Testing is really important

Component tests are always good to have in place, but in a design system, where possibly hundreds or even thousands of engineers will be using your system, tests are critical. Having tooling in place for accessibility testing and UX regression testing also is very valuable for design systems teams.

Accessibility is a must-have

Accessibility is unfortunately often an afterthought when working as a frontend engineer on a product team. When working on a design system, building accessible components is a core foundation of the role. Most US-based design systems aim to follow WCGAG 2.1 Guidelines for components. As a new design systems engineer, you'll be ramping up on these guidelines and learn how to best implement them.

Documentation is core to the system

Because the success of a design system is measured based on adoption, documentation on components and how to use them is key. Teams often use Storybook or a similar tool to allow customers to see and interact with components. Documenting usage patterns for each component, along with any guidelines for ensuring accessibility, is also critical.

Support is part of the role

As a design systems engineer, helping engineers adopt and use the design system is a big part of the role. Engineers may discover component bugs that need to be addressed, or they may have ideas for ways to make components easier to use. Fielding questions on component usage and fixing component bugs are common activities for design systems team members.

Infrastructure and version management comes to the forefront

On a design systems team, engineers often work in a monorepo, where different aspects of the system, like components and icons, may be broken up into different npm packages with independent versioning. This makes adopting the system easier for users, as they can upgrade to new package versions on their own time frame. This also makes managing changes over time easier for design systems engineer.

Experience or interest in semantic versioning standards, tools like lerna, which is often use for automating package versioning, and tools for continuous integration is really valuable on a design systems team.

I hope this helps with anyone considering moving into design systems engineering! It's definitely a growing specialty. Do you have more thoughts on the differences between frontend engineering and design systems engineering? Leave a comment!

Image by David Pisnoy via Unsplash

Five Tips for Effective Github Pull Request Descriptions

Sheelah Brennan — Wed, 01 Sep 2021 14:47:32 +0000

A big part of collaborating with other developers on a project, whether it be at work or on an open source project, is creating and reviewing Github pull requests. Today I'm sharing five tips for creating effective Github pull request descriptions. These tips will help you ensure your pull request is easy for reviewers to understand and thoroughly review. They will also help your pull request to get reviewed more quickly, by being explicit about what was changed and how to QA it.

Let's dive in to sections worth including in a pull request description.

High-Level Details on What Was Changed

Providing a concise bulleted list of what was changed is a great first step. Linking to a ticket or open Github issue is great, but let's be honest -- who wants to have to put the pieces together on their own? Make it easy for your reviewer by noting the key changes included in your pull request.

If you are implementing something that was scoped out in an engineering proposal, link to that document. Also, if you are implementing a UI feature, link to the designs.

Open Questions

You may have some lingering questions relating to the changes that you had to make. Why not call those out in your pull request description, if you didn't already have a discussion about them beforehand? In addition, if you're looking for feedback on specific changes that you made, call those out as well so that your reviewer can provide input.

How to Test

This is an important one that is often missed. Make it easy for your reviewer by providing explicit steps on how to test your changes. It's often nice to use a checklist format, which is easy to do with markdown, so that your reviewer can even go through the list and check off completed steps. For example:

- [] Start dev server at http://localhost:3000/about-us
- [] Confirm that the navigation menu's open/close feature now works on mobile
- [] Confirm that the navigation menu still works the same on tablet and desktop widths
- [] Check that tests added are complete

If your pull request includes the addition of a new library, note that in the steps so that your reviewer knows to install it first.

Screenshots

For UI changes, include one or more screenshots of the completed feature. If you fixed a bug, it's nice to include a "before" and "after" screenshot so that your reviewer can see exactly what you fixed.

Notes

If you have any other notes to add for your reviewer, such as specific aspects of the work that are out of scope or things to address later, this is the section to note them.

That's all! One final tip: once you're landed on the appropriate format for your teams' pull request descriptions, you can create a pull request template for your Github repository, so that all pull requests will get those sections included by default.

If you have more ideas for effective Github pull request descriptions, please share in the comments :).

Image by Glenn Carstens-Peters via Unsplash

React Testing Library: Tips and Tricks

Sheelah Brennan — Fri, 20 Aug 2021 19:37:14 +0000

Update (9/6/22): This article has been updated to stay in line with current React Testing Library best practices.

Testing front-end web applications has gotten a lot easier! But that doesn't mean it doesn't involve some ramp-up on tooling. In this article I'll provide some tips and tricks for getting started and ramping up quickly with React Testing Library, the most popular tool for React component testing today.

Getting Started

The docs are great, so if you're new to the library, you should definitely take a quick look there.

Deciding on Queries to Use

In order to write tests, you'll use the library to render your component and then write one or more queries to find certain DOM elements on the page. The question you'll have is which query to use! There are a lot of them. The best practice here is to query for actual visible elements in the DOM, such as querying for buttons with certain text, form inputs, images with certain alt text, etc.

Here's an example of querying for a button with "Read More" text:

const button = screen.getByRole("button", { name: /read more/i })

These queries can be used to look for certain text elements too! Here's an example of querying for a h1 heading:

const button = screen.getByRole("heading", { level: "h1" })

Role-based Queries

findByRole and getByRole queries are the ones that you will likely be reaching for the most, and any element listed in this roles list can be queried for. The bonus of using these roles-based queries is that you're helping to ensure that your components are accessible and available for assistive technology like screen readers!

For the full list of role-based queries available, see the React testing library docs.

findBy* vs getBy* Queries

So what's the difference between findBy* and getBy* queries? For any test that involves asynchronous behavior, like checking that a message is rendered after a user clicks on a submit button, findBy* queries are the ones to reach for. For tests that don't involve asynchronous behavior, like checking that a heading with certain text is shown when component is rendered, getBy* queries work great.

Note that with findBy* queries, you'll use await to wait for the element you're querying for to be found:

const confirmation = await screen.findByRole("heading", { level: "h3" })

You can think of findBy* queries as a shortcut for running a getBy* query followed by an await waitFor() call. The following two approaches would accomplish the same thing but you'll see that using findBy* is more concise:

// Using findByRole() to wait for a toast to appear
const toast = await screen.findByRole("heading", { level: "h3", name: 'Confirmed!' })
expect(toast).toBeDefined() // This is optional since the line above will fail if the toast isn't found

// Using getByRole() to wait for a toast to appear
await waitFor(() => {
  const toast = screen.getByRole("heading", { level: "h3", name: 'Confirmed!' })
  expect(toast).toBeDefined()
}

getBy* vs queryBy* Queries

You'll also notice that there are both getBy* queries and queryBy* queries. The main difference is that getBy* and findBy* queries return the actual DOM element matched and throw an error if the element is not found. queryBy* queries are similar in that they also return the actual DOM node matched, but they return null if no match was found. How do you know which to use? Reach for getBy* and findBy* queries unless you want to test for an element that may not be present. In that case you'll want to use queryBy* queries. An example of a good use case for queryBy* queries is when you want to test that an element is not present.

Querying for Single and Multiple Items

With React Testing Library, you'll notice that there are both getAllBy* and getBy* queries. When you're just searching for a single element, you'll want to use a getBy* or findBy* query. For cases where you want to query for multiple items, such as an unordered list of elements, you'll want to use a getAllBy* or findAllBy* query.

Debugging Errors or Missing Elements

Sometimes your tests will fail unexpectedly and you'll wonder what is being rendered. Don't worry -- there's a utility for that! Use screen.debug() inside your test and you'll then get a full printout of what was rendered. If your component renders a lot of of content and screen.debug() output is getting cut off, specify a longer max output length by doing something like screen.debug(undefined, 50000) to print 50000 lines. Alternatively, you can print the output for a given DOM element that you queried for with screen.debug(myElement, 500000).

Testing Hidden Elements

Sometimes you'll want to test a component that is hidden. For example, an element might have aria-hidden=true on it if it has surrounding label text. In this case, if you query for the element, you'll find that you don't get any matching element found.

The fix is to include { hidden: true } in your query. Then the library will also include hidden elements in query results.

Example:

const buttons = screen.getByRole("button", { hidden: true })

See the documentation on this for more information.

Testing Click Behaviors

For tests that depend on a user interaction, like a button click, to happen, you'll want to simulate that interaction in your test first. To do this, you can use the userEvent library:

const user = userEvent.setup()

const submitButton = screen.getByRole("button", { name: /sign up/i })
await user.click(submitButton)

const toast = await screen.findByRole("heading", {
  level: "h3",
  name: "Confirmed",
})
expect(toast).toBeDefined()

There is also an older utility called fireEvent that you can use, but using userEvent is preferred since it more closely simulates an actual user interaction.

More Test Assertion Options

To have access to a wider array of Jest assertion options to use in your tests, I highly recommend installing the jest-dom library. It works great with React testing library and lets you write some useful assertions without extra legwork. For example, you can test that a link element has a certain href attribute like:

const link = screen.getByRole("link", { name: "Get Started" })
expect(link).toHaveAttribute("href", "https://example.com")

Query Helpers and Tools

To help with finding an appropriate query, there is a useful Chrome extension that you can try that's called Testing Playground.

To help ensure that you're following all best practices for the library, there's also an ESLint plugin that's worth installing in your project.

That's all! I'd love to hear what your favorite React Testing Library tip is. Feel free to share in the comments or find me on Twitter.

Featured image by Jörg Angeli via Unsplash

Debugging CSS: Some Tips and Tricks

Sheelah Brennan — Thu, 24 Dec 2020 04:27:37 +0000

We've all been there. You're working on a new piece of functionality and have the markup done. Now it's time to work on the styles. No problem, right? You add the base styles and when the page reloads with the changes applied, suddenly the layout is broken. You sigh, knowing that it might be a long day as you're up against a tight deadline.

CSS can be tricky at times. In this article I'll provide some strategies I've used for troubleshooting CSS when things are not working as expected. Hopefully one of these can help get you out of frustration mode and back into "getting things done" mode 🙂.

Generic Layout Issues

One of my most commonly used strategies when facing any kind of layout issue is to add an outline around a parent element's children. This lets me see whether the children are where I thought they would be and whether they have the expected dimensions. You can use a rule like this:

.element {
  outline: 1px solid red;
}

If the layout issue is more complex and you need to debug the layout of the entire page, you can add outlines for every element on the page using different colors. This is a lot of lines to look at, but it can be helpful. In your browser developer tools, open your console tab and type this JavaScript snippet:

;[].forEach.call($$("*"), function(a) {
  a.style.outline = "1px solid #" + (~~(Math.random() * (1 << 24))).toString(16)
})

An alternative strategy for debugging the layout of the entire page is to place a background color on all elements:

*:nth-child(n) {
  background-color: rgba(255, 0, 0, 0.2);
}

CSS Grid or Flexbox Issues

In addition to using the generic layout issue strategies above, I like to take advantage of Firefox or Chrome's developer tools to help with these issues. For example, in Firefox's developer tools, you can use the layout tab to inspect a grid or flex parent. If you inspect a grid parent, you'll then see lines added, allowing you to visualize the grid. Doing this can help you also discover any bugs caused by adding an extra wrapper div or element between your parent and child elements which can break your grid or flex layout.

Clicking on the grid waffle icon on the left automatically selects it on the right.

Page Overflow Issues

For debugging an unexpected horizontal scrollbar, my favorite strategy is outlined in this CSS Tricks article.

Browser or Mobile-Only Bugs

Could what you're seeing be a browser-specific bug? It's worth testing the page out on other browsers and on a mobile device (especially on Safari mobile!) if you can. If you're only seeing the issue on one browser, then you can narrow down the source of the bug.

For example, I've regularly ran into flexbox issues that are Safari-specific. I've discovered these by testing in other browsers and confirming that the issue only shows up in Safari. A good reference of Flexbox browser-specific bugs is Philip Walton's flexbugs repo.

I've also ran into issues in the past with how mobile Safari handles vh units, confirmed by testing on Android and seeing that the issue wasn't appearing there.

Typos

Could it just be a CSS typo? It happens to the best of us. Even the smallest typo can cause your CSS rule not to get applied. A useful strategy here is to use your browser developer tools to inspect the element of the page where you're seeing the bug. See what CSS is getting applied. If you see your rule there and it's crossed out, it's not getting applied.

A preventative strategy here is to use a code editor that includes syntax highlighting for CSS, like VS Code. This won't catch every single possible typo, but it will call out things like invalid property names and it will make invalid property values easier to catch.

Markup Issues

Another source of bugs is typos in HTML markup. For example, you might have forgotten to apply your CSS class to the desired element. Therefore the CSS rules for that class are not going to get applied. As discussed above, you can use your browser developer tools to inspect the element's markup and then verify that the expected class is applied to the element.

Animation and Transition Issues

For issues with animations and transitions, my first strategy is always to greatly slow down the timing of the animation or transition. That way I can watch as it runs, and it makes it easier to see both the start, end, and intermediate states.

For animations, I also like to verify that I've specified the animation shorthand properties for time values in the right order (the first one found is set to the animation duration and the second one found is set to the animation delay).

If the animation rule is crossed out, you'll know that there's likely a typo:

Another issue I've hit in the past is typos in animation keyframes which then cause the animation not to get applied. To verify the keyframes are set as expected, you can use your browser's developer tools. If you don't see the keyframes showing when inspecting the styles of the animated element like shown below, that's probably your issue:

For animation debugging, I also like this CSS Tricks article by Sarah Drasner.

Hope this helps someone stuck in that "oh no, what's wrong with my CSS??!" moment.

Featured image by Markus Winkler via Unsplash.

The Pros and Cons of Headless Shopify

Sheelah Brennan — Wed, 06 May 2020 02:51:03 +0000

Shopify has become one of the big players in ecommerce, and the release of their Storefront API a few years ago opened the doors to building completely custom Shopify-based ecommerce experiences.

There are pros and cons to consider when deciding whether to go with a headless Shopify ecommerce solution or a more traditional Shopify-hosted solution, and in this post I'll provide a rundown of my findings after building a React-based headless Shopify site in a recent project.

Overview of Headless Shopify

In a headless Shopify approach, you can build your own site in whatever language and framework you want and allow customers to add products to their cart, a custom cart that you've built, while still on your site. Typically the store is set up so that once the customer enters the checkout flow (typically by hitting some kind of "checkout" button), the customer is taken to your Shopify store to complete the purchase.

The simplest way to build an site using this approach is to use one of the Shopify SDKs. For JavaScript-based applications, you can use the Shopify Buy SDK. There are also SDKs for mobile. The Buy SDK uses the Shopify Storefront API under the hood and provides easy-to-use functionality for things like creating a customer checkout or fetching Shopify product data.

Note that the Buy SDK does not offer all of the functionality of the Storefront API. In order to access certain fields, you'll need to build a custom Storefront API GraphQL query. To do this, you'll need to use the Buy SDK's unoptimized build which is quite a bit larger. For a single page app rendered client-side, this will impact page weight and overall page load times :(.

Pros of Headless Shopify

Freedom - Languages, Frameworks, and UI

Being able to build a completely custom site and shopping experience is pretty compelling. While Shopify's cart and checkout experience has most likely gone through rigorous UI/UX design reviews, A/B testing, and lots of iterations (meaning it should be effective at leading to conversions), having the option to work closely with a UI/UX interaction designer to build a completely custom cart is a really nice option. While ecommerce is at the end of the day about sales, only you and your team know what's unique about your company and your customers. Perhaps having your own custom cart would lead to even more sales.

The other advantage is in terms of tech stack. Not being tied to Shopify's templating language, Liquid, means you could your site in whatever language and using whatever framework you want, as long as it could talk to Shopify's Storefront API.

If you're into Gatsby, you can use their Shopify plugin and hit the ground running.

GraphQL API

If you end up needing to use the Storefront API directly, you'll need to use GraphQL. A lot of developers are already familiar with (or are interested in building with) GraphQL-based APIs. This makes it easy to get started with if you have any level of experience with GraphQL.

Cons of Headless Shopify

Non-Standard Approach Means You're Your own Support

If something goes wrong, Shopify support likely won't be of much help. Plan on being able to and adept at troubleshooting your application on your own.

Roll-Your-Own Functionality

If you cringe at the thought of building your own shopping cart, your own product options picker, or building functionality to check whether a customer checkout is stale, building a headless Shopify solution may not be the way to go. No matter what kind of site you're building, plan on at some point building some functionality that duplicates features that Shopify has out of the box. That's the tradeoff for the freedom of a headless Shopify site.

Another thing you'll need to build in is support for handling any errors that the Shopify API may return, just like when dealing with any kind of API. You don't want to lose sales because of some kind of error.

Cumbersome Product Metadata

If you need to store metadata at the product or product variant level, you'll need to use Shopify metafields. For example, you could use a metafield to store a shorter version of a product's name that's displayed in a shopping cart. These can become pretty cumbersome from a data entry standpoint if you have a lot of them. And you must remember to whitelist all metafields in order to make them available to Shopify's API.

GraphQL API

The GraphQL API can be considered a con for developers who are more used to JSON-based APIs. However, the Storefront API documentation is decent and there is intro to GraphQL documentation as well. There is also a Shopify Storefront API GraphiQL explorer tool that you can use to test out GraphQL queries on Shopify's demo store.

API Limits

There are Storefront API rate limits to take into account when building a headless Shopify site. Luckily, these limits do take a user's IP address into account, so surges in traffic (Ex. due to a product launch) shouldn't put your app at risk of hitting up against these limits. Note that if you're on Shopify Plus, the limits are higher.

Less Availability of Add-On Apps

If you're used to being able to install add-ons to add new functionality (like you can with Shopify and with CMSs like WordPress), you'll be mostly out of luck. With headless Shopify, add-ons that you use on the backend side (within Shopify's admin interface, for example), will usually work fine. But add-ons that rely on you having a Shopify theme will not.

Less-Than-Stellar Image Tooling

If you're used to frameworks like Gatsby that handle image optimization for you, you're going to be more DIY under headless Shopify. There are some image helpers in Shopify's Github repo that can help you crop images, but there is nothing available that does image transformations for you like Cloudinary or Imgix. You will have access to Shopify's CDN for images, but other than that you're on your own. What you can do is look for other image tools that work on top of Shopify.

While it's likely not officially supported or endosed by Shopify, Imgix does work as a layer on top of Shopify. That would allow you to do things like image cropping, filters, etc. The only caveat is that if you want to replace an image in Shopify you'll need to make sure to rename the file before re-uploading it. The reason is that Shopify doesn't currently have a way to let you purge their CDN cache for a single image URL like Imgix does. Maybe someday! I put in a feature request :-).

Conclusion

There's a lot to consider on both sides of this, and I hope this helps someone out there who's looking into Headless Shopify. Have you built a headless Shopify site? I'd love to hear what you built it with and how it worked out.

Featured image by Lauren Fleischmann via Unsplash

Add Visual Interest to Your Website/Web App

Sheelah Brennan — Tue, 17 Sep 2019 18:18:13 +0000

My Skillshare course on making your website/web app stand out (using HTML, CSS, and SVG) went live today & I'm launching it as a free course! You'll just need a free Skillshare & CodePen account.

https://skl.sh/2kr2xrq