DEV Community: Sami Jaber

Stop polyfilling fetch in your npm package

Sami Jaber — Tue, 10 Jan 2023 18:09:16 +0000

tl;dr: Let your users handle it. See https://github.com/BuilderIO/this-package-uses-fetch/

I’ve maintained a handful of JavaScript SDKs over the years. And for each one, the question of how exactly to provide support for fetch in a Node environment inevitably comes up. In fact, we just recently had to resolve some issues concerning this in our Builder.io SDKs.

Given the ever-changing landscape of JavaScript environments (seriously: I’ve been a web dev since 2017…do things ever slow down?), I figured it’s worth sharing my perspective on the matter.

Let’s set the scene

You’re putting together an npm library that involves fetching data. There are many popular packages that can help you (axios, superagent, etc.) but in the spirit of not shipping bulky/redundant JS code to the browser, and the progress which browsers and JavaScript has made over the years, you try to use the platform whenever possible.

And when it comes to fetching data, there are 2 standards provided by browsers:

XMLHttpRequest (a.k.a. Ajax)
Fetch

We won’t dive too deep into the differences between these two, as this post is focused on how to use fetch, not how to decide between fetch and XMLHttpRequest! So we’ll assume you went with fetch here.

Browser support

So you’ve chosen and started using fetch in your code, making calls like fetch('https://example.com'). Great! This works in most modern browsers:

Source: https://caniuse.com/fetch

But as the above chart shows, around ~4% of internet users today might still be relying on browsers that do not support fetch. What can you do for them?

Nothing

Before jumping to conclusions, make sure that you actually have users on non-fetch environments (e.g. by importing your analytics into caniuse and looking at the browser usage of your users). It might be the case that you can actually get away with not doing anything at all!

Polyfills!

If it turns out that you do have users on older browsers, then the way to fix this is to provide a fetch polyfill to support them:

A polyfill is a piece of code (usually JavaScript on the Web) used to provide modern functionality on older environments that do not natively support it.

In this case, Github offers a great fetch polyfill for browsers: https://github.com/github/fetch

Node support

Adding a browser polyfill is great, but JavaScript code also runs on the server, and your new npm library is no different! Node.js is, by far, the most popular JavaScript server runtime, but it did not have fetch support until v18 (released in April 2022).

So for all versions of Node.js ≤17, you’ll need a Node fetch polyfill, the most popular of which is node-fetch: https://github.com/node-fetch/node-fetch

Non-Node JS server runtimes

A somewhat recent development is the explosion of new JavaScript server runtimes. Here are some of them, along with their Node support:

Deno: supports Fetch out-of-the-box
Bun: support Fetch out-of-the-box
Cloudflare Workers: supports Fetch out-of-the-box
Netlify Edge Functions: built on top of Deno

As you can see, many of the newer runtimes provide Fetch support from the get-go.

Who should actually polyfill it?

What would happen if you, the author, added these polyfills to your code?

You’d start by installing node-fetch as a package in dependencies, maybe include the github polyfill for browsers too, and finally include some logic that toggles between server & browser polyfills. It might look something like the following:

export async function getFetch() {
  const globalFetch = globalThis.fetch;

  const isNodeEnv = typeof global !== 'undefined';

  // do nothing if `fetch` exists
  if (globalFetch) {
        return globalFetch
    } else if (isNodeEnv) {
        // get node polyfill
    return import('node-fetch').then((d) => d.default));
  } else {
        // get browser polyfill
        return import('whatwg-fetch').then((d) => d.fetch));
  }
}

// use it like this
const fetch = await getFetch()
fetch('https://example.com')

The nice thing about implementing this toggle is that, if implemented just right, your users won’t have to worry about a thing: they can npm install your-cool-library and start using it with no extra steps.

However, this approach runs into a host of issues & dilemmas:

node-fetch is now a hard dependency in your app. Since it depends on certain Node.js APIs, it might cause issues if it (accidentally or otherwise) gets imported in other server runtimes like Cloudflare Workers (which do not support these)
Both you & your users will have to pay very close attention to how dynamic imports are bundled, to make sure your polyfill imports don’t end up in the wrong environment.
You will have to come back to this logic and tweak it as different JS runtimes show up, requiring different methods of checking which environment you’re in.
if your library’s users already installed another version of these polyfills (e.g. node-fetch) for another purpose, you’d be forcing them to needlessly have 2 versions of the same package.
(Bonus): the delightful conflict between ESM and CommonJS module standards has a big consequence here: node-fetch v3 is ESM-only and does not work in CommonJS projects. You will need to either stay with v2 to support both, or choose for your library to be ESM-only as well.

isomorphic-fetch

You can get around some of the above issues using a library called isomorphic-fetch, but not all of them. It also hasn’t been updated since 2015, and is locked on v2.x of node-fetch (whereas v3 has been out for some time now)

Solution

As much as we’d prefer the “we got you covered” approach of implementing polyfills on behalf of our users, it is too painful and brittle to do it this way.

Instead, as a general rule, I argue that you (a proud npm package author) should not include polyfills in your published code, or dependency tree. You should leave it up to your users to do as they see fit, based on their needs & environments. This guarantees that:

no one receives unnecessary code
no future JS runtime has conflicts with how your code handles fetch
no one ends up with duplicate versions of a given polyfill
less code for you to maintain
since most apps and packages do data fetching of some kind, end-users probably don’t need to do any extra work (and can reuse whatever polyfill they’ve already setup)
you can go back to using the global fetch() instead of importing a wrapped getFetch() everywhere.

Documentation

With Node v16 reaching end-of-life in Fall 2023, we are quickly approaching a time where polyfilling fetch is far less important. But we are probably still years away from most Node users updating to v18, so we still need to provide clear documentation on how to polyfill fetch. This is why we created this github README: https://github.com/BuilderIO/this-package-uses-fetch

It includes a summary of the above, with clear actionable steps for each environment. The goal is to avoid the need for all package authors to explain the same thing over and over again. In fact, we just started using it ourselves in our SDK code: https://github.com/BuilderIO/builder/pull/1661

We invite other folks who use fetch to link to this document in their README’s, and contribute any ideas they have!

Implementing CSS style inheritance in React Native

Sami Jaber — Thu, 05 Jan 2023 15:21:12 +0000

Sami Jaber is a Software Engineer at Builder.io, and the tech lead on the SDKs.

Recently, one of our users expanded their usage of Builder from their React app to their React Native app. They soon reported a rather troublesome bug: applying text styles to a button’s text did not properly work in React Native.

In this piece, we’re going to dive into this bug, and how the solution involves re-creating some of CSS’s cascading mechanisms for React Native.

The issue

Let’s assume our user is trying to render a button with a blue background and white text that says “Click Me!”.

In the React SDK, the Button component looks like this:

export default function Button(props) {
  return <button {...props.attributes}>{props.text}</button>;
}

Given the appropriate props, this final HTML will look something like:

<button style="color: 'white'; background-color: 'blue'">Click Me!</button>

PS: styles actually end up in CSS classes and not as inlined style attributes. I am writing them as such only to simplify the code examples.

In React Native, all text context must be wrapped in a Text component (kind of like a required span). Additionally, you must use View to represent layout elements (think of it as the div of React Native). So the same button looks something like:

import { View, Text } from 'react-native';

export default function Button(props) {
  return (
    <View {...props.attributes}>
      <Text>{props.text}</Text>
    </View>
  );
}

Which results in the following React Native output:

<View style={{ color: 'white', backgroundColor: 'blue' }}>
  <Text>Click Me!</Text>
</View>

The issue here is that the styles are all applied to the parent View. This wouldn’t be an issue on the web, but it is in React Native. Why? Because in React Native, elements do not inherit styles from their parents!

We could manually fix this particular Button component by selectively applying text styles to the inner Text component. But we want a generalizable solution: Builder allows users to drag’n’drop their own custom components into the Builder blocks, and vice versa. Additionally, if a parent block had text styles applied, those still wouldn’t cascade down to this Text component.

While the React Native team may have very good reasons to not implement this core CSS feature, it is something that we certainly need in the Builder.io SDKs, or else our users would have to manually style every single Text block manually. We want the React Native SDK experience to be as close as possible to that of our other web-based SDKs.

Solution Overview

To implement CSS inheritance, we need to first make sure we understand it. While MDN has a great in-depth article on CSS inheritance, here’s a brief explanation:

At a high-level, CSS inheritance works by climbing up the DOM tree until you find a parent node that provides a value for it. This of course also includes any values set by the node iself.

Things to note:

CSS inheritance only applies to certain styles, not all of them.
we will ignore !important (for now)

Before explaining our solution, it’s important to briefly explain how the Builder.io SDK works. Its architecture will dictate the solution we choose to implement.

SDK Architecture Overview

The Builder.io SDK exports a <RenderContent> component. The user will make an API call to Builder, fetch a JSON object that represents their content, and provide it to <RenderContent>. This component is then responsible for rendering the JSON content. Here’s an example of the JSON:

{
  "url": "/",
  "title": "Home",
  "blocks": [
    {
      "@type": "@builder.io/sdk:Element",
      "children": [
        {
          "@type": "@builder.io/sdk:Element",
          "component": {
            "name": "Text",
            "options": { "text": "Welcome to my homepage" }
          }
        },
        {
          "@type": "@builder.io/sdk:Element",
          "children": [
            {
              "@type": "@builder.io/sdk:Element",
              "component": {
                "name": "Button",
                "options": { "text": "About Page", "link": "/about" }
              },
              "styles": { "color": "white" }
            },
            {
              "@type": "@builder.io/sdk:Element",
              "component": {
                "name": "Button",
                "options": { "text": "Contact Us", "link": "/contact" }
              }
            }
          ]
        }
      ],
      "styles": { "font-size": "15px" }
    }
  ]
}

which would render HTML like this:

<div style="font-size: 15px;">
  <div>
    <span>Welcome to my homepage</span>
  </div>
  <div>
    <button style="color: white;">About Page</button>
    <button>Contact Us</button>
  </div>
</div>

Internally, <RenderContent> will loop over the content.children arrays and call <RenderBlock> for each item, until all of the content is rendered.

Given that we are traversing the JSON data top-down from the root down to the leaf nodes, how would we go about implementing style inheritance in React Native?

We decided to implement it in the following way:

write logic to extract inheritable text styles from styles object
store inheritable text styles in a inheritedTextStyles React.Context
merge new styles into this context whenever a node deeper in the tree updates some of those values
use a React.Context value to make the value available in leaf components
consume that context in wrapped Text component

Let’s get to work!

Step 1 - Inherit Text Styles

First, we need to grab all inheritable styles from the styles JSON object we receive from the Builder API. The API guarantees that these styles all map nicely to React Native (it therefore excludes things like CSS functions, and special units e.g. vw, vh, etc.).

Let’s implement extractInheritedTextStyles, which returns the subset of styles that we plan on passing down:

const TEXT_STYLE_KEYS = [
  'color',
  'whiteSpace',
  'direction',
  'hyphens',
  'overflowWrap',
];

/**
 * Check if the key represent a CSS style property that applies to text
 * See MDN docs for refrence of what properties apply to text.
 * https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Fundamentals#summary
 */
const isTextStyle = (key: string) => {
  return (
    TEXT_STYLE_KEYS.includes(key) ||
    key.startsWith('font') ||
    key.startsWith('text') ||
    key.startsWith('letter') ||
    key.startsWith('line') ||
    key.startsWith('word') ||
    key.startsWith('writing')
  );
};

/**
 * Extract inherited text styles that apply to text from a style object.
 */
export const extractInheritedTextStyles = (
  styles: Partial<CSSStyleDeclaration>
) => {
  const textStyles: Partial<CSSStyleDeclaration> = {};
  Object.entries(styles).forEach(([key, value]) => {
    if (isTextStyle(key)) {
      textStyles[key] = value;
    }
  });

  return textStyles;
};

Step 2 & 3 - Create & Merge Context

An empty default context will do the trick here:

// stylesContext.js
export default React.createContext({});

Now that we have the context and the extraction logic, we can pass styles down in the recursive RenderBlock calls. We also have to merge the new inherited text styles into the previous context passed from above. Here’s what that looks like:

import StylesContext from './stylesContext';

function RenderBlock(props) {
  const stylesContext = React.useContext(StylesContext);
  // ...the rest of `RenderBlock` code

  return (
    <StylesContext.Provider value={{
      ...stylesContext,
      extractInheritedTextStyles(props.content.styles)
    }}>
      {/* ...The rest of `RenderBlock` render code */}
      {props.content.children.map(childElements =>
        <RenderBlock key={childElements.id} content={childElements} />
      )}
    </StylesContext.Provider>
  )
}

Step 4 - Wrap Text

The last piece of this puzzle is to implement a component that wraps Text, and consumes these inherited text styles:

import { Text } from 'react-native';
import StylesContext from './stylesContext';

function BaseText({ style, ...otherProps }) {
  const stylesContext = React.useContext(StylesContext);
  return <Text {......otherProps} style={{ ...stylesContext, ...style }} />
}

And render this inside of our Button (and any other block that renders text):

import { View, Text } from 'react-native';
import { BaseText } from './BaseText';

export default function Button(props) {
  return (
    <View {...props.attributes}>
      <BaseText>{props.text}</BaseText>
    </View>
  );
}

And that’s it! Now, whenever we provide text styles that ought to be inherited, they are going to be stored in this styles context that makes its way down to BaseText.

Do you remember how I mentioned that Builder customers can render their own React Native components inside of Builder content? They can also make sure the <Text> within those components is styled just like the text in Builder by importing the <BaseText> component and using it in their own code! Since the component uses a React.Context to consume the styles, there is no additional work needed on the end-user’s part.

Bonus: `!important`

Implementing !important requires a bit more complexity, but is certainly doable. We’ll need to improve our logic to:

store whether a value is marked as !important or not:

export const extractInheritedTextStyles = (
  styles: Partial<CSSStyleDeclaration>
) => {
  const textStyles: Partial<CSSStyleDeclaration> = {};
  Object.entries(styles).forEach(([key, value]) => {
    if (isTextStyle(key)) {
      const isImportant = value.endsWith(' !important');

      textStyles[key] = {
        // strip `!important` if it exists
        value: value.replace(/ !important$/, ''),
        isImportant,
      };
    }
  });

  return textStyles;
};

make sure not to override an !important value, unless we’re overriding it with another !important value:

function mergeInheritedStyles = (oldStyles, newStyles) => {
  const inheritedTextStyles = { ...oldStyles };

  Object.entries(newStyles).forEach(([key, style]) => {
    // if the parent has an `!important` value for this style, and the current node's value is not `!important`,
    // then we should ignore it.
    if (inheritedTextStyles[key]?.isImportant && !style.isImportant) {
      // TO-DO can we use return? or break?
      return;
    }
  })
}

import StylesContext from './stylesContext';

function RenderBlock(props) {
  const stylesContext = React.useContext(StylesContext);
  // ...the rest of `RenderBlock` code

  return (
    <StylesContext.Provider value={mergeInheritedStyles({
      ...stylesContext,
      extractInheritedTextStyles(props.content.styles)
    })}>
      {/* ...The rest of `RenderBlock` render code */}
      {props.content.children.map(childElements =>
        <RenderBlock key={childElements.id} content={childElements} />
      )}
    </StylesContext.Provider>
  )
}

And finally, we have to map over the object and only grab the value properties

import StylesContext from './stylesContext';

const getInheritedStyleValues = (inheritedTextStyles) => {
  values = {}
  Object.entries(inheritedTextStyles).forEach(([key, style]) => {
    values[key] = style.value
  })
}

function BaseText({ style, ...otherProps }) {
  const stylesContext = React.useContext(StylesContext);
  return <Text {......otherProps} style={{ ...getInheritedStyleValues(stylesContext), ...style }} />
}

We should now have the ability to parse and process !important styles in React Native as well (not that anyone would ever want to do that 😉)

Do you have any suggestions on how we can improve this solution? Is there anything we missed? Please share with us on Twitter!