Never worry again about your GraphQL API breaking changes

Justine — Thu, 14 Mar 2024 09:38:17 +0000

Problem

We deploy our API and our frontend at the same time. It means our new frontend contains the necessary changes to match the new API ⇒ great ✅.
🚨 But a user can keep their browser opened with the previous frontend code version, as a consequence the previous frontend version calls the new API, and if there are breaking changes in the modifications ⇒ it breaks 💥.

Our previous solution

🚨 Spoiler: not the one we recommend now, scroll down to 'Our new solution' if you want to go straight to the point

For a long time, here is how we have handled our breaking changes:

deprecate the concerned field in the API instead of deleting/modifying it
add the new one
merge the pull request
wait for 7 days: totally arbitrary timing, we considered that after 1 week, all our users would have refreshed their frontend
remove the deprecated field

Pros and cons:

🟢 no impact at all for most users
🔴 not efficient for developers (2 pull requests, with a week delay between it)
🔴 not perfect: the 7 days delay is arbitrary, some users can still face a bug
🔴 we often forgot to clean the deprecated field: legacy code remaining in the codebase

We wanted to improve that situation.
Here are the solutions we considered:

❌ API versioning: too costly to put in place versus the gain + GraphQL does not recommend it (see best practices)
❌ Fields versioning: forces you to maintain legacy code in the backend
✅ Automatically refresh the user frontend when they face an API breaking change: this is the solution we chose and I will explain below how we implemented it.

Our new solution

👉 Automatically refresh the user frontend when they face an API breaking change

How to

In your ApolloClient, if you do not have one already, you will need to add an errorLink
Build this errorLink thanks to the given onError link furnished by @apollo in @apollo/client/link/error:

import { onError } from '@apollo/client/link/error';

const errorLink = onError(({ graphQLErrors, operation }) => {
  if (graphQLErrors) {
    /* We are targeting here GraphQL API breaking changes 
    * due to schema changes which correspond to code 
    * 'GRAPHQL_VALIDATION_FAILED'
    */ 
    const validationErrors = graphQLErrors.filter(
      ({ extensions: { code } }) => 
          code === 'GRAPHQL_VALIDATION_FAILED',
    );

    if (validationErrors.length > 0) {
      const isMutation = operation.query.definitions
        .filter(
          (def: DefinitionNode): def is OperationDefinitionNode =>
            def.kind === 'OperationDefinition',
        )
        .some(
          ({ operation }) => operation === 'mutation',
        );

      if (isMutation) {
        /* In case of a mutation being affected 
        * by the breaking change,
        * as the data they entered will not be saved
        * we decided to display a pop up to the user 
        * so they can collect their data before losing it 
        * to avoid frustration, if it was a long text for example.
        */ 
        if (
          !window.confirm(
            "Sorry, the page needs to refresh to work properly.\n\n** You'll need to enter your latest data again **\nNote that you can:\n1. Click on 'Cancel'\n2. Copy your data\n3. Refresh the page\n4. Paste your data back\n\nSorry again for the inconvenience.\nThis will lead to improvements for you down the road.",
          )
        ) {
            return;
          }
        }

        window.location.reload();
      }
    }
  });

Pros and cons:

🟢 no mental load for the developers (API fields can be modified/deleted with peace of mind)
🟢 the legacy code is removed right away
🟠 small impact on user experience: users can face an auto reload or a pop up in the case of a mutation

One last thing

Do not forget to stop your error alerting on 'Validation errors' if you had some, because you won't need it anymore.

If you have any feedback, please feel free to comment! Thanks 🙏

Building my first browser extension: should I use a framework?

Justine — Wed, 22 Nov 2023 17:44:41 +0000

A few months ago, the Product team I work with came up with this new project in mind: let’s create a Browser extension to help our users.
All the tech team got excited about it as it was new to all of us.
But then, during our first technical refinement, one of the developers raised a very good question: should we use a framework or not?

So here is this article, to help you with this question if you face the same situation.

PS: This article will focus solely on Chrome, as it is currently the only browser we have experience with.

⚠️ Spoiler ⚠️

We decided to use a framework!

We chose Plasmo because the other options available were not suitable for us:
— CRXJS: Chrome specific, we had the ambition to deploy to other browsers in the future;
— Bedframe: early access only.

In this article, I will compare building an extension with Plasmo and without it.
Please feel free to compare the same bullet points on Bedframe and CRXJS, and share them in the comments.

Here is why we chose to use a framework:

Better developer experience: live reload

Without Plasmo framework:
With Plasmo framework:

With Plasmo, you have got live reloading.
Whereas without it, you need to close and reopen the extension to see your changes.

Easier QA validation

Chrome extensions are subject to a review to be published. It can take a few days to be reviewed (depending on the content of your extension).
But then how do you do QA?

Here are the 2 ways:
Without Plasmo framework:
— the developer bundles the extension => got a zip file
— the developer sends it to QA
— QA manually uploads the new file in Chrome extension developer mode
✅ Free
🚨 Error-prone and time-consuming for both dev and QA teams

With Plasmo framework:
Plasmo proposes a service (Plasmo Itero) to have a staging environment for your extension.
Process: at merge, a CD job is automatically run, it builds and deploys the browser extension on a private store. QA testers install the extension once, and then just need to update the extension on chrome://extensions/ to get the last update.
✅ Fully automated process
🟠 Paid service: $65/month

Automatic permissions management

One of our learning on Chrome publication is “The more permissions your browser extension asks, the more time the Google review will take”
(and from our experience it can be quite long, for us it was often 1 week)

As a consequence, you do not want to mess up by asking for permissions that are not required.
It is yet another Plasmo framework benefit: as the manifest.json file (the file containing all your browser extension configuration, permissions included) is generated by Plasmo, permissions asked by your extension reflect the permissions actually needed by the codebase, nothing more.

One codebase for all browsers

One promise of Plasmo is: “you can build an extension once and easily target it to multiple browsers”.
We did not experience it, so I can not give feedback on that point. But that was an additional point that made us choose to use Plasmo.

Easier communication with external services

Finally, you will probably need your extension to communicate with external services (your API, external APIs, etc).
If you call the external API naively from the current page, chances are you will run into a CORS issue: your request origin is the current page and your API is expecting another origin. So to bypass this, you can use a background service worker to proxy the communication with your API.

Without framework:
With Plasmo:

Advantages here:

Plasmo defines listeners and does the cleanup for you.
Again, Plasmo‘s code is not Chrome specific
Code organisation: your messages are split into different files, and manifest.json background key is generated automatically for you
Message name is type-safe, which can save you not pleasant debugging time:

Before I leave you, one advice:

I advise you to try a first publication to Chrome Web Store as soon as possible (you will be able to publish it as Private as a first step).
It will allow you to:

See the list of elements required by the store (description, category, images with precise sizes, etc) and ask the right team in your company to give you those elements on time for your expected release in production.
Get a sense of the time a publication review can take.

If you have any questions, please comment on this article, I hope we can have an answer to help you with our experience of building a browser extension.

Forem: Justine

Never worry again about your GraphQL API breaking changes

Problem

Our previous solution

Pros and cons:

Our new solution

How to

Pros and cons:

One last thing

Building my first browser extension: should I use a framework?

⚠️ Spoiler ⚠️

Better developer experience: live reload

Easier QA validation

Automatic permissions management

One codebase for all browsers

Easier communication with external services

Before I leave you, one advice: