DEV Community: Matteo Mazzarolo

Track down the JavaScript code responsible for polluting the global scope

Matteo Mazzarolo — Wed, 23 Feb 2022 13:12:00 +0000

Following “Find what JavaScript variables are leaking into the global scope”, here’s another post to help you solve issues with global scope pollution in JavaScript apps.

In the previous post, we learned a technique to discover the name of variables being added to the global scope by JavaScript code. Just knowing the global variable names is usually enough to determine 1) if it’s ok or not for the variable to live in the global scope and, if it’s not, 2) what line of JavaScript code is adding it to the global scope.

Still, sometimes tracking down the JavaScript code responsible for creating a global variable is not that straightforward — for example, when the global variable name is extremely generic (e.g., item, x, etc.) or when the code that creates the global is deep into the dependency tree of your JavaScript app.

So, here’s how to build (from scratch) a JavaScript utility that can help us debugging where the global definitions are happening within out code.

Here’s a real-world example where this utility has helped me track-down a global variable leak coming from third-party JavaScript code.

Global pollution example

As an example, let’s focus again on the HTML document I shared in the previous post:

<html>
  <body>
    <h1>Hello world!</h1>
    <script src="https://unpkg.com/jquery@3.6.0/dist/jquery.js"></script>
    <script>
      function doSomethingTwice() {
        for (i = 0; i <= 2; i++) {
          const myString = `hello-world-${i}`;
          // Let's imagine we're going to do something with myString here...
        }
      }
      doSomethingTwice();
    </script>
  </body>
</html>

The two scripts on the page (jquery.js and the inline one) add four different global variables: $ and jQuery from jquery.js, and doSomethingTwice and i from the inline script. Because of how popular jQuery is, the $ and jQuery global names are pretty easy to associate with the library that creates them (and understand that they’re not global leaks).

The story is different for the two other globals, though:

doSomethingTwice is added to the global scope because it’s defined at the root scope (a cleaner approach would be to wrap it in a closure/IIFE). Finding the code responsible for creating this global shouldn’t be difficult with a search & replace in the codebase because doSomethingTwice is quite a unique name. But what if the global name was more generic (e.g., run), or if the code was uglified/minified or if it comes from a dependency? That would make it way more difficult to track its declaration down just based on its name.
i is (mistakenly) added to the global scope because we’re declaring it with no var/let/const while not being in strict mode. In this small example, it’s rather obvious what line of code declares it. But good luck tracking it down with a search & replace in a bigger app 😅.

So, let’s see how we can make it easy to track down the line of codes responsible for setting global variables in our codebase.

Debugging global leaks: inspecting the call stack

Here’s a high-level overview of what we can do to help us track down these pesky global variables:

Take note of the exact global variable name I want to track down (following “Find what JavaScript variables are leaking into the global scope”).
Proxy the set instruction of such variable on the window object to trigger some custom code when the variable is set. The goal of this code is to point out “what” is setting the global variable.

I’ve already covered the first step in the past, so let’s focus on the second one: proxying the window (or globalThis) object.

The idea here is that whenever an assignment like window.i = 1 happens, we want to run some code that tells us the context of where that assignment happened. To be useful, this context should provide us some information about the code that is running it (e.g., tell us the line of code or file where the declaration happened).

Here are a couple of ways to get this info:

When the global declaration happens, halt the code execution with a debugger; statement to inspect the context — this is exactly like adding a breakpoint in the script source, and it’s helpful for debugging the scope and closures.
When the global declaration happens, print the stack trace using console.trace(). This is helpful to inspect the stack trace’s code even while the execution is running.

We’ll implement both solutions using an onGlobalDeclaration function:

function onGlobalDeclaration(globalName) {
  // Print the stack trace to the console.
  console.trace();
  // Halt the code execution (only if the DevTools are running).
  debugger;
}

// TODO: Code that attaches the onGlobalDeclaration listener.

Debugging global leaks: proxying `window` attributes

Now that we can get some contextual information about the stack, how can we attach invoke onGlobalDeclaration when the global variable is set?

In the past, I tried a few different options, but to me the one that works better is to instantiate the global variable ourselves as a proxy before it gets set by the rest of our codebase. Basically, before a window.i = 1 statement runs, we want to instantiate window.i ourselves and override its setter function so that, whenever it’s invoked, we also invoke onGlobalDeclaration:

function addGlobalToInspect(globalName) {
  function onGlobalDeclaration(globalName) {
    // Print the stack trace to the console.
    console.trace();
    // Halt the code execution (only if the DevTools are running).
    debugger;
  }

  // Proxy the global variable that we're interested in.
  Object.defineProperty(window, globalName, {
    set: function (value) {
      // Invoke onGlobalDeclaration and set the value in a proxy attribute.
      onGlobalDeclaration(globalName);
      window[` __globals-debugger-proxy-for-${globalName}__ `] = value;
    },
    get: function () {
      // When the global is requested, return the proxy attribute value.
      return window[` __globals-debugger-proxy-for-${globalName}__ `];
    },
    configurable: true,
  });
}

// Inspect the strack whenever an "i" variable is added to the global scope.
addGlobalToInspect("i");

Note on ES6 proxies : ES6 introduced the Proxy object to cover similar use-cases. If you’re not familiar with it, the Proxy object allows you to create an object that can be used in place of the original object, but which may redefine fundamental Object operations like getting, setting, and defining properties.

Unfortunately, the Proxy object doesn’t work well for our use case because of how the window object is implemented at the browser level (with proxies, we’d need to override it with its own proxy instance, which we can’t do), so we need to fallback to the monkey-patching approach.

Nice! Now our code is (kinda) ready to intercept globals declaration. The next step is to ensure we run addGlobalToInspect before the global declarations statement.

Debugging global leaks: integrating the global inspector

We still need to do two things to finalize our debugging flow.

First of all, we must make sure to run addGlobalToInspect before setting the global we want to inspect. It’s up to you to decide how and when to do so, but my suggestion is to put the global inspector code in its own .js file (e.g., globals-debugger.js) and make sure to load it before all other scripts:

<html>
  <body>
    <h1>Hello world!</h1>
    <!--- 
    Make sure to load globals-debugger.js first. 
    It might be wise to load it conditionally depending 
    on the environment (e.g., do not load it in production).
    —-->
    <script src="./globals-debugger.js"></script>
    <script src="https://unpkg.com/jquery@3.6.0/dist/jquery.js">. 
    </script>
    <script>
      function doSomethingTwice() {
        for (i = 0; i <= 2; i++) {
          const myString = `hello-world-${i}`;
          // Let's imagine we're going to do something with myString here...
        }
      }
      doSomethingTwice();
    </script>
  </body>
</html>

Then, it would be nice to pick the globals to inspect dynamically instead of hardcoding them in the code like we’re doing now (as we’re doing with addGlobalToInspect("i")).

Since our script runs ASAP, I think the easiest way to pass the global names as parameters is by appending them to URL as query parameters.

For example, we can change our script so that when the page is loaded with ?globalsToInspect=i,jQuery in the URL, it will automatically start inspecting for the i and jQuery globals:

// Grab the global to inspect from the URL's "globalsToInspect" query parameter.
const parsedUrl = new URL(window.location.href);
(parsedUrl.searchParams.get("globalsToInspect") || "")
  .split(",")
  .filter(Boolean)
  .forEach((globalToInspect) => addGlobalToInspect(globalToInspect));

Complete solution: `globals-debugger.js`

Before finally trying the globals debugger, here’s the complete code (with comments and a couple of additional safety checks):

`globals-debugger.js` usage example

Finally, here’s an example of using what we just built to track down the i global creation.

Note: This is just a simplified use-case to show you the globals-debugger use-flow. In a more realistic scenario you would probably use it to track down globals added in bigger codebases or from third-party libraries deep down the dependencies tree.

Opening the HTML page above with the ?globalsToInspect=i query parameter will immediately pause the code execution when the i variable is being set (notice that the globalName variable in the current closure is i in the right panel):

Since the debugger; statement is in our own code, we need to step out of the current function (Shift + F11), to land on the exact line of code that is setting the i variable:

Last but not least, if we check the DevTools console we’ll see the logged stack trace, which is helpful to inspect the stack even while the script is running. Also, we can validate that, even if proxied, the global variables are still working correctly:

Find what JavaScript variables are leaking into the global scope

Matteo Mazzarolo — Tue, 22 Feb 2022 15:13:00 +0000

Detecting global variable leaks can be helpful to debug your apps and avoid collisions in the global scope. The more a web app grows, the more having a good understanding of what’s happening in the global scope becomes important (e.g., to ensure multiple libraries — or even multiple apps! — can coexist on the page without collisions).

In this post, I’ll show you how to find variables that have been added or leaked into the global scope at runtime in web apps (thanks to @DevelopSean for introducing me to this trick at InVision).

Disclaimer : in this post, I’ll reference global scope using the window property. Please notice that, in most cases, the globalThis property would be a better candidate to access the global object since it works in different JavaScript environments. That said, this post is specific to web (non-worker) contexts, so I think using the window term here makes it easier to follow.

Let’s say you want to check what global variables are being added to the window object on this page (with some code that looks bad on purpose):

<html>
  <body>
    <h1>Hello world!</h1>
    <script src="https://unpkg.com/jquery@3.6.0/dist/jquery.js"></script>
    <script>
      function doSomethingTwice() {
        for (i = 0; i <= 2; i++) {
          const myString = `hello-world-${i}`;
          // Let's imagine we're going to do something with myString here...
        }
      }
      doSomethingTwice();
    </script>
  </body>
</html>

Typically, you’d probably open the DevTools console and inspect the window object looking for suspicious variables.

This approach can work, but… it’s a lot of work. The browser and the JavaScript engine themselves add a bunch of globals on the window object (e.g., JavaScript APIs such as localStorage, etc.), so finding globals introduced by our code is like looking for a needle in a haystack.

One possible way to get around this issue is to grab a list of all the default globals and filter them out from the window object by running a similar snippet in the DevTools console:

const browserGlobals = ['window', 'self', 'document', 'name', 'location', 'customElements', 'history', 'locationbar', 'menubar', 'personalbar', 'scrollbars', 'statusbar', 'toolbar', 'status', 'closed', 'frames', 'length', 'top', ...];

const runtimeGlobals = Object.keys(window).filter(key => {
  const isFromBrowser = browserGlobals.includes(key);
  return !isFromBrowser;
});

console.log("Runtime globals", runtimeGlobals)

Doing so should work, but it leaves two open questions:

How do you get the browserGlobals variables?
Between cross-browser differences and JavaScript API updates, maintaining the browserGlobals list can quickly get hairy. Can we make it better?

To answer both questions, we can generate the browserGlobals list programmatically by populating it with the globals of a pristine window object.

There are a couple of ways to do it, but to me, the cleanest approach is to:

Create a disposable iframe pointing it at about:blank (to ensure the window object is in a clean state).
Inspect the iframe window object and store its global variable names.
Remove the iframe.

(function () {
  // Grab browser's default global variables.
  const iframe = window.document.createElement("iframe");
  iframe.src = "about:blank";
  window.document.body.appendChild(iframe);
  const browserGlobals = Object.keys(iframe.contentWindow);
  window.document.body.removeChild(iframe);

  // Get the global variables added at runtime by filtering out the browser's
  // default global variables from the current window object.
  const runtimeGlobals = Object.keys(window).filter((key) => {
    const isFromBrowser = browserGlobals.includes(key);
    return !isFromBrowser;
  });

  console.log("Runtime globals", runtimeGlobals);
})();

Run the snippet above in the console, and you’ll finally see a clean list with of the runtime variables 👍

For a more complex version of the script, I created this Gist:

A couple of final notes:

This utility can easily run in a Continuous Integration context (e.g., in E2E tests using Cypress) to provide automated feedback.
I recommend running this utility in browser tabs with no extensions: most browser extensions inject global variables in the window object, adding noise to the result (e.g., __REACT_DEVTOOLS_BROWSER_THEME__, etc. from the React DevTools extension).
To avoid repeatedly copy/pasting the global checker code in your DevTools console, you can create a JavaScript snippet instead.

Creating and deploying a tiny proxy server on Vercel in 10 minutes

Matteo Mazzarolo — Tue, 22 Feb 2022 14:48:00 +0000

I recently created a tiny proxy server to edit responses of a public API on the fly, and I was impressed by how easy it is to build and deploy such things on Vercel.

In my case, the goal was to allow all origins to fetch the Pinboard API by adding an "Access-Control-Allow-Origin": "*" header to the API response, but there are plenty of other cases where a proxy server may come in handy.

So, here’s how you can create and deploy a tiny but flexible Node.js proxy server on Vercel in 10 minutes.

TL;DR

We’ll create a Node.js serverless function that uses http-proxy-middleware to proxy any /api request to (e.g.) https://example.org. Within the serverless function code, we can intercept requests/responses and manipulate them on the fly.

The serverless function will be deployed on Vercel.

Project setup

Create a project directory, cd into it, and initialize an npm project:

mkdir my-proxy && cd my-proxy
npm init

Install vercel as a dependency:

npm install -D vercel

Update the start script of your package.json to "start": "vercel dev" in order to run your serverless function locally:

my-proxy/package.json

 {
   "name": "my-proxy",
   "version": "1.0.0",
   "scripts": {
     "start": "vercel dev"
   },

Create an api directory and an index.js file inside of it.

mkdir api && touch api/index.js

Vercel serverless functions use a file-system-based convention. So the api/index.js file you just created will automatically handle all requests of the /api endpoint:

my-proxy/api/index.js

// In Vercel, any file inside the "api" directory is exposed on an "/api" endpoint.

// For an API route to work, you need to export a function as default (a.k.a request handler),
// which then receives the following parameters:
// - req: The request object.
// - res: The response object.
// See https://vercel.com/docs/serverless-functions/supported-languages#node.js for details.
export default async function handler(req, res) {
  res.status(200).send(`Hello world!`);
}

By default, on Vercel, the /api/index.js file would strictly match only requests made to the /api endpoint , ignoring sub-paths like /api/hello.

To make /api/index.js handle the entire path, we can configure a Vercel rewrite to redirect all /api/* calls to the /api/index.js file (by specifying the rewrite rule in a vercel.json file at the root of the project):

touch vercel.json

my-proxy/vercel.json

{
  "rewrites": [{ "source": "/api/(.*)", "destination": "/api" }]
}

You should now be able to deploy your code to Vercel (of course, we haven’t added any “real” logic in api/index.js, so it won’t do anything for now).

My go-to approach on these occasions is to create a GitHub repo and connect it to Vercel to automatically deploy the project on each commit. But you can also follow the automated setup by running npm start.

Proxy logic setup

Install http-proxy-middleware, an easy-to-use proxy middleware compatible with Vercel:

npm i http-proxy-middleware

In /api/index.js, use http-proxy-middleware to create a new proxy and expose it on the route handler:

my-proxy/api/index.js

// Create a proxy to redirect requests of the "/api/*" path to "https://example.org".
//
// Examples:
// GET /api/hello → GET https://example.org/hello
// POST /api/test?color=red → POST https://example.org/test?color=red
//
// Additionally, the proxy will:
// - Add an "x-added" header
// - Remove the "x-removed" header
// From the proxied response.
//
// You can/should update the proxy to suit your needs.
// See https://github.com/chimurai/http-proxy-middleware for more details.
const { createProxyMiddleware } = require('http-proxy-middleware');

const apiProxy = createProxyMiddleware({
  target: "https://example.org",
  changeOrigin: true,
  pathRewrite: {
    "^/api": "" // strip "/api" from the URL
  },
  onProxyRes(proxyRes) {
    proxyRes.headers['x-added'] = 'foobar'; // add new header to response
    delete proxyRes.headers['x-removed']; // remove header from response
  }
});

// Expose the proxy on the "/api/*" endpoint.
export default function (req, res) {
  return apiProxy(req, res);
};

Et voilà!

By deploying your code (or running it locally with npm start) any call made to the /api endpoint will be proxied to https://example.org.

Check the documentation of the http-proxy-middleware library (and of the node-http-proxy library, used under-the-hood) to learn how you can manipulate the proxied request & response.

Speed up your TypeScript monorepo with esbuild

Matteo Mazzarolo — Sat, 06 Nov 2021 00:00:00 +0000

TypeScript monorepos are a great way to organize medium-to-big size projects. TypeScript improves the developer experience by adding type-checking and a deep IDE integration. And using a monorepo helps in scaling your project(s).

Compared to plain JavaScript, however, TypeScript adds an additional compilation layer to your project, which may slow down the developer experience. While the native TypeScript compiler is not that slow (IMHO), it’s still something you need to take into account if you’re planning to build a large codebase. But what if there was a way to speed up the TypeScript compilation by using a different compiler?

Enter esbuild: a fast JavaScript bundler that claims to be >10x faster than similar projects (webpack, rollup + terser, parcel 2). I’ve been using esbuilt for a couple of TypeScript projects and have been surprised by how well it performs.

🍊 Tangerine monorepo

While learning esbuild, I haven’t found many examples of how to integrate it within TypeScript monorepos. So I created my own template: 🍊 tangerine-monorepo, a “minimal” TypeScript-based Node.js monorepo setup fully powered by esbuild.

Features

Uses TypeScript to write code, tests, and scripts.
Uses esbuild to compile your TypeScript codebase, tests, and scripts.
Uses tsc CLI to type-check the codebase without emitting the compiled files (since they’re handled by esbuild). No need to keep TypeScript’s Project References up-to-date.
Uses esbuild-runner to run scripts on the fly.
Uses Yarn workspaces to make it easy to work within the monorepo.
Uses Ultra runner to run scripts from the project root.
Uses a shareable ESLint config and Jest config(./packages/jest-config) to provide an extensible linting and testing setup.
Uses esbuild + nodemon to reload the server in development mode (even when workspace dependencies are changed).

Workspaces

Tangerine monorepo includes five workspaces:

packages/is-even: The simplest workspace — it doesn’t depend on any other worskpace. It’s a Node.js module that exposes an isEven function that tells if the input number is even. It includes a CLI script that invokes the function from your terminal, and a test file, both written in TypeScript. The CLI script runs using esbuild-runner, which uses esbuild to compile it on the fly.
package/is-odd: Depends on packages/is-even. It’s a Node.js module that exposes an isOdd function that tells if the input number is odd (by invoking isEven and checking if it’s false). It includes a CLI script and a test file.
package/server: Depends on both packages/is-odd and packages/is-even. It’s a Node.js Express server that exposes two routes that invoke isEven and isOdd. It uses nodemon to reload the server in development mode.
packages/jest-config: Shared Jest config that uses esbuild to compile your tests and your codebase.
packages/eslint-config: Shared ESLint config.

All the workspaces use esbuild to compile the TypeScript codebase. Be it for building, testing, or running CLI scripts, the compilation is instantaneous compared to the native TypeScript compiler (you can quickly test the difference by temporarily swapping esbuild with tsc).

The tsc CLI is used only to type-check the codebase (without emitting the compiled files — since they’re handled by esbuild). I expect people usually use the IDE integration to type-check the code anyway and explicitly invoke the tsc CLI only in specific use cases (such as pre-commit hooks).

Each workspace’s package.json is pointing the main and types entry to src/index.ts. Which might look strange at first, given that it’s uncompiled code… see “You might not need TypeScript project references” on the Turborepo blog for an explanation. This pattern has been working fine for my use cases so far (especially while using esbuild). Still, you might want to update these entries to suit your needs (e.g., when shipping packages to npm).

Chrome does some weird stuff if you toggle a stylesheet on and off

Matteo Mazzarolo — Thu, 21 Oct 2021 11:52:00 +0000

Last week I spent more time than I expected debugging a Chrome-specific issue: when toggling the visibility of a view of one of our web apps, the view was flashing with unstyled content before becoming visible.

The flow that was causing the issue is the following:

At some point, during the user session, we hide a view and disable the stylesheet (<link href="stylesheet">) associated with it (it doesn’t really matter why we’re disabling it).
Later on, when needed, we re-enable the stylesheet.
Immediately after re-enabling the stylesheet, we show the view (e.g., by changing its visibility from display: none to display: block).

To toggle the stylesheet on and off, we are using the disabled property of the StyleSheet interface.

At this stage, the stylesheet had already been loaded once (before step 1), so expected that re-enabling it (in step 2) would have applied its styles immediately.

Unfortunately, that’s not what happens in Chrome.

When you re-enable a stylesheet, Chrome (v94.0.4606.71) sometimes tries to fetch it:

The fetch results in loading the stylesheet from the cache. Still, the browser runs this flow asynchronously, causing a quick flash on unstyled content until the stylesheet is fully loaded:

You can reproduce this issue with the following HTML code:

<html>
  <body>
    <link
      rel="stylesheet"
      href="https://unpkg.com/purecss@2.0.6/build/pure-min.css"
      id="purecss"
    />
    <button id="btn">Toggle CSS</button>
    <h1 id="text">Hello world</h1>
  </body>
  <script>
    const purecss = document.querySelector("#purecss");
    const btn = document.querySelector("#btn");
    const text = document.querySelector("#text");
    btn.addEventListener("click", () => {
      if (purecss.disabled) {
        purecss.disabled = false;
        // At this point, the stylesheet on the page should reflect the state
        // set in the previous line — but in Chrome, sometimes it wont.
        // To reproduce the issue consistently, tick "Disable cache" in
        // the network panel.
        text.style.display = "block";
        debugger;
      } else {
        text.style.display = "none";
        purecss.disabled = true;
      }
    });
  </script>
</html>

If you run your code on Chrome, sometimes you’ll notice that the breakpoint will stop in a state where the stylesheet is not fully loaded.

For example, in the screenshot below, Firefox and Chrome are paused on the same breakpoint. As you can see, in Chrome there’s a pending network request for the stylesheet, and the style has not been applied yet (see the text font style).

I don’t know if this issue is a Chrome bug or not, but I have an idea on why it might be happening.

When you add a disabled stylesheet to the page (with <link href="stylesheet" disabled>) and then enable it a runtime dynamically, browsers load the stylesheet on-demand.

My guess is that sometimes Chrome tries to load the stylesheet on-demand even if it has already been loaded before.

To solve this issue, we must wait for the stylesheet to be fully loaded before showing the view.

Unfortunately, toggling a stylesheet on and off doesn’t trigger its onload event.

As a (less elegant) alternative, we can use the document.styleSheets API. This API is a read-only property that returns the list of stylesheets explicitly linked into or embedded in the document. In Chrome, we can expect to find our re-enabled stylesheet in this list only after it has been fully loaded.

So, we can update our flow this way:

At some point, during the user session, we hide a view and disable the stylesheet (<link href="stylesheet">) associated with it (it doesn’t really matter why we’re disabling it).
Later on, when needed, we re-enable the stylesheet.
Wait for the stylesheet to be available in document.styleSheet (using a quick-looped setInterval).
Immediately after re-enabling the stylesheet, we show the view (e.g., by changing its visibility from display: none to display: block).

Example of the solution:

<html>
  <body>
    <link
      rel="stylesheet"
      href="https://unpkg.com/purecss@2.0.6/build/pure-min.css"
      id="purecss"
    />
    <button id="btn">Toggle CSS</button>
    <h1 id="text">Hello world</h1>
  </body>
  <script>
    const purecss = document.querySelector("#purecss");
    const btn = document.querySelector("#btn");
    const text = document.querySelector("#text");

    function isStylesheetLoaded() {
      return [...document.styleSheets].find(
        (stylesheet) => stylesheet.href === purecss.href
      );
    }

    // Wait for the stylesheet to be loaded
    async function waitForStylesheet() {
      if (isStylesheetLoaded()) {
        // In non-Chromium browsers the stylesheet will immediately be loaded
        return;
      }
      const intervalMs = 20;
      return new Promise((resolve) => {
        const intervalId = setInterval(() => {
          if (isStylesheetLoaded()) {
            clearInterval(intervalId);
            return resolve();
          }
          // Handle max retries/timeout if needed.
        });
      });
    }

    btn.addEventListener("click", async () => {
      if (purecss.disabled) {
        purecss.disabled = false;
        await waitForStylesheet(); // 👈👈👈
        text.style.display = "block";
        debugger;
      } else {
        text.style.display = "none";
        purecss.disabled = true;
      }
    });
  </script>
</html>

Running React Native everywhere: Browser Extensions & Electron

Matteo Mazzarolo — Tue, 28 Sep 2021 14:07:00 +0000

TL;DR

Fourth part of the "Running React Native everywhere" series: a tutorial about structuring your monorepo to run multiple React Native apps targeting different platforms.

This time, we'll focus on running React Native in an Electron app and in a browser extension.

About web-based platforms

⚠️ This post is more of a fun experiment than a real tutorial :)

I'm not aware of many React Native for Web apps running in Electron in production (besides Ordinary Puzzles and DevHub). And I've never heard of anyone running React Native for Web in a browser extension before.

Now that we added support for React Native on the web, we can leverage web-based frameworks to run our web app on different platforms:

With Electron, we can build cross-platform desktop apps to run our React Native for Web app.
With the WebExtension API (for Firefox) and the Chrome Extension API (for Chrome, Edge, Opera, and Vivaldi), we can run our React Native for Web app in a browser extension.

In both cases, we'll re-use our web app workspace as the foundation.

If you’re not familiar with web development this section will feel somewhat different from the rest of the tutorial because we won't work with anything really specific to React Native.

This is more about adding support for Electron and a browser extension to a web app. Still, I think it's still a valuable example of how our React Native JavaScript code can run everywhere.

Electron

Electron is a popular framework for building cross-platform desktop apps with JavaScript, HTML, and CSS.

Many popular apps like Visual Studio Code or Slack are built with Electron.

Let's start by addressing the elephant in the room: yes, Electron apps can (and often do) perform poorly and not fit in with the rest of the operative system. That said, Electron is still a valid option for shipping desktop apps on platforms not yet supported by React Native (e.g., Linux) or if you don't want to (or can't) deal with Windows/macOS native code.

This tutorial will show you the bare minimum setup required to develop your React Native for Web app on Electron.

If you're interested in a more in-depth tutorial, please check "Building a desktop application using Electron and Create React App".

Let's start by duplicating the React Native for Web workspace into a new electron one.

From the packages/ directory, run:

cp -R web electron && cd electron

Add the following dependencies (most of them are here only to simplify the development flow):

yarn add -D concurrently cross-env electron electronmon wait-on

concurrently: Run multiple commands concurrently. We'll use it to run both the Electron process and the React app in watch mode.
cross-env: Run scripts that set and use environment variables across different platforms. We'll use it to make our scripts compatible with both Unix and Windows OSes.
electron: The core framework for creating the app.
electronmon: Like nodemon, but for the Electron process. Allows watching and reloading our Electron app.
wait-on: Utility to wait for files, ports, sockets, etc. We'll use it to wait for the React app to be built before we open the Electron app (while developing).

The next step is creating Electron's main script. This script controls the main process, which runs in a full Node.js environment and is responsible for managing your app's lifecycle, displaying native interfaces, performing privileged operations, and managing renderer processes.

Create a new electron.js file in public/:

// Module to control the application lifecycle and the native browser window.
const { app, BrowserWindow } = require("electron");
const url = require("url");

// Create the native browser window.
function createWindow() {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  });

  // In production, set the initial browser path to the local bundle generated
  // by the Create React App build process.
  // In development, set it to localhost to allow live/hot-reloading.
  const appURL = app.isPackaged
    ? url.format({
        pathname: path.join(__dirname, "index.html"),
        protocol: "file:",
        slashes: true,
      })
    : "http://localhost:3000";
  mainWindow.loadURL(appURL);

  // Automatically open Chrome's DevTools in development mode.
  if (!app.isPackaged) {
    mainWindow.webContents.openDevTools();
  }
}

// This method will be called when Electron has finished its initialization and
// is ready to create the browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
  createWindow();

  app.on("activate", function () {
    // On macOS it's common to re-create a window in the app when the
    // dock icon is clicked and there are no other windows open.
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

// Quit when all windows are closed, except on macOS.
// There, it's common for applications and their menu bar to stay active until
// the user quits  explicitly with Cmd + Q.
app.on("window-all-closed", function () {
  if (process.platform !== "darwin") {
    app.quit();
  }
});

// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and require them here.

Then, we need to make a few changes to package.json:

Rename the app from @my-app/web to @my-app/electron.
Add the main entry. During execution, Electron will look for the script we created above in the main field of the app’s package.json.
Update the homepage property. We need to enforce Create React App to infer a relative root path in the generated HTML file. This is a requirement because we're not going to serve the HTML file; it will be loaded directly by Electron. To do so, we can set the homepage property of the package.json to ./ (see Building For Relative Paths in the Create React App documentation for more details).
Define a script to build the Create React App and start the Electron process in watch mode.

 {
-  "name": "@my-app/web",
+  "name": "@my-app/electron",
   "version": "0.0.0",
   "private": true,
+  "homepage": "./",
+  "main": "./public/electron.js",
   "scripts": {
-    "start": "craco start",
+    "start": "concurrently -k \"cross-env BROWSER=none craco start\" \"wait-on http://localhost:3000 && electronmon .\"",
     "build": "craco build"
   },

The start script might look a bit confusing now, so here's a breakdown of what it does:

concurrently -k invokes the subsequent commands in parallel, and kills both of them when the process is stopped.
cross-env BROWSER=none yarn start sets the BROWSER=none environment variables (using cross-env for Windows compatibility) to disable the automatic opening of the browser and invokes the start script, which runs the Create React App build in watch-mode.
wait-on http://localhost:3000 && electronmon . waits for the Create React App dev-server to serve the app on localhost:3000, and then invokes electronmon . to start the Electron add in watch-mode.

⚠️ Adding a build script to our Electron app requires some additional work that, for the sake of simplicity, I glossed over in this blog post. Please check "Building a desktop application using Electron and Create React App" for a more in-depth guide.

Finally, add the electron:start script to the root package.json:

"scripts": {
  "electron:start": "yarn workspace @my-app/electron start"
},

And run it to start developing your Electron app:

Browser Extension

Extensions, or add-ons, can modify and enhance the capability of a browser.

There are two primary standards used for building browser extensions:

Chrome/Chromium's extension API, supported by Chromium-based browsers (such as Google Chrome, Microsoft Edge, Opera, Vivaldi)
The WebExtensions API, supported by Firefox addons (and, in a limited way, by the latest version of Safari).

These two technologies are, to a large extent, compatible.
In most cases, extensions written for Chromium-based browsers run in Firefox with just a few changes.

Extensions are created using web-based technologies: HTML, CSS, and JavaScript. They can take advantage of the same web APIs as JavaScript on a web page, but extensions also have access to their own set of JavaScript APIs.

Since we already have a working web app, we just need a couple of tweaks to use it as the foundation for our browser extension.

Let's start by duplicating the React Native for Web workspace (packages/web) into a new packages/browser-ext one.

From the packages/ directory, run:

cp -R web browser-ext && cd browser-ext

Every browser extension requires a manifest (manifest.json) to be identified by the browser. A manifest contains basic metadata such as its name, version, and the permissions it requires. It also provides pointers to other files in the extension.

By default, Create React App creates a Web App manifest in the /public dir. This default manifest is part of the technologies that power Progressive Web Apps (PWA) and follows an entirely different standard from the Extension API manifest we need.

So, let's replace the content of public/manifest.json with our own extension manifest.
This new manifest tells the browser we're building a popup extension and that its entry point is located at browser-ext/public/index.html:

{
  "name": "My Extension",
  "version": "1.0.0",
  "manifest_version": 2,
  "browser_action": {
    "default_popup": "index.html"
  }
}

Then, we need a tiny tweak for the start and build scripts:

Out-of-the-box, Create React App embeds an inline script into index.html of the production build.

This is a small chunk of Webpack runtime logic used to load and run the application, which is embedded in our build/index.html file to save an additional network request on web apps. Unfortunately, it also breaks the extension usage by violating the web extension API Content Security Policy (CSP), which doesn't allow loading external scripts into the extension.

The easiest way to solve this issue is by turning off the inline script by the INLINE_RUNTIME_CHUNK environment variable to false:

 {
-  "name": "@my-app/web",
+  "name": "@my-app/browser-ext",
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "start": "craco start",
+    "start": "INLINE_RUNTIME_CHUNK=false craco start",
-    "build": "craco build",
+    "build": "INLINE_RUNTIME_CHUNK=false craco build"
   },

Finally, add the start and build script to root's package.json:

"scripts": {
  "browser-ext:start": "yarn workspace @my-app/browser-ext start",
  "browser-ext:build": "yarn workspace @my-app/browser-ext build"
},

We can now run browser-ext:start and add the browser extension to the browser to develop it (see "Install and manage extensions" for details):

What we've done so far is just the bare minimum work required to make the browser extension run.

As your next step, I'd suggest you to:

Clean up the public dir, making sure to keep there only manifest.json and index.html.
Remove the Service Worker and the Web Vitals scripts installed by default by Create React App (they won't work in a browser extension).
Tweak the start script to enable hot-reloading.
Get familiar with the browser extension APIs (and limitations).

Compatibility and platform-specific code

As always, please keep in mind that every platform has its limitations.

Be it Electron or a browser extension, we shouldn't expect every API exposed by React Native for Web to work out-of-the-box.

Something worth noticing is that, even if we're targeting different platforms/frameworks, the React Native Platform API will always detect the OS as "web" because it's not aware of whether a React Native for Web app is running in a website, in Electron, or in a browser extension.

A possible workaround for this issue is to inject a more specific target platform as an environment variable:

 const webpack = require("webpack");
 const { getWebpackTools } = require("react-native-monorepo-tools");

 const monorepoWebpackTools = getWebpackTools();

 module.exports = {
   webpack: {
     configure: (webpackConfig) => {
       // Allow importing from external workspaces.
       monorepoWebpackTools.enableWorkspacesResolution(webpackConfig);
       // Ensure nohoisted libraries are resolved from this workspace.
       monorepoWebpackTools.addNohoistAliases(webpackConfig);
       return webpackConfig;
     },
     plugins: [
       // Inject the "__DEV__" global variable.
       new webpack.DefinePlugin({
         __DEV__: process.env.NODE_ENV !== "production",
       }),
+      // Inject the "__SUBPLATFORM__" global variable.
+      new webpack.DefinePlugin({
+        __SUBPLATFORM__: JSON.stringify("electron"), // Or "browser-ext"
+      }),
     ],
   },
 };

In the app workspace, we can then check the __SUBPLATFORM__ global variable to detect whether we're running in a web page, in Electron, or in a browser extension.

What's next?

When I started writing this series, I envisioned this post as the last one of the tutorials.

Still, in the next few days I'll write a FAQs post to ensure the most common questions and answers about the series are captured in a single location. So, please, stay tuned!

If you somehow managed to read through this entire series, hats off to you!

I hope what I've shown you may give you some ideas about approaching a multi-platform project of your own.

I surely learned a lot while experimenting with it.

Thanks to the React + React Native team and community for building all these fantastic tools! ♥

For feedback and questions, feel free to start a discussion on the React Native Universal Monorepo's discussions page or send me a direct message.

Overview
Monorepo setup
Android & iOS
Windows & macOS
The web
Browser extensions & Electron (☜ you're here)

Originally published at mmazzarolo.com

Running React Native everywhere: The Web

Matteo Mazzarolo — Sun, 26 Sep 2021 17:17:00 +0000

TL;DR

Fourth part of the "Running React Native everywhere" series: a tutorial about structuring your monorepo to run multiple React Native apps targeting different platforms.

This time, we'll focus on running React Native on the web.

About React Native for Web

React Native for Web is an accessible implementation of React Native's components and APIs that is interoperable with React DOM.

React Native for Web translates all the references of React Native's components (e.g. View) and APIs to their HTML & DOM counterpart (e.g., div).

The React Native for Web homepage does a great job at highlighting why you should try it:

Accessible HTML. Support different devices and input modes, render semantic tags.
High-quality interactions. Support gestures and multiple input modes (touch, mouse, keyboard).
Reliable styles. Rely on scoped styles and automatic vendor-prefixing. Support RTL layouts.
Responsive containers. Respond to element resize events.
Incremental adoption. Interoperates with existing React DOM components. Bundle only what you use.

If you've already built a React Native app and you're planning to port it to the web, I recommend giving React Native for Web a try.

One of the most common mistakes people make about React Native for Web is assuming that it is React Native.

Let's be clear: in a React Native for Web project you're not "using" React Native, you're just aliasing every component and API from react-native to react-native-web.

// Running the following:
import { Button, Image, StyleSheet, Text, View } from "react-native";
// At build time is translated to:
import { Button, Image, StyleSheet, Text, View } from "react-native-web";

Instead of thinking about React Native for Web as a library for building mobile apps that run on the web, think of it as a website that uses React Native as a "components and API framework".

Because React Native for Web is a React website, you can use front-end tools to build and run it.

For example, you can build it with Webpack or Rollup instead of Metro bundler.

Like for React Native for Windows + macOS, you can add React Native for Web to an existing mobile project. I've already written about this option in the past in "Run your React Native app on the web with React Native for Web".

However, in this tutorial we'll add it as a separate web workspace.

Create React App (CRA)

React Native for Web is compatible with multiple frameworks and tools. You can use it with Create React App, Next.js, Gatsby, Expo (!), or you can create a custom build process.

To keep it simple, in this tutorial we'll use Create React App, which is a basic way to setup a simple, web-only React app with built-in support for aliasing react-native-web to react-native.

Create React App is very limited in its configuration options, so we'll use CRACO (Create React App Configuration Override) to customize its Webpack configuration to make it compatible with Yarn workspaces.

Setup

First of all, add the react-native-web library to the nohoist list in the root's package.json:

 {
   "name": "my-app",
   "version": "0.0.1",
   "private": true,
   "workspaces": {
     "packages": [
       "packages/*"
     ],
     "nohoist": [
       "**/react",
       "**/react-dom",
       "**/react-native",
       "**/react-native/**",
       "**/react-native-windows",
+      "**/react-native-web"
     ]
   }
 }

Then, from the packages directory, scaffold a new Create React App project:

npx create-react-app my-app && mv my-app web

Rename the package name:

 {
-  "name": "my-app",
+  "name": "@my-app/web",
   "version": "0.0.0",
   "private": true,

And install react-native-web:

cd web && yarn add react-native-web

The cool thing about Create React App is that adding react-native-web to our dependencies is enough to make it automatically resolve react-native-web instead of react-native.

To start using our React Native app within the web project, add it to the JavaScript entry point:

 import React from "react";
 import ReactDOM from "react-dom";
 import "./index.css";
-import App from "./App";
+import { App } from "@my-app/app";

 ReactDOM.render(
   <React.StrictMode>
     <App />
   </React.StrictMode>,
   document.getElementById("root")
 );

If Create React App supported Yarn workspaces out-of-the-box, what we've done so far would have been enough to run the app... unfortunately, it doesn't.

Luckily, we can use CRACO (or other tools such as customize-cra or react-app-rewired) to customize the Webpack configuration used by Create React App to resolve packages imported from other workspaces.

Install CRACO and react-native-monorepo-tools:

yarn add -D @craco/craco react-native-monorepo-tools

Create a craco.config.js file at the root of your web workspace.

We'll use it to:

Update the babel-loader config used in Webpack to allow importing from directories outside of the web workspace.
Use Webpack's aliases to ensure all the libraries in the nohoist list are resolved from web/node_modules. This ensures the build process doesn't bundle the same library twice if its present in multiple workspaces.
Inject the __DEV__ global variable in the codebase. __DEV__ is commonly used in React Native apps to determine if we're running in development or production mode (like process.env.NODE_ENV on the web).

const webpack = require("webpack");
const { getWebpackTools } = require("react-native-monorepo-tools");

const monorepoWebpackTools = getWebpackTools();

module.exports = {
  webpack: {
    configure: (webpackConfig) => {
      // Allow importing from external workspaces.
      monorepoWebpackTools.enableWorkspacesResolution(webpackConfig);
      // Ensure nohoisted libraries are resolved from this workspace.
      monorepoWebpackTools.addNohoistAliases(webpackConfig);
      return webpackConfig;
    },
    plugins: [
      // Inject the React Native "__DEV__" global variable.
      new webpack.DefinePlugin({
        __DEV__: process.env.NODE_ENV !== "production",
      }),
    ],
  },
};

To use the updated Webpack configuration, swap react-scripts in favour of craco in the workspace start and build scripts:

 {
   "name": "@my-app/web",
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "start": "react-scripts start",
+    "start": "craco start",
-    "build": "react-scripts build",
+    "build": "craco build",
     "test": "react-scripts test --watchAll=false --passWithNoTests",
     "eject": "react-scripts eject"
   },

And while you're at it, update the root package.json so that you can invoke the web scripts from the root of the monorepo:

  "web:start": "yarn workspace @my-app/web start",
  "web:build": "yarn workspace @my-app/web build"
},

We're done.

We can now run yarn web:start to run your app in development mode, and yarn web:build to create a production build.

Compatibility and platform-specific code

React Native for Web provides compatibility with the vast majority of React Native’s JavaScript API. Features deprecated in React Native should be considered unsupported in React Native for Web.

See "React Native compatibility" for details.

Also, like for Windows and macOS, React Native provides two ways to organize your web-specific code and separate it from the other platforms:

Using the platform module.
Using platform-specific file extensions.

On Expo & Next.js

In this tutorial we're not using Expo because it's not compatible (yet) with every platform we're supporting. Still, Expo for Web supports React Native for Web out-of-the-box, provides dozens of additional cross-platform APIs, includes web build optimizations, and is compatible with the broader React Native ecosystem.

And thanks to @expo/next-adapter, you can even use Next.js to control your Expo for Web app.

For details, check "Using Next.js with Expo for Web".

Next steps

In the next step, we'll re-use the web codebase we just created as a boilerplate to support Electron & browser extensions.

Stay tuned!

Originally published at mmazzarolo.com

Running React Native everywhere: Windows & macOS

Matteo Mazzarolo — Wed, 22 Sep 2021 11:58:00 +0000

TL;DR

Third part of the "Running React Native everywhere" series: a tutorial about structuring your monorepo to run multiple React Native apps targeting different platforms.

This time, we'll focus on the Windows and macOS platforms.

About React Native for Windows + macOS

React Native for Windows + macOS brings React Native support for the Windows SDK as well as the macOS 10.13 SDK. With this, you can use JavaScript to build native Windows apps for all devices supported by Windows 10 and higher including PCs, tablets, 2-in-1s, Xbox, Mixed reality devices, etc., as well as the macOS desktop and laptop ecosystems.

The React Native for Windows + macOS development flow is very similar to the Android and iOS one. If you're already familiar with building mobile React Native apps and with the Windows or macOS SDK, you should be able to quickly jump into a React Native for Windows + macOS codebase.

Both the Windows and macOS platforms are currently being maintained by Microsoft.

As of today, React Native for Windows is in a much more stable shape than React Native for macOS, but they're both getting better and better.

The React Native for Windows + macOS documentation follows a classic approach to setup the projects: it shows you how to add them directly in an existing React Native mobile app, resulting in having the Android, iOS, macOS, and Windows code located in the same directory, sharing a single metro bundler setup.

As explained in the monorepo setup guide, we'll follow a slightly different approach and create a workspace for each platform. By doing so, we're making our codebase a bit more complex in exchange for a simplified incremental React Native update path, because we won't be forced to use the same React Native version on all platforms.

Please keep in mind that this solution is probably a bit over-engineered if you do already expect to always use the same React Native version on all platforms. In that case, I'd suggest you to go with the classic approach shown in the React Native for Windows + macOS documentation 👍

To add support for the Windows and macOS platforms to our monorepo, we'll follow the same pattern we used with the mobile app, creating a workspace for each platform:

.
└── <project-root>/
    └── packages/
        # React Native JavaScript code shared across the apps
        ├── app/
        │   ├── src/
        │   └── package.json
        # macOS app configuration files and native code
        └── macos/
        │   ├── macos/
        │   ├── index.js
        │   ├── metro.config.js
        │   └── package.json
        # Android/iOS app configuration files and native code
        └── mobile/
        │   ├── android/
        │   ├── ios/
        │   ├── index.js
        │   ├── metro.config.js
        │   └── package.json
        # Windows app configuration files and native code
        └── windows/
            ├── windows/
            ├── index.js
            ├── metro.config.js
            └── package.json

Something worth noticing is that React Native for Windows + macOS uses metro bundler, just like React Native mobile does.

So we can leverage the same monorepo tooling we used in our mobile app! 💥

Windows

To create the windows workspace we'll follow the same procedure we used for the mobile one.

First of all, add the react-native-windows library to the nohoist list in the root's package.json:

 {
   "name": "my-app",
   "version": "0.0.1",
   "private": true,
   "workspaces": {
     "packages": [
       "packages/*"
     ],
     "nohoist": [
       "**/react",
       "**/react-dom",
       "**/react-native",
       "**/react-native/**",
+      "**/react-native-windows",
     ]
   }
 }

Then, from the packages directory, scaffold a new React Native for Windows project:

npx react-native init MyApp --template react-native@^0.65.0 && mv MyApp windows

Update windows/package.json:

 {
-  "name": "MyApp",
+  "name": "@my-app/windows",
   "version": "0.0.1",
   "private": true,
   "scripts": {
     "android": "react-native run-android",
     "ios": "react-native run-ios",
     "start": "react-native start",
     "test": "jest",
     "lint": "eslint ."
   },
   "dependencies": {
+    "@my-app/app": "*",
     "react": "17.0.2",
     "react-native": "0.65.1"
   }

Update windows/index.js to point to our app workspace:

 import { AppRegistry } from "react-native";
-import App from "./App";
+import App from "@my-app/app";
 import { name as appName } from "./app.json";

 AppRegistry.registerComponent(appName, () => App);

And finalize the Windows project setup:

Install all the required dependencies. Microsoft has done a phenomenal job here: you can check and install all the development dependencies with a single script.
Install the Windows extensions. This process will add the windows directory (with the native Windows SDK code) to the workspace and update the metro configuration to support the Windows platform.
Remove the ios and android directories from the workspace.

Last but not least, use react-native-monorepo-tools to make metro compatible with Yarn Workspaces:

const path = require("path");
const exclusionList = require("metro-config/src/defaults/exclusionList");
const { getMetroConfig } = require("react-native-monorepo-tools");

+// Get the metro settings to make it compatible with Yarn workspaces.
+const monorepoMetroConfig = getMetroConfig({
+  reactNativeAlias: "react-native-windows",
+});

module.exports = {
  resolver: {
    blockList: exclusionList([
      // This stops "react-native run-windows" from causing the metro server to crash if its already running
      new RegExp(
        `${path.resolve(__dirname, "windows").replace(/[/\\]/g, "/")}.*`
      ),
      // This prevents "react-native run-windows" from hitting: EBUSY: resource busy or locked, open msbuild.ProjectImports.zip
      /.*\.ProjectImports\.zip/,

+     // Ensure we resolve nohoist libraries from this directory.
+     ...monorepoMetroConfig.blockList,
    ]),
+   // Ensure we resolve nohoist libraries from this directory.
+   extraNodeModules: monorepoMetroConfig.extraNodeModules,
  },
+ // Add additional Yarn workspace package roots to the module map.
+ // This allows importing from any workspace.
+ watchFolders: monorepoMetroConfig.watchFolders,
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
};

That should be it! We can now run yarn windows from the windows workspace to run the app.

macOS

Like for Windows setup, to create the macos workspace we'll follow the same procedure we used for the mobile one.

The main difference here is that, as of today, the latest stable version available for React Native for macOS is 0.63.

So we need to take into account that our app will run on two different React Native versions: 0.65 for Android, iOS, and Windows, and 0.63 for macOS.

Let's start by adding the react-native-macos library to the nohoist list in the root's package.json:

{
  "name": "my-app",
  "version": "0.0.1",
  "private": true,
  "workspaces": {
    "packages": [
      "packages/*"
    ],
    "nohoist": [
      "**/react",
      "**/react-dom",
      "**/react-native",
      "**/react-native/**",
+     "**/react-native-macos",
      "**/react-native-windows"
    ]
  }
}

Then, from the packages directory, scaffold a new React Native for macOS project:

npx react-native init MyApp --template react-native@^0.65.0 && mv MyApp macos

Update macos/package.json:

 {
-  "name": "MyApp",
+  "name": "@my-app/macos",
   "version": "0.0.1",
   "private": true,
   "scripts": {
     "android": "react-native run-android",
     "ios": "react-native run-ios",
     "start": "react-native start",
     "test": "jest",
     "lint": "eslint ."
   },
   "dependencies": {
+    "@my-app/app": "*",
     "react": "16.13.1",
     "react-native": "0.63.0"
   }

Update macos/index.js to point to our app workspace:

 import { AppRegistry } from "react-native";
-import App from "./App";
+import App from "@my-app/app";
 import { name as appName } from "./app.json";

 AppRegistry.registerComponent(appName, () => App);

And finalize the macOS project setup:

Install the macOS extensions. This process will add the macos directory (with the native macOS SDK code) to the workspace and update the metro configuration to support the macOS platform.
Remove the ios and android directories from the workspace.

Last but not least, use react-native-monorepo-tools to make metro compatible with Yarn Workspaces:

const path = require("path");
const exclusionList = require("metro-config/src/defaults/exclusionList");
const { getMetroConfig } = require("react-native-monorepo-tools");

+// Get the metro settings to make it compatible with Yarn workspaces.
+const monorepoMetroConfig = getMetroConfig({
+  reactNativeAlias: "react-native-macos",
+});

module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },
+ // Add additional Yarn workspace package roots to the module map.
+ // This allows importing from any workspace.
+ watchFolders: monorepoMetroConfig.watchFolders,
+ resolver: {
+   // Ensure we resolve nohoist libraries from this directory.
+   blacklistRE: exclusionList(monorepoMetroConfig.blockList),
+   extraNodeModules: monorepoMetroConfig.extraNodeModules,
+ },
};

Run yarn macos (from the macos workspace) et voilà, our React Native app is now running on macOS!

On supporting different React Native versions

Generally, supporting different React Native versions might sound complicated.

From my experience, though, it will rarely be a problem. We only have to worry about breaking changes of React Native JavaScript API/components, which aren't that common nowadays.

And, even if it happens, let's keep in mind that we can always encapsulate platform-specific code in multiple ways.

Root-level scripts

Just like we did for the mobile package, I recommend adding a few scripts to the top-level package.json to invoke workspace-specific scripts (to avoid having to cd into a directory every time you need to run a script).

Add the following scripts to the Windows workspace:

"scripts": {
  "start": "react-native start",
  "windows": "react-native run-windows"
},

And the following scripts to the macOS workspace:

"scripts": {
  "macos": "react-native run-macos",
  "xcode": "xed macos",
  "start": "react-native start",
},

And then you can reference them from the project root this way:

"scripts": {
  "macos:metro": "yarn workspace @my-app/macos start",
  "macos:start": "yarn workspace @my-app/macos macos",
  "macos:xcode": "yarn workspace @my-app/macos xcode",
  "windows:start": "yarn workspace @my-app/windows windows",
  "windows:metro": "yarn workspace @my-app/windows start"
},

Compatibility and platform-specific code

React Native for Windows + macOS provides compatibility with the vast majority of React Native’s JavaScript API. Features deprecated in React Native should be considered unsupported in React Native for Windows + macOS.

See "API Parity" for details.

Also, React Native provides two ways to organize your Windows-specific and macOS-specific code and separate it from the other platforms:

Using the platform module.
Using platform-specific file extensions.

Next steps

In the next step, we'll add support for the web to our monorepo.

Stay tuned!

Overview
Monorepo setup
Android & iOS
Windows & macOS (☜ you’re here)
The Web
Electron & browser extension

Originally published at mmazzarolo.com

Running React Native everywhere: Android & iOS

Matteo Mazzarolo — Tue, 21 Sep 2021 12:21:00 +0000

TL;DR

Second part of the "Running React Native everywhere" series: a tutorial about structuring your project to run multiple React Native apps targeting different platforms.

This time, we'll build a modular React Native app using a Yarn Workspaces monorepo, starting from Android & iOS.

The next step

Now that the monorepo foundation is in place, we can start building our app.

The next step is encapsulating the shared React Native code and the native Android & iOS code in two different workspaces:

.
└── <project-root>/
    └── packages/
        # React Native JavaScript code shared across the apps
        ├── app/
        │   ├── src/
        │   └── package.json
        # Android/iOS app configuration files and native code
        └── mobile/
            ├── android/
            ├── ios/
            ├── app.json
            ├── babel.config.js
            ├── index.js
            ├── metro.config.js
            └── package.json

The shared React Native JavaScript code: `packages/app`

Lets' start from the shared React Native JavaScript code.

The idea here is to isolate the JavaScript code that runs the app in an app workspace.

We should think about this workspaces as a standard npm library that can work in isolation.

So it will have its own package.json where we'll explicitly declare its dependencies.

Let's start by creating the new package directory:

mkdir packages/app && cd packages/app

And its package.json:

{
  "name": "@my-app/app",
  "version": "0.0.0",
  "private": true,
  "main": "src",
  "peerDependencies": {
    "react": "*",
    "react-native": "*"
  }
}

As we already explained in the monorepo setup, we're setting react and react-native as peerDependencies because we expect each app that depends on our package to provide their versions of these libraries.

Then, let's create a tiny app in src/app.js:

import React from "react";
import {
  Image,
  Platform,
  SafeAreaView,
  StyleSheet,
  Text,
  View,
} from "react-native";
import LogoSrc from "./logo.png";

export function App() {
  return (
    <SafeAreaView style={styles.root}>
      <Image style={styles.logo} source={LogoSrc} />
      <Text style={styles.text}>Hello from React Native!</Text>
      <View style={styles.platformRow}>
        <Text style={styles.text}>Platform: </Text>
        <View style={styles.platformBackground}>
          <Text style={styles.platformValue}>{Platform.OS}</Text>
        </View>
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  root: {
    height: "100%",
    alignItems: "center",
    justifyContent: "center",
    backgroundColor: "white",
  },
  logo: {
    width: 120,
    height: 120,
    marginBottom: 20,
  },
  text: {
    fontSize: 28,
    fontWeight: "600",
  },
  platformRow: {
    marginTop: 12,
    flexDirection: "row",
    alignItems: "center",
  },
  platformValue: {
    fontSize: 28,
    fontWeight: "500",
  },
  platformBackground: {
    backgroundColor: "#ececec",
    borderWidth: StyleSheet.hairlineWidth,
    borderColor: "#d4d4d4",
    paddingHorizontal: 6,
    borderRadius: 6,
    alignItems: "center",
  },
});

export default App;

Thanks to Yarn Workspaces, we can now use @my-app/app in any other worskpace by:

Marking @my-app/app as a dependency
Importing App: import App from "@my-app/app";

The native mobile code and configuration

Now that the shared React Native code is ready let's create packages/mobile. This workspace will store the Android & iOS native code and import & run packages/app.

Using React Native CLI, bootstrap a new React Native app within the packages directory.

cd packages && npx react-native init MyApp && mv MyApp mobile

React Native CLI requires a pascal case name for the generated app — which is why we're using MyApp and then renaming the directory to mobile.

Then, update the generated package.json by setting the new package name and adding the @my-app/app dependency:

 {
-  "name": "MyApp",
+  "name": "@my-app/mobile",
   "version": "0.0.1",
   "private": true,
   "scripts": {
     "android": "react-native run-android",
     "ios": "react-native run-ios",
     "start": "react-native start",
     "test": "jest",
     "lint": "eslint ."
   },
   "dependencies": {
+    "@my-app/app": "*",
     "react": "17.0.2",
     "react-native": "0.65.1"
   },
   "devDependencies": {
     "@babel/core": "^7.12.9",
     "@babel/runtime": "^7.12.5",
     "babel-jest": "^26.6.3",
     "eslint": "7.14.0",
     "get-yarn-workspaces": "^1.0.2",
     "jest": "^26.6.3",
     "metro-react-native-babel-preset": "^0.66.0",
     "react-native-codegen": "^0.0.7",
     "react-test-renderer": "17.0.2"
   },
   "jest": {
     "preset": "react-native"
   }
 }

Finally, update packages/mobile/index.js to use @my-app/app instead of the app template shipped with React Native:

 import { AppRegistry } from "react-native";
-import App from "./App";
+import App from "@my-app/app";
 import { name as appName } from "./app.json";

 AppRegistry.registerComponent(appName, () => App);

Updating the `nohoist` list

We should be ready to run the app now, right?

Well... kinda. We still need to update the nohoist section of the root package.json to include all the libraries required by React Native.

To understand why we need to do so, try installing the iOS pods:

cd packages/mobile/ios && pod install

The command will fail with an error like this:

[!] Invalid Podfile file: cannot load such file:/Users/me/workspace/react-native-universal-monorepo -> js/packages/mobile/node_modules/@react-native-community/cli-platform-ios/native_modules.

As we explained in the previous post, by default Yarn Workspaces will install the dependencies of each package (app, mobile, etc.) in <project-root>/node_modules (AKA "hoisting").

This behaviour doesn't work well with React Native, because the native code located in mobile/ios and mobile/android in some cases references libraries from mobile/node_modules instead of <project-root>/node_modules.

Luckily, we can opt-out of Yarn workspaces' hoisting for specific libraries by adding them to the nohoist setting in the root package.json:

 {
   "name": "my-app",
   "version": "0.0.1",
   "private": true,
   "workspaces": {
     "packages": [
       "packages/*"
     ],
     "nohoist": [
       "**/react",
       "**/react-dom",
+      "**/react-native",
+      "**/react-native/**"
     ]
   }
 }

Adding the libraries from the diff above should be enough to make an app bootstrapped with React Native 0.65 work correctly:

**/react-native tells Yarn that the react-native library should not be hoisted.
**/react-native/** tells Yarn that the all react-native's dependencies (e.g., metro, react-native-cli, etc.) should not be hoisted.

You can completely opt-out from hoisting on all libraries (e.g., with "nohoist": ["**/**"]), but I wouldn't advise doing so unless you feel like maintaining the list of hoisted dependencies becomes a burden.

Once you've updated the nohoist list, run yarn reset && yarn from the project root to re-install the dependencies using the updated settings.

Now cd packages/mobile/ios && pod install should install pods correctly.

Making metro bundler compatible with Yarn workspaces

Before we can run the app, we still need do one more thing: make metro bundler compatible with Yarn workspaces' hoisting.

Metro bundler is the JavaScript bundler currently used by React Native.

One of metro's most famous limitations (and issue number #1 in its GitHub repository) is its inability to follow symlinks.

Therefore, since all hoisted libraries (basically all libraries not specified in the nohoist list) are installed in mobile/node_modules as symlinks from <root>/node_modules, metro won't be able to detect them.

Additionally, because of this issue, metro won't even be able to resolve other workspaces (e.g., @my-app/app) since they're outside of the mobile directory.

For example, running the app on iOS will now show the following (or a similar) error:

error: Error: Unable to resolve module @babel/runtime/helpers/interopRequireDefault from /Users/me/workspace/react-native-universal-monorepo-js/packages/mobile/index.js: @babel/runtime/helpers/interopRequireDefault could not be found within the project or in these directories:
  node_modules

In this specific case, metro is telling us that he's unable to find the @babel/runtime library in mobile/node_modules. And rightfully so: @babel/runtime is not part of our nohoist list, so it will probably be installed in <root>/node_modules instead of mobile/node_modules.

Luckily, we have several metro configuration options at our disposal to fix this problem.

With the help of a couple of tools, we can update the metro configuration file (mobile/metro.config.js) to make metro aware of node_modulesdirectories available outside of the mobile directory (so that it can resolve @my-app/app)... with the caveat that libraries from the nohoist list should always be resolved from mobile/node_modules.

To do so, install react-native-monorepo-tools, a set of utilities for making metro compatible with Yarn workspaces based on our nohoist list.

yarn add -D react-native-monorepo-tools

And update the metro config:

 const path = require("path");
 const exclusionList = require("metro-config/src/defaults/exclusionList");
 const { getMetroConfig } = require("react-native-monorepo-tools");

+const yarnWorkspacesMetroConfig = getMetroConfig();

 module.exports = {
   transformer: {
     getTransformOptions: async () => ({
       transform: {
         experimentalImportSupport: false,
         inlineRequires: false,
       },
     }),
   },
+  // Add additional Yarn workspace package roots to the module map.
+  // This allows importing importing from all the project's packages.
+  watchFolders: yarnWorkspacesMetroConfig.watchFolders,
+  resolver: {
+    // Ensure we resolve nohoist libraries from this directory.
+    blockList: exclusionList(yarnWorkspacesMetroConfig.blockList),
+    extraNodeModules: yarnWorkspacesMetroConfig.extraNodeModules,
+  },
 };

Here's how the new settings look like under-the-hood:

const path = require("path");
const exclusionList = require("metro-config/src/defaults/exclusionList");
const { getMetroConfig } = require("react-native-monorepo-tools");

const yarnWorkspacesMetroConfig = getMetroConfig();

module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: false,
      },
    }),
  },
  // Add additional Yarn workspaces to the module map.
  // This allows importing importing from all the project's packages.
  watchFolders: {
    '/Users/me/my-app/node_modules',
    '/Users/me/my-app/packages/app/',
    '/Users/me/my-app/packages/build-tools/',
    '/Users/me/my-app/packages/mobile/'
  },
  resolver: {
    // Ensure we resolve nohoist libraries from this directory.
    // With "((?!mobile).)", we're blocking all the cases were metro tries to
    // resolve nohoisted libraries from a directory that is not "mobile".
    blockList: exclusionList([
      /^((?!mobile).)*\/node_modules\/@react-native-community\/cli-platform-ios\/.*$/,
      /^((?!mobile).)*\/node_modules\/@react-native-community\/cli-platform-android\/.*$/,
      /^((?!mobile).)*\/node_modules\/hermes-engine\/.*$/,
      /^((?!mobile).)*\/node_modules\/jsc-android\/.*$/,
      /^((?!mobile).)*\/node_modules\/react\/.*$/,
      /^((?!mobile).)*\/node_modules\/react-native\/.*$/,
      /^((?!mobile).)*\/node_modules\/react-native-codegen\/.*$/,
    ]),
    extraNodeModules: {
      "@react-native-community/cli-platform-ios":
        "/Users/me/my-app/packages/mobile/node_modules/@react-native-community/cli-platform-ios",
      "@react-native-community/cli-platform-android":
        "/Users/me/my-app/packages/mobile/node_modules/@react-native-community/cli-platform-android",
      "hermes-engine":
        "/Users/me/my-app/packages/mobile/node_modules/hermes-engine",
      "jsc-android":
        "/Users/me/my-app/packages/mobile/node_modules/jsc-android",
      react: "/Users/me/my-app/packages/mobile/node_modules/react",
      "react-native":
        "/Users/me/my-app/packages/mobile/node_modules/react-native",
      "react-native-codegen":
        "/Users/me/my-app/packages/mobile/node_modules/react-native-codegen",
    },
  },
};

You should finally be able to to run your app on iOS now:

Fixing the Android assets resolution bug

If you run your app on Android, you'll notice that images won't be loaded correctly:

This is because of an open issue with the metro bundler logic used to load assets outside of the root directory on android (like our app/src/logo.png image).

To fix this issue, we can patch the metro bundler assets resolution mechanism by adding a custom server middleware in the metro config.

The way the fix works is quite weird, but since it's available in react-native-monorepo-tools you shouldn't have to worry too much about it.

You can add it to metro the metro config this way:

 const path = require("path");
 const exclusionList = require("metro-config/src/defaults/exclusionList");
 const {
   getMetroConfig,
   getAndroidAssetsResolutionFix,
 } = require("react-native-monorepo-tools");

 const yarnWorkspacesMetroConfig = getMetroConfig();

+const androidAssetsResolutionFix = getMetroAndroidAssetsResolutionFix();

 module.exports = {
   transformer: {
     getTransformOptions: async () => ({
+      // Apply the Android assets resolution fix to the public path...
+      publicPath: androidAssetsResolutionFix.publicPath,
+      transform: {
+        experimentalImportSupport: false,
+        inlineRequires: false,
+      },
+    }),
   },
+  server: {
+    // ...and to the server middleware.
+    enhanceMiddleware: (middleware) => {
+      return androidAssetsResolutionFix.applyMiddleware(middleware);
+    },
+  },
   // Add additional Yarn workspace package roots to the module map.
   // This allows importing importing from all the project's packages.
   watchFolders: yarnWorkspacesMetroConfig.watchFolders,
   resolver: {
     // Ensure we resolve nohoist libraries from this directory.
     blockList: exclusionList(yarnWorkspacesMetroConfig.blockList),
     extraNodeModules: yarnWorkspacesMetroConfig.extraNodeModules,
   },
 };

Try running Android — it should work correctly now 👍

Developing and updating the app

By using react-native-monorepo-tools in the metro bundler configuration, we are consolidating all our Yarn workspaces settings into the root package.json's nohoist list.

Whenever we need to add a new library that doesn't work well when hoisted (e.g., a native library), we can add it to the nohoist list and run yarn again so that the metro config can automatically pick up the updated settings.

Additionally, since we haven't touched the native code, updating to newer versions of React Native shouldn't be an issue (as long as there aren't breaking changes in metro bundler).

Root-level scripts

To improve a bit the developer experience, I recommend adding a few scripts to the top-level package.json to invoke workspace-specific scripts (to avoid having to cd into a directory every time you need to run a script).

For example, you can add the following scripts to the mobile workspace:

"scripts": {
  "android": "react-native run-android",
  "ios": "react-native run-ios",
  "start": "react-native start",
  "studio": "studio android",
  "xcode": "xed ios"
},

And then you can reference them from the root this way:

"scripts": {
  "android:metro": "yarn workspace @my-app/mobile start",
  "android:start": "yarn workspace @my-app/mobile android",
  "android:studio": "yarn workspace @my-app/mobile studio",
  "ios:metro": "yarn workspace @my-app/mobile start",
  "ios:start": "yarn workspace @my-app/mobile ios",
  "ios:xcode": "yarn workspace @my-app/mobile xcode"
},

This pattern allows us to run workspace-specific script directly from the root directory.

Next steps

In the next step, we'll add support for Windows and macOS to our monorepo.

Stay tuned!

Originally published at mmazzarolo.com

Running React Native everywhere: Yarn Workspaces monorepo

Matteo Mazzarolo — Thu, 16 Sep 2021 13:14:00 +0000

TL;DR

First part of the "Running React Native everywhere" series.

In this post, we'll lay the foundation for running multiple React Native apps within a single codebase.

Highlights:

Using a monorepo to support multiple platforms with React Native
What are Yarn Workspaces nohoist's benefits
Bootstrapping a minimal Yarn Workspaces setup

Multi-platform support

Running React Native on multiple platforms is not a new thing. We've been able to run React Native on the web, macOS, and Windows for quite a while now.

The most common and straightforward way to support different platforms with a single React Native codebase is to store all the configuration files required to run the app on all platforms in a single project directory.

For example, if you're planning to support Android, iOS, Windows, and macOS, by following the React Native for Windows + macOS documentation, you'll end up with a project that looks like this:

.
└── <project-root>/
    ├── android/
    ├── ios/
    ├── macos/
    ├── src/
    ├── windows/
    ├── app.json
    ├── babel.config.js
    ├── index.js
    ├── metro.config.js
    └── package.json

This structure can work perfectly fine for most use cases.

...but, from my personal experience, it has a few drawbacks that get exponentially worse the more your codebase grows.

First and foremost: you're forced to use the same version of React Native on every platform you support.

Therefore, you won't be able to update React Native until all platforms are ready to support it.

Even though this limitation may not seem like an issue at first, it might get you stuck on older versions of React Native if even a single platform is not compatible with the latest versions.

Let's look at a real case example: as of today (Sep 2021), the latest stable version for React Native for macOS supports only React Native 0.63.4 (released in Oct 2020).

Assuming we're planning to support both Android/iOS and macOS, we won't be able to update React Native in our project until React Native for macOS supports it. And we'd be stuck on an (almost) 1-year-old version of React Native even on Android/iOS.

P.S.: To be clear, I'm not criticizing React Native for macOS's release cycle. It's just the first example of versions gap that comes to my mind.

Second, sharing code with other projects (e.g., backend code, web apps) may get complicated.

Out-of-the-box, React Native's metro bundler cannot reference code outside of the project's root directory. You can configure it to do so (and we'll do it as well later on). Still, once you do it, you'll also need to ensure dependencies resolution works correctly (to avoid loading two different versions of the same library, for example); which might not be as easy as it may sound.

Last, because you're supporting multiple platforms in a single directory, it's easy to end up with confusing indirections and branches in platform-specific files.

This may be just a "me" thing, but I find it hard to navigate around configuration files of projects that support multiple platforms. At first glance, it may look like all platforms use the same configuration files. But once you dig a bit deeper, you realize that each platform requires some ad-hoc tweaks to the configuration files (for Metro, Babel, Webpack, etc.).

Want an example from a codebase I wrote?

Check out Ordinary Puzzles, which is a mobile, web, and Electron app.

It's not easy to understand what files are used by which platform (e.g., what platform build phase is using babel.config.js?)

A possible answer to these issues: Yarn Workspaces monorepo

A possible way to solve these issues that I've been using with success for a while now (and the one we'll use in this guide) is structuring the project as a Yarn Workspaces monorepo, keeping platform-specific code in different packages.

Yarn Workspaces (and monorepos in general) is a way to allow multiple apps to coexist in the same repository and cross-reference each other, easing the overhead of repository management and allowing a higher degree of collaboration among teams.

Each app is known as "package", and has its own package.json file.

Thanks to Yarn Workspaces, we can go from a single app that runs on different platforms to multiple apps that share common JavaScript code:

.
└── <project-root>/
    # JavaScript code of the app (shared between all apps)
    ├── app/
    │   ├── src/
    │   └── package.json
    # macOS app configuration files and native code
    ├── macos/
    │   ├── macos/
    │   ├── app.json
    │   ├── babel.config.js
    │   ├── index.js
    │   ├── metro.config.js
    │   └── package.json
    # Android/iOS app configuration files and native code
    ├── mobile/
    │   ├── android/
    │   ├── ios/
    │   ├── app.json
    │   ├── babel.config.js
    │   ├── index.js
    │   ├── metro.config.js
    │   └── package.json
    # Windows app configuration files and native code
    └── windows/
        ├── windows/
        ├── app.json
        ├── babel.config.js
        ├── index.js
        ├── metro.config.js
        └── package.json

To me, this structure perfectly suits React Native's "Learn once, write anywhere" headline.

By using a single project structure, it's easy to forget that we're not developing a "single" app: we're developing different apps (Android, iOS, web, etc.) that run the same JavaScript code.

The difference between a monolithic approach and monorepo, is that in the former, all apps are forced to use the same dependency versions. In the latter, you're free to use different dependency versions on each app.

This "freedom" comes as a double-edged sword.

Suppose you decide to use two different versions of React Native. In that case, the shared JavaScript code must support both versions: you can't simply run the current version of React Native on a platform and a two year old version of it on another and expect the shared JavaScript code to just work. Even if React Native is steadily becoming more "stable" you still need to take into account breaking changes.

That said, as we'll see later on, between platform-specific file names (index.ios.js, index.web.js, etc.) and being able to isolate platform-specific JavaScript code in packages, supporting different dependency versions might be easier than you expect.

Yarn's nohoist

A crucial part of our monorepo setup is Yarn's nohoist.

To reduce redundancy, most package managers employ some kind of hoisting scheme to extract and flatten all dependent modules, as much as possible, into a centralized location.
Yarn Workspaces store the flattened dependencies in a node_modules directory in the project root and makes it accessible to the workspace packages by symlinking the libraries in the packages' node_module directory.

While it might appear that we can access all modules from the project’s root node_modules, the reality is that build processes sometimes aren't able to traverse symlinks.
This problem is especially prominent in React Native apps, where both the metro bundler and the native code can't follow symlinks.

A common way to solve this issue in React Native monorepos, is to configure the metro bundler and the native layer to use the project's root node_modules directory instead of the package's one.
While this approach ensures you gain all the benefits of the hoisting process, it introduces a few complexities:

Each time you update React Native (or a library that requires native linking), you must also update (or at least keep in sync) the native code with the root project's node_modules directory. To me, this process has always seemed error-prone, because you're dealing with multiple languages and build-tools.
Suppose your packages need different versions of React Native (or of a library that requires native linking). In that case, you can't ensure React Native will be installed in a specific location (unless you give up the hoisting mechanism) — adding even more complexities to the table.

For these reasons, we'll use a different approach: Yarn's nohoist.

Yarn's nohoist is a setting that disables the selected modules from being hoisted to the project root. They are placed in the actual (child) project instead, just like in a standalone, non-workspaces, project.

Of course, this comes with drawbacks. The most obvious one is that nohoist modules could be duplicated in multiple locations, denying the benefit of hoisting mentioned above. Therefore, we'll keep nohoist scope as small and explicit as possible, targeting only problematic libraries.

Thanks to nohoist, we can avoid making changes to the native code, and we can keep the monorepo configuration in the JavaScript land. This means we can even extract common metro and webpack settings in a workspace package to share them easily across the entire project.

And, even more importantly, different platforms can use different versions of React Native (and native libraries), favoring incremental updates instead of migrating the entire project.

Please notice that I'm focusing on Yarn Workspaces just because it's the tool I'm most familiar with. You can achieve similar results with pnpm and nx.

Creating our monorepo

Enough with the theory! Let's start the setup of our monorepo.

First of all, ensure Yarn 1 (classic) is installed.

Then, initialize a new my-app project

# Create the project dir and cd into it.
mkdir my-app && cd my-app

# Initialize git.
git init
npx gitignore node

Add this package.json:

{
  "name": "my-app",
  "version": "0.0.1",
  "private": true,
  "workspaces": {
    "packages": ["packages/*"]
  },
  "scripts": {
    "reset": "find . -type dir -name node_modules | xargs rm -rf && rm -rf yarn.lock"
  }
}

The workspaces.packages setting tells Yarn that each package (e.g., mobile, macos, etc.) will live in <root>/packages/.
The reset script deletes all the node_modules directories in the project (recursively) and the root yarn.lock file. It may come in handy during the initial phase of the setup if we mistakenly install dependencies that should be nohoisted before adding them to nohoist :)

Create an empty packages directory:

mkdir packages

Finally, the most important part: add a nohoist section to your package.json:

{
  "name": "my-app",
  "version": "0.0.1",
  "private": true,
  "workspaces": {
    "packages": ["packages/*"],
    "nohoist": ["**/react", "**/react-dom", "**/react-native"]
  },
  "scripts": {
    "reset": "find . -type dir -name node_modules | xargs rm -rf && rm -rf yarn.lock"
  }
}

This nohoist section will tell Yarn that the listed dependencies (specified as glob patterns) should be installed in the node_modules directory of each package instead of the root project's one.

For now, I just added react, react-dom, and react-native:

react-native because the native code requires/expects it to be installed at the package level.
react and react-dom because once we start supporting the React Native for Web, it will be easy to get into a state where the app crashes because different versions of React are loaded on the page.

Spoiler: we'll have to come back and update this list every time we notice a dependency doesn't work well when hoisted.

We're done, for now!

Next steps

In the next step, we'll add support for Android and iOS to our monorepo and learn how to configure the metro bundler dynamically based on the nohoist list.

Stay tuned!

Originally published at mmazzarolo.com

Originally published at mmazzarolo.com

Running React Native everywhere

Matteo Mazzarolo — Thu, 16 Sep 2021 11:20:00 +0000

TL;DR

How to structure your codebase to run multiple React Native apps within a single codebase targeting different platforms: Android, iOS, macOS, Windows, the web, a browser extension, and Electron.

The complete project is available on GitHub: React Native Universal Monorepo.

Learn once, run everywhere

Since its inception, React Native's focus has always been enabling developers to write native applications using React. And by "native", they don't mean just "mobile" apps.

Yes, React Native is mainly known for its Android and iOS support, but its scope is steadily expanding: be it mobile devices, desktop apps, VR, or websites, React Native has an answer to almost every platform nowadays.

"Running React Native everywhere" is an in-depth guide about using React Native to run a single app on different platforms and frameworks: Android, iOS, macOS, Windows, the web, a browser extension, and Electron.

This guide leans towards showing the technical side of the platform's integration process, focusing on creating a setup that provides a good developer experience.

This is not a "how to create a React Native app" guide. We'll spend most of the time getting our hands dirty by tweaking React Native's metro bundler, customizing Webpack configurations, and learning how monorepos and Yarn workspaces work.

I won’t delve deeply into explaining how the technology stack works. A good understanding of React/React Native is required if you want to fully understand the process. Some basic knowledge of build tools like Webpack and the metro bundler will help too (but are not required).

Last but not least: I'm not looking for buy-in on using React Native on multiple platforms. I'll assume you've already done some research on the pros and cons of such an approach 👍.

Project goal

By the end of this guide, we’ll have a fully working multi-platform setup sharing a single React Native codebase.

You can find the complete code in the React Native Universal Monorepo GitHub project.

Even if I'm covering several platforms, you’re likely interested in just a couple of them.

That's ok, and that's why I'm splitting the guide into different blog posts — you can skip posts of platforms you don't care about.

Tech stack

The project we're building is structured as a Yarn workspaces monorepo.

For the sake of simplicity, code is written in plain JavaScript. Still, you can add support for TypeScript if needed (you can use the React Native Universal Monorepo as an example; it's written in TypeScript).

We're not going to use Expo. Not because I don't like it (quite the opposite: I love it!), but because currently it doesn't support all our target platforms.

We'll generate the iOS and Android app using React Native CLI, and the Windows and macOS apps app using React Native for Windows + macOS.

For the web app, the browser extension, and the Electron app, we'll use React Native for Web.

To simplify their setup, we'll use Create React App, and customize it using CRACO — but you're free to use other React-based frameworks as well (e.g., NextJS).

As of writing, the latest version of React Native is 0.65. This is the version of React Native we're going to use on most of the codebase (except for the macOS app that currently only supports React Native 0.63).

Even if we're going to mess around with the configuration of each project, updating to newer versions of React Native shouldn't be too complex. We'll keep all our configurations on the JavaScript side and, by design, we'll support and use different versions of React Native.

Acknowledgements

I created React Native Universal Monorepo and I'm writing these blog posts because I wanted to share what I learned while working on this setup on other personal projects.

For feedback and questions, feel free to start a discussion on the React Native Universal Monorepo's discussions page or send me a direct message.

Thanks to the React + React Native team and community for building all these fantastic tools! ♥

Next steps

Without further ado, let's start from the first step: setting up the monorepo.

Originally published at mmazzarolo.com

Loading web workers using Webpack 5

Matteo Mazzarolo — Mon, 06 Sep 2021 11:58:00 +0000

Just wanted to share a few notes around the currently available options for loading web workers using webpack 5.

Web Workers overview

Web workers allow you to push work outside of main execution thread of JavaScript, making them convenient for lengthy computations and background work.

Web workers are delivered as scripts that are loaded asynchronously using the Web Worker API.

A worker is an object created using a constructor (e.g., Worker()) that runs a named JavaScript file.

To create a new worker, all you need to do is call the Worker() constructor, specifying the URI of a script to execute:

// Assuming we're in a JavaScript script that runs in your main thread and that
// the worker script is available at yourdomain.com/worker.js, this will take
// care of spawning a new worker:
const myWorker = new Worker("worker.js");

Since they’re loaded as separate scripts, web workers can’t be “bundled” within the code that runs in the main thread. This means that if you’re using a module bundler to bundle your code (e.g., Webpack, Rollup) you’ll have to maintain two separate build processes, which can be pretty annoying.

The good news is that, if you’re using webpack, there are a couple of tools you can use to simplify the loading process of web workers.

Web Workers in webpack 5

Since webpack 5, web workers are first-class citizens, and you can use a specific syntax to let webpack automatically handle the creation of two separate bundles.

To do so, you must use the import.meta object (an object that exposes context-specific metadata) to provide the module URL to the Worker() constructor:

const myWorker = new Worker(new URL("./worker.js", import.meta.url));

Note that the import.meta.url construct is available only available in ESM. Worker in CommonJS syntax is not supported.

As of today, there’s not much documentation around webpack 5’s web worker supports. It indeed works pretty well for the most common use-cases and it’s a future-proof way to load web worker, but, for now, if you’re looking for a more flexible way to load web workers, you might want to take a look at worker-loader.

Webpack 5 and Worker Loader

worker-loader is the pre-webpack-5 way to load web workers, and its documentation highlights how it’s not compatible with webpack 5 (“Worker Loader is a loader for webpack 4”).

Still, in my experience, besides a few quirks, worker-loader can be used with webpack 5, and it offers several more customization options than webpack 5’s built-in web worker support.

The most important ones are probably the support for inlining web workers as BLOB and specifying a custom publicPath.

Inlining web workers

Web workers are restricted by a same-origin policy, so if your webpack assets are not being served from the same origin as your application, their download may be blocked by your browser.

This scenario can commonly occur if you are serving the web worker from localhost during local development (e.g., with webpack-dev-server):

// If the origin of your application is available at a different origin than
// localhost:8080, you won't be able to load the following web worker:
const myWorker = new Worker(
  new URL("http://localhost:8080/worker.js");
);

worker-loader solves the local development issue by allowing you to inlining the web worker as a BLOB (instead of pointing it to localhost) on development builds by specifying an inline: "fallback" option:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        loader: "worker-loader",
        options: { inline: isDevelopment ? "fallback" : "no-fallback" },
      },
    ],
  },
};

Setting a worker-specific `publicPath`

Another scenario where the same-origin policy might need some accommodations is if you’re hosting your main bundle code on a static CDN.

In this case, you’re probably going to set the publicPath of your webpack output to the CDN domain (e.g., https://my-static-cdn), so that all the assets will reference it in production. Unfortunately, this pattern doesn’t work well when using web workers because you can’t reference a web worker that is hosted on a CDN (because of the same-origin policy):

// Since the origin of the application (e.g., https://example.com) is different
// from the CDN one, you won't be able to load the following web worker:
const myWorker = new Worker(
  new URL("https://my-static-cdn/worker.js");
);

What’s great about worker-loader, is that you can solve this issue by setting a worker-specific publicPath:

module.exports = {
  output: {
    // Set the publicPath of all assets generated by this webpack build to
    // https://my-static-cdn/.
    publicPath: "https://my-static-cdn/",
  },
  module: {
    rules: [
      {
        loader: "worker-loader",
        // Overrides the publicPath just for the web worker, marking it as
        // available on the same origin used by the app (notice that this is
        // a relative path).
        options: { publicPath: "/workers/" },
      },
    ],
  },
};

A note on setting worker-loader’s `publicPath` with webpack 5

Webpack 5 introduced a mechanism to detect the publicPath that should be used automatically. Sadly, the new automatic detection seems to be incompatible with worker-loader’s publicPath… but there are a couple of (hacky) ways you can solve this issue ;)

The first one is to by setting the publicPath on the fly.

Webpack 5 exposes a global variable called __webpack_public_path__ that allows you to do that.

// Updates the `publicPath` at runtime, overriding whatever was set in the
// webpack's `output` section.
__webpack_public_path__ = "/workers/";

const myWorker = new Worker(
  new URL("/workers/worker.js");
);

// Eventually, restore the `publicPath` to whatever was set in output.
__webpack_public_path__ = "https://my-static-cdn/";

I recommend using webpack’s DefinePlugin to pass the public path as environment variables instead of hardcoding them in the source code.

The other (even more hacky) option is to apply the following patch to worker-loader (using patch-package, for example):

# worker-loader+3.0.8.patch
# Compatible only with worker-loader 3.0.8.
diff --git a/node_modules/worker-loader/dist/utils.js b/node_modules/worker-loader/dist/utils.js
index 5910165..2f2d16e 100644
-------- a/node_modules/worker-loader/dist/utils.js
+++ b/node_modules/worker-loader/dist/utils.js
@@ -63,12 +63,14 @@ function workerGenerator(loaderContext, workerFilename, workerSource, options) {
   const esModule = typeof options.esModule !== "undefined" ? options.esModule : true;
   const fnName = `${workerConstructor}_fn`;

+ const publicPath = options.publicPath ? `"${options.publicPath}"` : ' __webpack_public_path__';
+
   if (options.inline) {
     const InlineWorkerPath = (0, _loaderUtils.stringifyRequest)(loaderContext, `!!${require.resolve("./runtime/inline.js")}`);
     let fallbackWorkerPath;

     if (options.inline === "fallback") {
- fallbackWorkerPath = ` __webpack_public_path__ + ${JSON.stringify(workerFilename)}`;
+ fallbackWorkerPath = `${publicPath} + ${JSON.stringify(workerFilename)}`;
     }

     return `
@@ -77,7 +79,7 @@ ${esModule ? `import worker from ${InlineWorkerPath};` : `var worker = require($
 ${esModule ? "export default" : "module.exports ="} function ${fnName}() {\n return worker(${JSON.stringify(workerSource)}, ${JSON.stringify(workerConstructor)}, ${JSON.stringify(workerOptions)}, ${fallbackWorkerPath});\n}\n`;
   }

- return `${esModule ? "export default" : "module.exports ="} function ${fnName}() {\n return new ${workerConstructor}( __webpack_public_path__ + ${JSON.stringify(workerFilename)}${workerOptions ? `, ${JSON.stringify(workerOptions)}` : ""});\n}\n`;
+ return `${esModule ? "export default" : "module.exports ="} function ${fnName}() {\n return new ${workerConstructor}(${publicPath} + ${JSON.stringify(workerFilename)}${workerOptions ? `, ${JSON.stringify(workerOptions)}` : ""});\n}\n`;
 } // Matches only the last occurrence of sourceMappingURL

For more info, check this GitHub issue.

Originally published at mmazzarolo.com

DEV Community: Matteo Mazzarolo

Track down the JavaScript code responsible for polluting the global scope

Global pollution example

Debugging global leaks: inspecting the call stack

Debugging global leaks: proxying window attributes

Debugging global leaks: integrating the global inspector

Complete solution: globals-debugger.js

globals-debugger.js usage example

Find what JavaScript variables are leaking into the global scope

Creating and deploying a tiny proxy server on Vercel in 10 minutes

TL;DR

Project setup

Proxy logic setup

Speed up your TypeScript monorepo with esbuild

🍊 Tangerine monorepo

Features

Workspaces

Chrome does some weird stuff if you toggle a stylesheet on and off

Running React Native everywhere: Browser Extensions & Electron

TL;DR

About web-based platforms

Electron

Browser Extension

Compatibility and platform-specific code

What's next?

Running React Native everywhere: The Web

TL;DR

About React Native for Web

Create React App (CRA)

Setup

Compatibility and platform-specific code

On Expo & Next.js

Next steps

Running React Native everywhere: Windows & macOS

TL;DR

About React Native for Windows + macOS

Windows

macOS

On supporting different React Native versions

Root-level scripts

Compatibility and platform-specific code

Next steps

Running React Native everywhere: Android & iOS

TL;DR

The next step

The shared React Native JavaScript code: packages/app

The native mobile code and configuration

Updating the nohoist list

Making metro bundler compatible with Yarn workspaces

Fixing the Android assets resolution bug

Developing and updating the app

Root-level scripts

Next steps

Running React Native everywhere: Yarn Workspaces monorepo

TL;DR

Multi-platform support

A possible answer to these issues: Yarn Workspaces monorepo

Yarn's nohoist

Creating our monorepo

Next steps

Running React Native everywhere

TL;DR

Learn once, run everywhere

Project goal

Tech stack

Acknowledgements

Next steps

Loading web workers using Webpack 5

Web Workers overview

Web Workers in webpack 5

Webpack 5 and Worker Loader

Inlining web workers

Setting a worker-specific publicPath

A note on setting worker-loader’s publicPath with webpack 5

Debugging global leaks: proxying `window` attributes

Complete solution: `globals-debugger.js`

`globals-debugger.js` usage example

The shared React Native JavaScript code: `packages/app`

Updating the `nohoist` list

Setting a worker-specific `publicPath`

A note on setting worker-loader’s `publicPath` with webpack 5