DEV Community: Callstack Engineers

A Step-By-Step Guide to Super App Development

Callstack Engineers — Thu, 18 May 2023 10:34:17 +0000

With the number of active mobile users growing and the consumers' demands for smooth mobile-first experiences strengthening each year, it’s no surprise you’re considering jumping on the super app bandwagon. After all, super apps come with a number of benefits for both users and the businesses behind them.

To help you take the first step, we’ve put together some tips for developing a super app from the tech perspective. As businesses and their products come in all shapes and sizes, we’re focusing here on two scenarios:

building a super app from scratch,
migrating your solutions to a super app setup.

Speaking of different shapes and sizes, when creating a super app, you can choose from a couple of different approaches, including:

Native Android application with Feature Delivery
Native iOS application with WebViews
Cross-platform React Native application with Metro
Cross-platform React Native application with Webpack and Re.Pack

In this article, we’ll be focusing on the latter, not only because we’re the people behind Re.Pack, but primarily because this solution allows you to enjoy the most benefits compared to other tools. Building your super app with Re.Pack means the ability to reuse features across apps, smaller JS bundle size, OTA updates, time and cost-effective development experience, and potential to leverage third-party contributors – these perks pretty much speak for themselves.

Now let’s get down to the super app development business, shall we?

Building a super app from scratch

For the sake of this tutorial, we’ve prepared an example repository with two apps inside one monorepo, namely HostApp and MiniApp. You can find the repository with the example here.

The HostApp is a simple app with HomeScreen and a DetailScreen, which you can reach via a button on the HomeScreen. MiniApp is similar, but has a button that navigates to the GalleryScreen with a list of pictures.

For now, those are two separate apps that have nothing in common with each other and run independently. Each app has its own navigation with a few screens. Our goal in this part will be to bring the MiniApp into the HostApp using Re.Pack and Module Federation.

Why this combination of technologies? Re.Pack is an Open Source toolkit that allows you to build React Native apps with the support of the Webpack ecosystem. Thanks to supporting Module Federation ever since the 3.0 version, it’s particularly fit for developing mobile applications that benefit from code splitting – and super apps are a great example of those.

Now that you get the gist of using Re.Pack and Module Federation to build a super app, we can get to the nitty-gritty. Let’s get started by cloning the repository:

Setting up Re.Pack in both HostApp and MiniApp

In both packages/host-app and packages/mini-app install Re.Pack with its dependencies:

Make sure to run yarn bootstrap from the repository's root to update the pods that come with those dependencies.

Now let’s make some adjustments to the setup. To make React Native CLI able to use Re.Pack commands (such as webpack-start or webpack-bundle), we will add the following content to react-native.config.js (or create it if it doesn't exist):

Having done that, let’s update our package.json scripts to reflect these changes. Edit the start script for both apps, so it utilizes new webpack-start command, which starts the development server for Re.Pack:

Now add webpack.config.mjs to each app in our monorepo. For now, we’ll start with a default template that will be modified along the way. You can find the ES Module template here or the CommonJS equivalent here. Either one will work just fine.

The last step of this part is to modify the scripts used for bundling the iOS and Android.

Open your application's XCode project/workspace and:

Click on the project in the Project navigator panel on the left
Go to Build Phases tab
Expand Bundle React Native code and images phase
Add export BUNDLE_COMMAND=webpack-bundle to the phase

Go to android/app/build.gradle in both apps, uncomment the line with bundleCommand in the react block, and modify it to use webpack-bundle:

That’s the basic setup for Re.Pack; try running the apps to see if everything works as expected.

Setting up ModuleFederationPlugin

Now it’s time to set up the ModuleFederationPlugin. Not long ago, you were required to do some hacky workarounds to get the Module Federation working with Re.Pack. Since the release of version 3.0, though, the ModuleFederationPlugin has been included out of the box.

Let’s add a new instance of RePack.ModuleFederationPlugin to our webpack.config in the HostApp:

We’ve added all our dependencies because they all have native code inside, and whenever a dependency has native parts, you must add it to the shared field inside ModuleFederationPlugin.

Usually, when a node module contains android and/or ios directories, you should consider it native. When it comes to dependencies with only JavaScript in them, you can leave them out, and Re.Pack will take care of downloading them from the mini app. However, it is advised to also include them as you will reduce the overall network transfer when loading the bundles.

We’ve also specified singleton and eager on them.

Singleton means that only one instance of such a module will ever be initialized, which is a requirement for React and React Native. It is usually a good idea to make the dependencies with native parts singleton as well.

Eager, on the other hand, means that the module is added to the initial bundle and will not be loaded later. All shared modules in the host app should be eager. In remote containers, it depends on the build configuration. When you want to run the app as a standalone, you need to mark all the shared dependencies as eager as well.

Having that in mind, let's add a similar configuration of the plugin to the mini app:

Inside webpack.config.mjs, let’s grab STANDALONE from the process.env
Now let’s add the ModuleFederationPlugin just like in the HostApp
Finally, let’s add a separate script to run webpack in our mini app in standalone mode and modify the previous start script to run on a different port (which will come in handy soon when we need to have both our development servers running at the same time)

STANDALONE env variable will help us to distinguish when we want to run the app as a separate entity or as a mini app. Currently, modules specified in shared will be eagerly loaded only when running the app on its own.

Setting up ScriptManager in the HostApp

The last part of the setup to get the HostApp ready to accept remote containers is to add the ScriptManager’s resolver. We need to tell our app where to find the mini app, and we’re about to do it now.

Let’s add the following piece in the HostApp’s index.js on line 4

As ScriptManager can have many resolvers, we need to return the configuration for the bundle only if we get a URL match. Implicitly returning undefined here means the ScriptManager should keep looking at other resolvers to find a proper match. In the example, the configuration contains info about the URL and platform, but many more options are available for the more advanced use cases.

Our basic Module Federation setup is now complete, and we can start connecting the two apps.

Using MainNavigator from the `MiniApp` in the `HostApp`

In this part, we will be going through the process of reusing the whole MiniApp inside our HostApp. The part we will need is the MainNavigator from the MiniApp, as we don’t want to have two NavigationContainers in our app.

First, we must expose the MainNavigator from the MiniApp to be available for consumption in the HostApp. Let’s go to MiniApp’s webpack.config.mjs and expose it there:

You can expose the components to be consumed by adding them in the form of key-value pairs, where the key is the name used to refer to that component in the HostApp, and the value is the path to the component. Note that for this to work, we must use export default in our component.

Once we’re done with that, it’s time to import the MiniApp into the HostApp. Let’s create a new screen that will house the MainNavigator from the MiniApp:

Federated.importModule takes two parameters: the name of the container and the name of the component that we want to import. As we want to load the component only when the user enters that particular screen, we need to put the import inside React.lazy and render it within React.Suspense.

To finish up, let’s add the MiniAppScreen to the MainNavigator in the HostApp and add a button to navigate to MiniAppScreen inside HomeScreen:

Now we should have a working MiniApp inside our HostApp. Go ahead and start both development servers using yarn start command in the root of the repository, and then let’s run the host app. If you choose to run the app on Android, remember to expose the port on the Android emulator to your machine by running:

Click on the newly added button to Navigate to MiniApp and enjoy your super app!

It’s easy to notice that after navigating to the MiniApp, we end up with two navigation headers. We can fix that by adjusting the header in the HostApp or exposing a navigator without the header; the decision is up to you.

Migrating to a super app setup

Migrating to a super app setup requires careful consideration and planning. Upgrading your existing setup with Re.Pack and Module Federation, as we’ve described above, shouldn’t pose problems in itself. However, it may become challenging in the context of your current project and the custom solutions it involves. In this part, we look at such challenges and cover a few key things to consider when turning your product into a super app.

Aligning dependencies

If you’re considering enriching your product portfolio with a super app, your codebase is probably already large enough to contain many dependencies. The biggest challenge lies in aligning the dependencies between respective apps, so they can be shared as efficiently as possible.

If there is an issue with one library or component, the federated module could suffer misaligned versions of libraries in the host app. Some tolerance is involved, as Re.Pack will try to fetch the missing dependencies by default, and runtime errors might not be the case. At the end of the day, however, Re.Pack will complain about version requirements not being met, albeit in development mode.

When the package contains native code and the versions are not aligned, a runtime error will occur. To avoid that, it is a good idea to have an error boundary wrapper that prevents federated modules from crashing your host app and displays fallback components when such issues arise.

Assets handling

Another thing that’s vital to successfully migrating your app is handling the assets. When the mini app is embedded into the host app, it won’t be able to access its local assets, as they won’t be added to the host app asset’s registry in build time. You need to remember that this problem won’t manifest itself in development mode with dev-server – only when working with a static bundle produced by the react-native webpack-bundle command.

‍Re.Pack offers two ways to deal with that. The first one, and by far the preferred one, is to handle the assets just like we do on the web, where our assets are first uploaded to a remote server (preferably CDN) first, and only then can be downloaded by the users. Re.Pack provides allows you to gather all the assets and modify the final bundle so that the production build can download them on demand.

These assets are now remote, so it might be necessary to include a placeholder to display while loading them. When working with remote assets, the only limitation is that the hostname of your CDN needs to be known at build time, so Re.Pack can generate the URLs for these assets.

Another alternative to consider is inlining all the assets from the federated module, so they are downloaded with the bundle itself. You can do that by adjusting the assetLoader’s options in the webpack.config.mjs, namely: setting inline to true. This solution has one major drawback: it significantly increases the bundle size. You might consider inlining some assets if you don’t want them to be publicly accessible on the web, or they are vital to a swift startup of your mini app, as they will be instantly visible to the user.

Sharing state across the app

When trying to create a super app from an existing app by extracting a certain functionality to a mini app, state management might become an issue. Until now, the state has been tightly coupled with the whole app. If you want your mini app to be a consumer of that state, it is necessary to address that problem.

For the sake of this example, let’s assume we have a setup like in the first part of the article. To make our state management solution reusable across the board with mini apps and the host app, we could extract the shared state into a separate package. Depending on whether you would like to update the state part of the app over-the-air, you could make it into a federated module as well. Otherwise, this can be a statically imported module into both the host app and the mini app.

If we specify this module inside the shared portion of the Re.Pack’s ModuleFederationPlugin, we will only have one copy of that module during the runtime of our super app. If that’s the case, we will be able to place the ContextProvider component in the host app and access the same instance in our mini app, having a shared state across the whole app.

These are just a few examples of challenges you might face when migrating to a super app setup. It’s hard to tell what you might run into, as every app is unique in its own way. Mind that Module Federation has been present in the web environment for quite some time, so if your problem is strictly related to the JS part of the app, chances are someone solved a similar problem already, and the concept might be applicable in the context of super apps.

Summary

We hope this article has shed more light on what it takes to develop a super app from the tech standpoint. Whether you’re up for building a super app from scratch or migrating your current solution into such a setup, it might turn out that your team needs some help to do it right. That’s why we’ve prepared a super-app-showcase. Use it to your advantage, and don’t hesitate to reach out to us if you have any questions about super app development.

If you’re looking for more organizational tips, we’ve also got you covered with a blog post about developer experience and planning the work of your in-house team and third-party contributors. We’ve also published a case study of a super-app-showcase that might significantly speed up your work.

This article was originally published at callstack.com on April 12, 2023.

Working With the Super-App-Showcase Repository

Callstack Engineers — Thu, 18 May 2023 09:09:16 +0000

by Jakub Romańczyk

On Callstack blog, you’ll find tips for building a super app and maximizing the efficiency of the development process in such setup. To give you even more insights into what super app development is all about, we’ve put together a case study of the super-app-showcase, a prime example of a repository demonstrating how to structure a super app when working with Re.Pack effectively.

Building upon the tutorial found in this step-by-step guide to super app development, where we showcased the bare minimum to illustrate super app development principles, this case study presents a more robust example that could evolve into a production-ready super app.

By analyzing this showcase, we can gain valuable insights into the solutions implemented to tackle various challenges developers face while creating a super app. By exploring the intricacies of this showcase, we mean to:

provide an overview of the general architecture of the solution,
set the stage for a deeper understanding of each component's role in creating a seamless and efficient super app,
empower you to deal with super apps more effectively in your projects.

Architecture overview

The super-app-showcase repository incorporates a micro-frontend architecture, facilitating easy setup and maintenance of the contained apps. These apps can be deployed independently or as part of the super app, providing developers with flexibility and fostering efficient collaboration.

The super-app-showcase is composed of the host app, which functions as the main container for all the micro-frontends, and the shell app, which acts as a blueprint of the host app with shared dependencies. Among other apps, you’ll find booking, shopping, news, and dashboard, each representing a micro-frontend for their respective services. An additional auth module is exposed for other modules to implement authentication and authorization flows, and UI.

Each of the mini apps, such as booking, shopping, news, and dashboard, exposes a MainNavigator, representing the mini app itself. In the case of the booking app, an additional UpcomingAppointments screen is exposed, which is used within the super app as part of its navigation. The news mini app is stored in a separate repository to demonstrate the usage of a remote container outside the monorepo.

Monorepo

As the team behind the super-app-showcase, we decided to go with a monorepo, but we need to emphasize that it's a strategic choice and not a strict requirement. There are both pros and cons to consider regarding this solution.

One of the major advantages of using a monorepo is that it simplifies dependency management. In our case, we've set up a shared directory in the root of the monorepo containing a JSON file with shared dependencies for the Module Federation. This approach makes it easy for developers to maintain the most vital part of the Re.Pack’s Module Federation Plugin.

Furthermore, a monorepo enhances code sharing, improving code reusability and consistency across the project. For instance, a monorepo enables us to enforce linting rules and formatting throughout the entire codebase, ensuring a uniform code style. This can significantly benefit development teams looking to maintain a clean and coherent codebase.

As mentioned previously, the news mini app is stored in a separate repository. This demonstrates that the entire app could have been structured using individual repositories instead of a monorepo, which might suit some projects better. Ultimately, the decision to use a monorepo or separate repositories should be based on your development team's specific needs and preferences, keeping in mind the unique aspects of each project. It's crucial to weigh the pros and cons, such as potential scalability issues and challenges in managing a large codebase, when deciding whether a monorepo is the right choice for your project.

Catalog server

The super-app-showcase includes a package within the monorepo named catalog-server, which plays a vital role in handling mini app compatibility in production environments. Built using Node.js and Express, this straightforward server acts as a reliable resource for determining which mini app version to download considering the requesting app's requirements, such as its current version.

Centralizing versioning logic in the catalog-server allows developers to easily implement custom versioning strategies, ensuring seamless integration between the host app and its corresponding mini apps. This approach is fundamental when dealing with conflicts arising from native dependencies. When a new version of the host app is released, users who are still on an older version of the host app should not download the latest mini app that requires the newest native changes. Instead, the catalog-server ensures they download the most recent, compatible version that guarantees a smooth experience.

By managing version compatibility this way, the catalog-server effectively mitigates potential issues arising from different host app versions and provides seamless integration between the host app and its corresponding mini apps, maintaining the stability of the super app.

State management

The auth package in our super-app-showcase monorepo is a practical solution for state management, focusing on authentication and authorization for all mini apps. Keep in mind that this package isn't meant to work as a standalone module. Instead, it serves as a collection of components designed to handle authentication and authorization within the super app.

This package makes it easy for developers to integrate authentication and authorization flows into their super app. Although it doesn't have dedicated iOS or Android folders, it relies on the host app bundle for any necessary native-based libraries.

What's great about the auth package is its reusability. When mini apps are run independently, they can use their own provider component for authentication and authorization. But when they're part of the host app, they can efficiently use the provider component from the host app itself. This approach not only simplifies the development process but also ensures a consistent and secure user experience across the entire super app.

The package can be viewed as a template for implementing reusable state management solutions in super apps using any library of your choice. By following the design principles demonstrated in the auth package, developers can create their own custom state management solutions tailored to their specific needs and preferences while maintaining the same level of reusability and consistency throughout the super app.

Shell app

The shell app, although not strictly required, serves as a helpful addition to the host app by precisely representing its structure and navigation. To maintain its usefulness, it should be kept in sync with the host app. The shell app's lightweight design trims the excess, focusing on the aspects needed for integration. It may even feature pre-configured states for hassle-free testing of different aspects. This effective testing process allows developers to pinpoint and tackle integration challenges early on, resulting in an overall more stable super app.

Summary

The super-app-showcase serves as a comprehensive guide to building a robust and scalable super app using Re.Pack and Module Federation. By exploring its monorepo structure, catalog-server, basic state management solution we've highlighted various solutions and best practices that developers can employ to tackle challenges and streamline the development process.

By understanding the architectural choices, such as monorepo versus separate repositories, and leveraging shared components and state management, you can create powerful super apps that offer a consistent and seamless user experience. Armed with this knowledge, you are now better equipped to navigate the world of super app development and bring your own super app projects to life. And if you’re looking for an experienced tech partner to help you with super app development, get in touch with our team.

This article was originally published at callstack.com on April 12, 2023.

How to Optimize Development Efficiency When You’re Building a Super App

Callstack Engineers — Thu, 18 May 2023 08:49:45 +0000

by Jakub Romańczyk

The modular architecture of super apps translates into significant benefits for their creators. Enriching your product portfolio with a super app ultimately means greater flexibility, more sustainable growth, and increased development efficiency. However, to enjoy these benefits, you need to plan the development process well – and in this article, we’re going to show you how to take care of that.

We’ll take a closer look at two factors that have the potential to boost the efficiency of your super app development process:

preparing for third-party contributions,
laying the foundations for smooth teamwork.

If you’re looking for practical tips on developing a super app, check out this guide to super app development and a case study of our super-app-showcase. For now, though, let’s focus on the organizational side of this process.

Preparing your super app for third-party contributions

Super apps’ architecture enables third-party contributions to be seamlessly integrated into an app. In practice, it means you’re capable of developing certain features faster and more efficiently by leveraging the expertise and capabilities of an external team.

While it sounds promising, you need to be cautious and thoroughly vet the third-party engineers you choose to work with, as the app will run in the same JavaScript context with their code, potentially posing a security risk. In this part of the article, we discuss a few things to consider when opening up your app for third-party contributions.

Laying down requirements

First and foremost, you need to set out requirements for the mini apps. It is absolutely necessary to specify what version of React and React Native the mini app is supposed to use, and this requirement needs to be kept in sync with the host app at all times.

If the mini app is going to use a native module, it is also necessary to declare this upfront and add it to the host app to ensure that everything works as expected. It might be useful to establish a communication channel when a native dependency needs to be added to the host app so that the super app team can quickly approve or reject the proposed change.

Besides the setup requirements, it's also a good idea to provide a design rule book or a shared UI components library that the third-party developers must use when building their features so that the app is coherent as a whole.

Optimizing developer experience

To provide a great development experience that will minimize integration issues and possibly enforce some requirements mentioned above, consider creating and exposing a sandbox environment that closely resembles your host app. This way, the team working on the mini app can ensure everything is well-aligned. It proves particularly useful when the host app is being upgraded to a new version of React Native, allowing each team to independently upgrade their respective mini apps.

SDK

If you want your third-party mini-app to be consistent with the overall app's design and/or communicate with the host app, you should consider creating an SDK in the form of a dependency added to the mini-app.

An SDK can provide some common components, such as loading indicators or navigation headers. It can also expose methods to access the host app’s state (e.g., redux selectors) or even basic tools for developers like an ESLint preset. Remember that the SDK contents depend on the details of your setup.

Mobile nuances

Last but not least, don’t forget that the mobile environment differs from the web. If you plan on integrating big new functionality with your app, you need to go through the App Store or Google Play Store review process again to audit that functionality. Omitting this step may result in your app being removed from the store altogether.

As you can see, enabling third-party contributions in your super app will require some effort on your end. We haven’t mentioned here the delivery-related matters, as they’re even more specific to your own setup. Still, the ideas discussed in this section will be helpful if you decide to outsource some of the feature work to external teams.

Fostering collaboration between teams working on your super app

The super app approach enables teams to split their work while maintaining a coherent application, which is critical when multiple teams work on different parts of a single application or system.

Respective squads can independently develop and deploy parts of an application as mini apps: standalone modules that provide specific functionality or user interface components. They can be hosted and deployed autonomously (to a certain extent) while seamlessly integrating into the larger super app. In day-to-day work, this allows teams to collaborate more efficiently by reducing inter-team dependencies and enabling them to focus on their specific areas of expertise. In this part of the article, we explain how to make this teamwork as smooth as possible.

Sustainable architecture

The most common trend when splitting a monolith app into micro frontends is to divide the app into separate features. Separating the app screen by screen is overkill and should be avoided. Instead, we recommend identifying the core functional areas or features that can be developed and managed independently.

This will create a more sustainable architecture, allowing for more effortless scalability and efficient development cycles. By focusing on feature-based divisions, teams can optimize work, reduce communication overhead, and streamline project organization.

Lightweight host app

To ensure a seamless developer experience, creating a lightweight version of the host app is advisable solely for integration purposes. This stripped-down version should provide a basic scaffolding, enabling mini apps to be embedded in the same context as the host app. Keeping this version up to date with the host app is crucial, particularly with regard to dependencies and the component tree.

Although this may seem like a labor-intensive process, maintaining the lightweight version is typically only necessary when core changes occur in the host app, such as dependency upgrades or interface changes. This approach allows developers to test and debug their mini apps more efficiently in an environment that closely resembles the final super app, promoting better collaboration and minimizing integration issues.

Monorepo

Another optional strategy for managing super app development is organizing the codebase into a monorepo. By keeping all code in one central repository, teams can more easily share code, enforce consistent coding standards, and manage dependencies between projects.

Nevertheless, managing a monorepo can be difficult, as it requires careful attention to how different projects interact with one another. Bear in mind that the independence granted by Module Federation could be limited when adopting a monorepo, as it brings the codebase together.

To make the most of a monorepo, teams should establish clear guidelines for how code is structured and shared, leverage automation for streamlining development and testing processes, and maintain a strong focus on communication and collaboration across the entire team.

Summary

Building a super app using Re.Pack and Module Federation can be a complex endeavor, with numerous aspects to consider when dividing work among development teams. To successfully navigate this process, it is crucial to carefully evaluate various strategies and tailor them to the project's unique requirements.

We’ve presented here several ideas to help guide the decision-making process, but you need to remember that there is no one-size-fits-all solution. Ultimately, effective communication, collaboration, and adaptability are key factors in addressing the challenges of super app development and ensuring a seamless end product.

‍If you need help navigating through the super app development process, give us a shout, we’ll be happy to help.

This article was originally published at callstack.com on April 12, 2023.

Migrating a React Native Library to the New Architecture

Callstack Engineers — Mon, 14 Nov 2022 13:07:18 +0000

by Oskar Kwaśniewski

Introduction

This article is a bird's-eye view of migrating a React Native library to the New Architecture. At first, I wanted to go into the details. However, due to the pace of changes and ever-evolving new patterns, I decided to walk you through the migration steps with the helpful resources I found.

I had the pleasure of working on migrating react-native-slider and also the Android part of react-native-pager-view.

What’s the New Architecture?

If you are following things that happen in the React Native world, I’m sure you heard about the New Architecture, including Fabric and Turbo Modules.

If you are new to the “New Architecture” world, check out Lorenzo's at React Native Wrocław Meetup this year.

https://youtu.be/sdQHzjV90ow

There is also a podcast episode on the New Architecture in which Łukasz Chludziński talks with Nicola Corti, a member of the React Native core team.

What’s Fabric?

Fabric is React Native's new concurrent rendering system, a conceptual evolution of the legacy render system. It allows for all the features React 18+ brings to the table. Fabric is one of the 4 pillars of the New Architecture that React Native core team is working on since 2018.

Thanks to Fabric, instead of using the bridge which communicated with serialised JSON messages, we can communicate using JSI (second pillar), which is a C++ API for interacting with any JS engine. Ultimately JSI is going to replace the bridge (it’s the “bridgeless” project) but for now they live side by side, which is good because it can speed up your migration when you stumble upon some edge case which is not supported yet.

The third pillar is Turbo Modules. It’s an interface on top of JSI, that leverages CodeGen (the last pillar) to generate C++ code from our TypeScript or Flow spec.

If you want to try out the new Architecture in your app make sure to follow this guide.

Steps to migrate a library

Writing TypeScript spec for Codegen
Migrating deprecated JavaScript APIs
Extending react-native-codegen generated interfaces on native platforms (Android / iOS)
Done ✅

This may seem like a lot of work but with the documentation getting better and more developers getting involved in the process, it becomes easier every day. It is also worth noting that the first two steps can be done even before migrating to the New Architecture - when preparing your library for migration.

Using an official migration guide for library creators

There is an official migration guide that you can follow: React Native New Architecture Libraries. It has examples creating simple Fabric component and also a Turbo Module. There is also another guide for migrating your whole app to the New Architecture.

These examples really help to get you going with the migration. However, most of the time you will end up browsing the source code of other libraries (at least I did). So another helpful resource is a list of already migrated libraries.

Creating a library from scratch

If you want to create a new library or just scaffold a New Architecture setup for your existing library, you can use react-native-builder-bob which recently received a lot of new features!

Here is a screenshot of scaffolding a new library with create-react-native-library. As you can see, there are new options for Turbo Modules.

We have used it to scaffold the New Architecture inside react-native-pager-view which was way faster than creating all the necessary setup by hand. Fabric support will be added soon, but it may be already there as you are reading the article 😄 So go ahead and give Bob a try!

1. Writing TypeScript spec

Now let’s start with the migration part. The goal of this step is to write a specification of your module which is a set of types written in Flow or TypeScript that defines all the APIs provided by the native module. Using a spec allows Codegen (code generation tool for React Native) to generate native code for each platform during build time. To find more about it, refer to the docs.

Here is how the generated files look like for Android.

It sounds so good in theory. In reality, however, not everything is working as expected (yet!). Let’s go over a few issues I’ve stumbled upon.

Unsupported props between platforms
As for now CodeGen doesn’t support platform specific specs, so keep in mind that you need to define types for every platform in your spec file. If you have any props that’s not supported on iOS it’s not a problem because you can skip it inside updateProps method:

- (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &)oldProps
{
    const auto &oldScreenProps = *std::static_pointer_cast<const RNCSliderProps>(_props);
    const auto &newScreenProps = *std::static_pointer_cast<const RNCSliderProps>(props);

        if (oldScreenProps.step != newScreenProps.step) {
        slider.step = newScreenProps.step;
    }

        // Handle only supported props here
}

snippet 1.javascript hosted with ❤ by GitHub

snippet source code

However, Android handles props a little bit differently. It generates setters for all of the props which need to be overwritten.

The best way to tackle this problem is to override those setters with empty functions like here:

// iOS only prop
@Override
public void setVertical(ReactSlider view, boolean value) {}

snippet 2.javascript hosted with ❤ by GitHub

Union types
Typescript union types are not yet supported by Codegen, but we can get around this limitation by using a Codegen helper type named WithDefault<>.

Here is what this “hack” looks like in react-native-pager-view

overScrollMode?: WithDefault<'auto' | 'always' | 'never', 'auto'>;

snippet 3.javascript hosted with ❤ by GitHub
If you ever get stuck, you can go through these resources:

react-native source code (features a lot of fabric components)
Working Group for the New Architecture - features a list of already migrated libraries.

It’s also worth mentioning that Meta is working on making Codegen support more advanced.

2. Migrating deprecated APIs

Both projects I’ve worked on haven’t used any of the deprecated APIs. However, one of the most used ones is setNativeProps. It fundamentally breaks the model of the New Architecture leading to skipping all the rendering steps and desynchronising UI between React Native and what’s shown to the user. You can read more about it on github.

If you happen to use one of the APIs from this list though, it should be pretty straightforward to just replace them. You can find helpful resources in the Working Group discussion on the New Architecture.

3. Implementing Codegen generated interfaces on native platforms (Android / iOS)

This step is probably the most time consuming and it depends on the complexity of your library.

Android part is easier since we are having two source sets (newarch / oldarch) which get loaded accordingly to a newArchEnabled flag in build.gradle and then a one SharedImpl file which you can share between implementations.

However, iOS is based on creating a new .mm files which are implementing Codegen generated protocols. Depending on what’s your library doing you may need to create separate implementations for new / old arch or share code between them.

Using Swift
Both of the libraries I’ve worked on haven’t used Swift. But, unfortunately, it’s not officially supported at the moment. The official Meta team statement is that they are “looking into it.” Codegen generates native ObjC++ files (.mm) which are tricky to reference from Swift files.

There is a great twitter thread from Mateusz Mędrek on his experiences.
https://twitter.com/mateusz1913/status/1574150706382229511?ref_src=twsrc%5Etfw%7Ctwcamp%5Etweetembed%7Ctwterm%5E1574150706382229511%7Ctwgr%5E55a5ee86f092d9174c627003f86a76763dd8cb6d%7Ctwcon%5Es1_&ref_url=https%3A%2F%2Fwww.callstack.com%2Fblog%2Fmigrating-a-react-native-library-to-the-new-architecture

Using Kotlin
When we were migrating react-native-pager-view I had lots of build issues which resulted from using Kotlin. Due to mixing Java with Kotlin, Codegen created files which were not included. So we have added a temporary workaround which may be useful in case you are also using Kotlin in your library. Check it out here:

sourceSets {
    main {
      if (isNewArchitectureEnabled()) {
          java.srcDirs += [
            "src/fabric/java",
            "${project.buildDir}/generated/source/codegen/java"
          ]
      } else {
          java.srcDirs += ["src/paper/java"]
      }
    }
  }

snippet.javascript hosted with ❤ by GitHub
snippet source code

Custom component state with C++
In some use cases Codegen isn’t enough - it’s a good starting point but It wasn’t designed to cover all the edge cases. So if your native component would like to update its frames in a synchronous way, you will need to add custom C++ state.

I haven’t added custom shadow nodes to react-native-slider in C++ yet (it’s scary but it’s on my to do list 😄). We have lots of great developers working on improving the New Architecture here at Callstack. My colleague Piotr Trocki together with Nicola Corti created a sample repository which will help you set this up. Right know the guide only covers Fabric, yet there is already an open issue to support Turbo Modules.

If you are afraid of C++ you can make use of the good old bridge as it’s still being initialized. But keep in mind that one day there will be bridgeless mode added.

Build times
While I was working on migration of react-native-slider we were using react-native 0.69 which had a major flaw in terms of build times. When it was time to create a fresh build without any cache, I could go and make myself a coffee ☕️ and then go for a walk. It took around 15-20 minutes. The good thing is that the community have added an --active-arch-only flag which will decrease your build times even 3x. And the core team is actively working on bringing the build times down by leveraging prebuilt artifacts outside of NPM.

https://twitter.com/o_kwasniewski/status/1585270027942502404?ref_src=twsrc%5Etfw%7Ctwcamp%5Etweetembed%7Ctwterm%5E1585270027942502404%7Ctwgr%5E89ce2dd0d0d74ac26d77a1ff1aea239484ef7c69%7Ctwcon%5Es1_&ref_url=https%3A%2F%2Fwww.callstack.com%2Fblog%2Fmigrating-a-react-native-library-to-the-new-architecture

Also keep in mind that you will need a pretty good machine to play around with new architecture. I saw few comments to my tweet indicating that building app (using new architecture) took them around 30 minutes. Of course once the build is cached it will be faster.

4. Now it’s time to release a migrated library

Every migrated library brings us closer and closer to finally enable the New Architecture in the production apps. Meta is using Fabric in their Facebook app since last year, but most of us are probably still blocked by the libraries that don’t have support for the New Architecture yet. If you want to track the status of migration for libraries, there is a dedicated discussion page. And if you are working on migrating your library, also add it there so it will be listed in the React Native Directory as a library that supports the New Architecture.

Try React Native Slider with Fabric

Create a new app using React Native CLI: npx react-native init NewArchApp
Add a React Native slider yarn add react-native-slider
[iOS] Run RCT_NEW_ARCH_ENABLED=1 pod install inside ios folder
[Android] Set newArchEnabled=true in gradle.properties

In the New Architecture mode, components that are not yet compatible will show a red box: Unimplemented component: <ComponentName>, and you will likely notice them. In that case, please let the library maintainers know about it.

Here is an example of not yet fabric ready LottieAnimationView:

Summary

Even though the React Native New Architecture is out there for a good while now, it’s still a challenge to do migrations, especially Fabric. The React Native core team put a good amount of work into making this effort easier. There’s a lot new documentation and up-to-date repositories on how to migrate both libraries and apps. And it’s still not enough. We keep finding the gaps in the official docs and often need to dive into the source code and commit history to figure out the rationale behind some API decisions.

Nicola Corti from the core team frequently mentions at conferences and podcasts that now it is the best time for apps to migrate. That’s because now they have a dedicated capacity to help the community solve their app and library problems in a close cooperation. They can’t promise whether they’ll have this capacity in a year from now.

At Callstack, together with my fellow developers, we often took this opportunity to reach out directly to the core team members, be it around the New Architecture’s autolinking, or migrating Slider, PagerView and Bob. And they are always utterly helpful, even though not available on-demand.

Although this may not be the best time for your app to adopt the New Architecture, I strongly encourage you to try. Turn on the build flag, check which components and modules are missing support. Post your problems and findings in a github discussion group. The New Architecture is the biggest thing that has happened to React Native since its inception. Get involved 🙂

This article was originally published at callstack.com on November 3, 2022.

Stripe Identity: ID Authentication Made Simple

Callstack Engineers — Fri, 04 Nov 2022 12:00:47 +0000

by Jan Jaworski

What is Stripe Identity?

There’s no easier way to verify identities than Stripe Identity. It lets you programmatically confirm the identity of users around the globe by scanning an image of an official form of ID, so you can prevent attacks from fraudsters while minimizing friction for legitimate payments.

Stripe Identity is an open source React Native wrapper for the native Stripe SDKs. The idea is to compare your Face ID with images of you and your IDs by means of biometric technology.

With the Stripe Identity React Native SDK, you can confidently verify the authenticity of ID documents from over 33 countries in your React Native application.

How to use the Stripe Identity React Native SDK

To verify your user’s identity, you need to have a document upload sheet displayed in your application. There are few steps to do that. First of all, you have to install Stripe Identity React Native SDK.

The next step is to set up a server to create a VerificationSession, which is the programmatic representation of the verification. For security reasons, the VerificationSession API is not directly accessible from the mobile client. Instead, your server provides the SDK with an ephemeral key—a short-lived API key with restricted access to the VerificationSession API.

You can think of an ephemeral key as a session authorizing the SDK to retrieve and update a specific VerificationSession object for the duration of the session. After successfully creating a VerificationSession and ephemeral key, send the VerificationSession id and ephemeral key secret to the client to show the document upload sheet.

The third step is to show the “document upload” sheet to the user. With Stripe Identity React Native, you can do this in two ways - via a hook called useStripeIdentity, or a method called presentIdentityVerificationSheet. That depends on whether you want to use it in functional or class based components.

You can find example code in the repository or integration guide.

Getting started with the useStripeIdentity hook

The easiest way to use the SDK is to import the useStripeIdentity hook directly in a functional component. You should pass the necessary information you fetched from your server directly to the hook.

import React from "react";
import { View, Button, Text, Image } from "react-native";
import { useStripeIdentity } from "@stripe/stripe-identity-react-native";

// brand logo that needs to be passed to Stripe Identity hook
import logo from "./assets/{{YOUR_BRAND_LOGO}}.png";

// simplified example of fetch function for Stripe Identity
// it can be replaced with more robust implementation that handles error handling, analytics, etc.
// other fetching libraries like Axios can be used as a replacement for native fetch()
const fetchVerificationSessionParams = async () => {
 try {
   const data = await fetch(
     `${YOUR_SERVER_BASE_URL}/create-verification-session`,
     {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
       }
     }
   );
   const json = await data.json();
   return json;
 } catch (e) {
   return {};
 }
 };

// options needed to make correct request to Stripe Identity
const fetchOptions = async () => {
 const response = await fetchVerificationSessionParams();
 return {
   sessionId: response.id,
   ephemeralKeySecret: response.ephemeral_key_secret,
   brandLogo: Image.resolveAssetSource(logo)
 };
};

function VerifyScreen() {
 // hook provided by Stripe Identity SDK allows API consumers to get important states and values without too much work from their side.
 const { status, present, loading } = useStripeIdentity(fetchOptions);

 return (
   <View>
     <Button title="Verify" disabled={loading} onPress={present} />
     <Text>Status: {status}</Text>
   </View>
 );
}

code snippet 1.javascript hosted with ❤ by GitHub

The hook returns 3 fields: status (FlowCompleted, FlowCanceled, FlowFailed), loading boolean, or error, and a method: present. Use the present method to display a document verification sheet. Clicking the verify button will open a native modal view.

Using the Stripe Identity SDK without hooks

If you use class-based components or prefer to implement the SDK without using hooks in your RN application, you can import an async method called presentIdentityVerificationSheet and prepare your own implementation. You will pass the same parameters as with functional components.

This method returns a status and an optional error.

import React from "react";
import { View, Button, Text } from "react-native";
import { presentIdentityVerificationSheet } from "@stripe/stripe-identity-react-native";

const fetchVerificationSessionParams = async () => {
 //  same implementation as in function component
};

const fetchOptions = async () => {
 //  same implementation as in function component
};

class VerifyScreen extends React.Component {
 constructor(props) {
   super(props);
   this.state = { loading: false, status: undefined, error: undefined };
 }

 present = async () => {
   // without provided hooks implementation user has to manage error and loading states manually
   this.setState({ loading: true });
   const options = await fetchOptions();
   this.setState({ loading: false });
   const { status, error } = await presentIdentityVerificationSheet(options);
   this.setState({ status, error });
 };

 render() {
   return (
     <View>
       <View>
         {this.state.loading ? (
           <View>
             <Text>Loading...</Text>
           </View>
         ) : (
           <Button title="Verify Identity" onPress={this.present} />
         )}
       </View>
       <Text>Status: {this.state.status}</Text>
     </View>
   );
 }
}

code snippet 2.javascript hosted with ❤ by GitHub

Verifying results

Based on the status (FlowCompleted, FlowCancelled, FlowFails), you'll need to handle these outcomes in your application. Please refer to the official documentation to read more about setting up a webhook flow.

Error handling

When implementing such a critical feature for your app, it is important to correctly implement error handling and provide users with clear information about the source of the issue and how they should proceed. If the error is on their side, your application should tell the user what to do to fix the problem. If the problem is due to code or server issues, there should be a clear message saying it.

Stripe Identity SDK provides a number of statuses and messages that can be used to create robust error handling implementation in your application.

Both useStripeIdentity and presentIdentityVerificationSheet provide you with information about the errors.

TypeScript support

Stripe Identity React Native SDK provides TypeScript support - it’s actually written in TypeScript. If you use it in your RN project, you can also use the types that SDK provided - StripeError and IdentityVerificationSheetStatus. Both can be useful while using the method presentIdentityVerificationSheet.

Stripe Identity features

Stripe Identity SDK offers a number of features that allow you to quickly introduce identity verification in your app. It ensures a secure and law-compliant implementation that should cover most of you and your users’ needs.

Simplified security

It’s simple for you to securely collect your user’s personally identifiable information (PII) such as identity document images. Sensitive PII data is sent directly to Stripe Identity instead of passing through your server. More information in the integration security guide.

Automatic document capture

We automatically capture images of the front and back of government-issued photo ID to ensure a clear and readable image.

Prebuilt UI

We provide IdentityVerificationSheet, a prebuilt UI that combines all the steps required to collect ID documents, selfies, and ID numbers into a single sheet that displays on top of your app.

Automated verification

Stripe Identity's automated verification technology looks for patterns to help determine if an ID document is real or fake and uses distinctive physiological characteristics of faces to match your users' selfies to photos on their ID document.

Collected identity information is checked against a global set of databases to confirm that it exists. Learn more about the verification checks supported by Stripe Identity, accessing verification results, or integration guide on handling verification outcomes.

Summary

Stripe Identity was born to make the ID verification process faster and more efficient. Thanks to the technology used, online businesses can easily confirm their users’ identities. It’s a great convenience and, most importantly, a viable safety measure that should be widely adopted.

This article was originally published at callstack.com on October 28, 2022.

Setting up React Native Monorepo with Yarn Workspaces

Callstack Engineers — Fri, 14 Oct 2022 19:10:04 +0000

by Oskar Kwaśniewski

What is a monorepo?

A monorepo is a single repository that holds a multitude of projects with all their code and assets. While the projects can be related, they can be used independently by different teams.

Working with monorepos is very useful, especially when developing big and complex applications like super apps. Monorepos enable sharing the logic between a web app and a mobile app, for example.

In this article, we’re going to set up a basic structure for a monorepo in React Native.

Why use monorepo in React Native?

Thanks to react-native-web we can share every component so there’s no need to duplicate the code many times. This means easier dependency management, shorter CI times, and better collaboration between teams since the code can be shared.

The main advantage though is the possibility of sharing packages between React and React Native. Most of the time we decide to share only business logic, but thanks to React Native Web, we can also share some of the UI components.

Setting up Yarn workspaces

While setting up a monorepo, we have two options: we can either hoist the packages to the root level or prevent them from hoisting. Yarn workspaces have an option named nohoist which allows us to specify packages that aren’t hoisted. It depends on your use case but most of the time it’s better to hoist packages to the root level.

Alternatively, you can use npm workspaces, it should work the same.

Why it’s better to avoid using nohoist

Preventing packages from hoisting takes back the main advantage of monorepos which is sharing node_modules between repositories. When nohoist option is turned on, most of the time packages are duplicated inside the root level node_modules and inside the project level node_modules. Downloading packages multiple times can lead to longer CI/CD runs and higher costs.

Rearranging the project structure

In order to set up yarn workspaces, we need to restructure our project to suit the structure below. Projects need to be divided into separate folders and we should have root level package.json.

your-project
    packages
        web // <- React app
        mobile // <- React Native app
        shared // <- Shared (includes files shared between mobile/web)

plain1.txt hosted with ❤ by GitHub

Next, you should create a package.json file in the root directory of our project with this command: $ yarn init -y

It should look like this:

{
  "private": "true",
  "name": "example-app",
  "version": "1.0.0",
  "workspaces": [
    "packages/*"
  ]
}

codesnippet1.json hosted with ❤ by GitHub

Note that private: true is required because workspaces are not meant to be published.

In the workspaces section, we define a work tree. We can pass there an array of glob patterns that should be used to locate the workspaces. So in the example above, every folder inside packages is defined as a workspace.

Creating a React Native project

Use command below to create a React Native project inside the packages folder:

$ npx react-native init ExampleApp --directory mobile --template react-native-template-typescript

plain2.txt hosted with ❤ by GitHub

In order for our app to work in a monorepo structure, we need to make sure that config files are pointing to the root level node_modules due to package hoisting.

iOS setup

Change paths at the top of your Podfile
- require_relative '../node_modules/react-native/scripts/react_native_pods'
- require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
+ require_relative '../../../node_modules/react-native/scripts/react_native_pods'
+ require_relative '../../../node_modules/@react-native-community/cli-platform-ios/native_modules'

target 'ExampleApp' do
...

path1.diff hosted with ❤ by GitHub

Regenerate Pods, by entering the command below in the packages/mobile folder:

$ cd ios && pod install

plain3.txt hosted with ❤ by GitHub

Next open Xcode and inside Project settings > Build Phases open “Bundle React Native code and images”

Change the path of the script:

set -e

- WITH_ENVIRONMENT="../../node_modules/react-native/scripts/xcode/with-environment.sh"
- REACT_NATIVE_XCODE="../../node_modules/react-native/scripts/react-native-xcode.sh"
+ WITH_ENVIRONMENT="../../../node_modules/react-native/scripts/xcode/with-environment.sh"
+ REACT_NATIVE_XCODE="../../../node_modules/react-native/scripts/react-native-xcode.sh"

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"

path2.diff hosted with ❤ by GitHub

It should look like this:

Android setup

React Native ≥ 0.71

Uncomment the line with reactNativeDir and point it to root node_modules

// packages/mobile/android/app/build.gradle

react { 
+  hermesCommand = "../../node_modules/react-native/sdks/hermesc/%OS-BIN%/hermesc"
}

android 1.diff hosted with ❤ by GitHub

In top-level build.gradle add this:

allprojects {
    project.pluginManager.withPlugin("com.facebook.react") {
        react {
            reactNativeDir = rootProject.file("../../../node_modules/react-native/")
            codegenDir = rootProject.file("../../../node_modules/react-native-codegen/")
        }
    }
}

android 2.shell hosted with ❤ by GitHub

and inside: packages/mobile/android/settings.gradle

+ apply from: file("../../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
+ includeBuild('../../../node_modules/react-native-gradle-plugin')

android 3.diff hosted with ❤ by GitHub
‍
React Native ≤ 0.71

Fix paths inside packages/mobile/android/build.gradle
Change url of the React Native Android binaries, and Android JSC in the allprojects section:

allprojects {
    repositories {
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
-            url("$rootDir/../node_modules/react-native/android")
+            url("$rootDir../../../../node_modules/react-native/android")
        }
        maven {
            // Android JSC is installed from npm
-            url("$rootDir/../node_modules/jsc-android/dist")
+            url("$rootDir../../../../node_modules/jsc-android/dist")
        }
                ...
    }
}

code snippet2.diff hosted with ❤ by GitHub

Fix packages/mobile/android/settings.gradle
Here we also need to change paths to the root node_modules folder.

rootProject.name = 'example-app'
- apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
- includeBuild('../node_modules/react-native-gradle-plugin')
+ apply from: file("../../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
+ includeBuild('../../../node_modules/react-native-gradle-plugin')
include ':app'
if (settings.hasProperty("newArchEnabled") && settings.newArchEnabled == "true") {
    include(":ReactAndroid")
-   project(":ReactAndroid").projectDir = file('../node_modules/react-native/ReactAndroid')
+   project(":ReactAndroid").projectDir = file('../../../node_modules/react-native/ReactAndroid')
    include(":ReactAndroid:hermes-engine")
-   project(":ReactAndroid:hermes-engine").projectDir = file('../node_modules/react-native/ReactAndroid/hermes-engine')
+   project(":ReactAndroid:hermes-engine").projectDir = file('../../../node_modules/react-native/ReactAndroid/hermes-engine')
}

path3.diff hosted with ❤ by GitHub

Next go to packages/mobile/android/app/build.gradle
Inside the project.ext.react we need to add property cliPath so it will override the default location of the cli.

project.ext.react = [
+    cliPath: "../../../../node_modules/react-native/cli.js",
]

plain4.txt hosted with ❤ by GitHub

In the same file, change this line: apply from: "../../node_modules/react-native/react.gradle" to point to root level node_modules as well.

- apply from: "../../node_modules/react-native/react.gradle"
+ apply from: "../../../../node_modules/react-native/react.gradle"

path4.diff hosted with ❤ by GitHub

And also change: inside packages/mobile/android/app/build.gradle

- apply from: file("../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesAppBuildGradle(project)
+ apply from: file("../../../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesAppBuildGradle(project)

path5.diff hosted with ❤ by GitHub

If you are using or planning to use the new architecture, we also need to change a few lines in the isNewArchitectureEnabled() if statement*.*

if (isNewArchitectureEnabled()) {
            // We configure the NDK build only if you decide to opt-in for the New Architecture.
            externalNativeBuild {
                ndkBuild {
                    arguments "APP_PLATFORM=android-21",
                        "APP_STL=c++_shared",
                        "NDK_TOOLCHAIN_VERSION=clang",
                        "GENERATED_SRC_DIR=$buildDir/generated/source",
                        "PROJECT_BUILD_DIR=$buildDir",
-                       "REACT_ANDROID_DIR=$rootDir/../node_modules/react-native/ReactAndroid",
-                       "REACT_ANDROID_BUILD_DIR=$rootDir/../node_modules/react-native/ReactAndroid/build",
-                       "NODE_MODULES_DIR=$rootDir/../node_modules"
+                       "REACT_ANDROID_DIR=../../node_modules/react-native/ReactAndroid",
+                       "REACT_ANDROID_BUILD_DIR=../../node_modules/react-native/ReactAndroid/build",
+                       "NODE_MODULES_DIR=../../node_modules"
                    cFlags "-Wall", "-Werror", "-fexceptions", "-frtti", "-DWITH_INSPECTOR=1"
                    cppFlags "-std=c++17"
                    // Make sure this target name is the same you specify inside the
                    // src/main/jni/Android.mk file for the `LOCAL_MODULE` variable.
                    targets "okwasniewskionboarding_appmodules"
                }
            }

code snippet 3.diff hosted with ❤ by GitHub

Configure Metro

We’re almost done with setting up the project. The last thing in the React Native app is to add watchFolders so metro knows where the linked node_modules are. The shared modules are symlinked by yarn, and since metro doesn’t follow symlinks we need to explicitly say it where the linked node_modules are.

const path = require("path");

// packages/mobile/metro.config.js
module.exports = {
  watchFolders: [
    path.resolve(__dirname, '../../node_modules')
  ],
};

code snippet4.javascript hosted with ❤ by GitHub

Setting up a shared package

To keep it simple, we’re going to share only one function across React Native and React.

Inside the packages/shared, create a new package.json file with the command:

$ yarn init -y

code snippet5.javascript hosted with ❤ by GitHub

The shared library is in typescript, so we need to set up a build step with the typescript compiler (tsc).

The build step uses rimraf which is a small utility for node that allows us to remove a folder, and then build the app with tsc.

postinstall indicates that our shared dependency will build automatically after installing.

{
  "name": "@example-app/shared",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "build": "rimraf dist && tsc",
    "postinstall": "yarn build",
        "watch": "tsc --watch"
  },
    "dependencies": {
        "react-native": "0.69.1",
        "react": "18.0.0"
    },
    "devDependencies": {
        "rimraf": "^3.0.2",
        "typescript": "^4.4.4"
    },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

code snippet6.json hosted with ❤ by GitHub

Note: The package name is really important, because it will indicate from where we will import our module.

It’s also important to add all packages and keep the exact same version used in a shared project and target projects.

Next we need to configure tsconfig.json where we can define our build settings.

Here is an example config file:

// packages/shared/tsconfig.json
{
    "compilerOptions": {
      "target": "es6",
      "lib": ["dom", "dom.iterable", "esnext"],
      "skipLibCheck": true,
      "esModuleInterop": true,
      "allowSyntheticDefaultImports": true,
      "strict": true,
      "forceConsistentCasingInFileNames": true,
      "module": "commonjs",
      "outDir": "dist", // <- Directory of generated output
      "moduleResolution": "node",
      "resolveJsonModule": true,
      "experimentalDecorators": true,
      "strictPropertyInitialization": false,
      "declaration": true,
      "jsx": "react"
    },
  }

code snippet7.json hosted with ❤ by GitHub

Next, let’s create an index.ts file inside the packages/shared folder.

export const add = (a: number, b: number) => {
    return a + b;
}

code snippet8.javascript hosted with ❤ by GitHub

Run this command to build the package:

$ yarn build

code snippet9.javascript hosted with ❤ by GitHub

Next, we need to add this package as a dependency in our react native project. So inside packages/mobile/package.json add @example-app/shared as a dependency.

Note that the version of the package must match the version specified inside packages/shared/package.json. Previously we defined that @example-app/shared version is 1.0.0.

// packages/mobile/package.json

"dependencies": {
    "@example-app/shared": "1.0.0",
    ...
  },

code snippet10.json hosted with ❤ by GitHub

And also inside the metro.config.js

// packages/mobile/metro.config.js

module.exports = {
  watchFolders: [
    path.resolve(__dirname, '../../node_modules'),
+   path.resolve(__dirname, '../../node_modules/@example-app/shared'),
  ],
};

code snippet11.javascript hosted with ❤ by GitHub

Now, run this command in the root directory, so yarn will set up symlinks for your shared package.

$ yarn

code snippet12.javascript hosted with ❤ by GitHub

Right now we should be able to import the add function inside React Native app.

import React from 'react';
import {Text, TouchableOpacity, View} from 'react-native';
import {add} from '@example-app/shared';


const App = () => {
  return (
    <View>
      <TouchableOpacity
        accessibilityRole="button"
        onPress={() => {
          console.log(add(1, 2));
        }}>
        <Text>Run Add function</Text>
      </TouchableOpacity>
    </View>
  );
};

export default App;

code snippet13.javascript hosted with ❤ by GitHub

Setting up a React project

In order to set up a React project, execute the command below inside packages/web:

$ npx create-react-app . ExampleApp --template typescript

code snippet14.javascript hosted with ❤ by GitHub

Add @example-app/shared dependency:

// packages/web/package.json
"dependencies": {
    "@example-app/shared": "1.0.0",
    ...
  },

code snippet15.json hosted with ❤ by GitHub

And we can import and use the shared package:

import React from 'react';
import {add} from '@example-app/shared';


const App = () => {
  return (
    <div>
      <button onClick={() => console.log(add(1,2))}>Run add function</button>
    </div>
  );
};

export default App;

code snippet16.javascript hosted with ❤ by GitHub

Sharing UI components with React Native Web

In order to share UI components, we need React Native Web which provides a compatibility layer between React DOM and React Native.

Installation steps

Install react-native-web:

$ yarn add react-native-web

code snippet17.txt hosted with ❤ by GitHub

Install babel-plugin-react-native-web

$ yarn add -D babel-plugin-react-native-web

code snippet18.txt hosted with ❤ by GitHub

Modify shared package to export React Native component

First inside packages/shared, create a new file called TestComponent.tsx

import { Text, View } from "react-native";
import React from "react";

const TestComponent = () => {
  return (
    <View>
      <Text>TestComponent</Text>
    </View>
  );
};

export default TestComponent;

code snippet 19.javascript hosted with ❤ by GitHub

Next export it from the index.ts file:

export const add = (a: number, b: number) => {
    return a + b;
}

export { default as TestComponent } from './TestComponent.tsx'

code snippet20.javascript hosted with ❤ by GitHub

Rebuild the shared package inside packages/shared folder:

$ yarn build

code snippet21.txt hosted with ❤ by GitHub

And now we should be able to use TestComponent inside a React app.

import React from 'react';
import {add, TestComponent} from '@example-app/shared';


const App = () => {
  return (
    <div>
      <button onPress={() => console.log(add(1,2))}>Run add function</button>
            <TestComponent/> // <- React Native component inside React app! 
    </div>
  );
};

export default App;

code snippet22.javascript hosted with ❤ by GitHub

To sum up

Setting up a monorepo can be tricky, but it pays off in the long run! You can easily share all of your code and assets between React and React Native.

Using a monorepo is growing in popularity - there is even an open proposal to migrate react-native repository to monorepo. Find out more about React Native monorepo on github.

This article was originally published at callstack.com on October 11, 2022.

A Comprehensive Guide to Mock Service Worker (MSW)

Callstack Engineers — Thu, 13 Oct 2022 16:57:33 +0000

by Aleksandra Desmurs-Linczewska

Mock Service Worker is an API mocking tool that lets you mock by intercepting requests on the network level. You can reuse the same mock definition for testing, development, and debugging.

MSW is delightful to adopt. Plus, it makes testing components with network requests a pleasure.

In this article, I’d like to share some best practices for working with MSW for basic and more advanced problems.

When to use a Mock Service Worker?

Has this ever happened to you?

You’ve finally gotten the green light to spend some writing tests!

This sprint is calm, but you remembered all too clearly that disastrous release a few weeks ago. The entire team had to drop everything and fix bugs.

Your repo has around 20% test coverage, and everyone agrees that it’s too little, but there’s never enough time to write tests. You write your features, get an LGTM on the PR, and move on.

But this release will be different!

You have a dedicated task, a couple of story points, and a jug of coffee to get this done right. You know the feature you’re about to test very well; you wrote most of it. You set out to mock the component and pass some props.

The tests fail.

No worries, that was only the first try, my friend! You re-check what needs testing, add some missing mocks, and maybe throw a jest.spyOn in there. You’re so proud of your accomplishment!

yarn test – another fail.

You dig deeper and realize your component depends on a network request returning some data.

Ok, don’t panic.

Let’s see how other tests in the codebase manage this. You find tests mocking axios, other ones' mock fetch, and wait; there are also some global files mocking resolved values and network errors?

You sweat a little, add many lines of code to your test, and ponder briefly if all of them are necessary. You notice tests unrelated to your changes started failing! You start feeling like the people in the first half of any infomercial.

…and you probably think: there has to be a better way! That’s when Mock Service Worker comes in handy.

The basic guide to Mock Service Worker (MSW)

Mock Service Worker intercepts real network requests that your tests make.

The components in your tests think they are talking with the real API, which means you can test their real functionality (as opposed to testing contained, mock functionality). If you don’t feel convinced about this approach just yet, I invite you to read Kent C. Dodd’s excellent blog post: Stop Mocking Fetch.

Let’s see this magical library in action. As with any new dependency, you need to start by adding it to your project: npm install msw --save-dev or yarn add msw --dev

Once the installation finishes, you will have to define your request handlers. MSW documentation suggests creating them in a file called mocks/handlers.js. Depending on your project, you can create REST or GraphQL handlers. MSW request handlers aim to hold instructions for specific API endpoints.

Let’s take a look at an example REST request handler:

// src/mocks/handlers.js
import { rest } from "msw";

export const handlers = [
  // Handles a POST request
  rest.post("https://fancy-app.com/postToThisEndpoint", (req, res, ctx) => {
    return res(
      // Respond with a 200 status code
      ctx.status(200)
    );
  }),

  // Handles a GET request
  rest.get("https://fancy-app.com/getSomeData", (req, res, ctx) => {
    return res(
      ctx.status(200),
      ctx.json({
        data: "fancy data string",
      })
    );
  }),
];

msw.test.tsx hosted with ❤ by GitHub

We start by importing the rest function from MSW, then create an array of API endpoints we want to handle.

We can add anything we would like to this array. We can mock an error response; we can mock correct or faulty data objects. Remember to use absolute request URLs since we will use those request handlers in a NodeJS environment.

The only caveat here is that if you add multiple handlers for one API endpoint, the last one in the array will be the only one that’s actually used. But more on that later.

Once you have a few handlers ready, it is time to let your test suite know about them. We will need to set up a request mocking server and run it with our tests. This may sound scary, but don’t worry; the server setup file is three lines long.

Let’s create a new file called server.js:

// src/mocks/server.js
import { setupServer } from 'msw/node'
import { handlers } from './handlers'

// This configures a request mocking server with the given request handlers.
export const server = setupServer(...handlers)

msw.test.2.tsx hosted with ❤ by GitHub

We have to import the setupServer function from msw/node and pass the previously created request handlers to that function.

I don’t know about you, but this is the simplest mock server setup I have ever seen!

The very last step is running the mock server when you run your tests.

This step depends heavily on your project setup. There are various ways to set up and configure Jest, and this blog post will not try to cover all of them.

Instead, I’ll talk about the setup I’ve seen the most often: using a dedicated setupTests.js file, which is called through Jest’s setupFilesAfterEv.

If that’s the case in your project, congratulations! You only need to add the following lines:

// src/setupTests.js
import { server } from './mocks/server.js'
// Establish API mocking before all tests.
beforeAll(() => server.listen())

// Reset any request handlers that we may add during the tests,
// so they don't affect other tests.
afterEach(() => server.resetHandlers())

// Clean up after the tests are finished.
afterAll(() => server.close())

msw.test.2.tsx hosted with ❤ by GitHub

If you prefer to test MSW quickly in a single test file, you can do so as well.

It is possible to use the mock server directly anywhere you would like. This means you can skip all the steps above (except for the installation, let’s not get carried away!) and write something like this in your test file:

// __tests__/FancyPage.test.js
import { setupServer } from "msw/node";
import { FancyComponentWithAPICall } from "../FancyComponentWithAPICall";

const server = setupServer(
  rest.get("https://fancy-app.com/getSomeData", (req, res, ctx) => {
    return res(ctx.json({ data: "return this string" }));
  })
);

describe("<FancyComponentWithAPICall />", () => {
  beforeAll(() => server.listen());
  afterAll(() => server.close());
  test("displays data from backend", async () => {
    // Render components, perform requests, receive mocked responses.
  });
});

msw.test.4.tsx hosted with ❤ by GitHub

This has all been fun and games so far, don’t you think?

Going through the setup takes less than an hour. Honestly, going through the official MSW documentation takes less than an hour!

If you’re working on a project that’s not too big, you can stop reading now, pat yourself on the back, and look at all those green check marks on your tests.

The advanced guide to Mock Service Worker

If you are working on a big application, maybe a robust dashboard, or an e-commerce website, you realize the basic setup presented above won’t cut it.

The handlers array will soon become a 10-thousand line mess. People may add mock servers in random tests, making debugging errors difficult.

My team and I have faced those issues, and here’s how we decided to tackle them.

As stated above, the biggest issue in a big app using MSW is the handlers' files becoming unreadable. We tackled this issue by dividing the handlers’ files into separate, feature-related files.

Now, instead of a single, long handlers.js, we had something in the shape of the following structure:

src
│
└───tools
|   └───jest
│   │   commonMswHandlers.js
│   │   server.js 
|   |   setupTests.js
│
└───featureA
│   │   FeatureA.js
|   |
|   └───__tests__
│       │   FeatureA.test.js
│   │
│   └───msw
│       │   mswHandlers.js
│   
└───featureB
│   │   FeatureB.js
|   |
|   └───__tests__
│       │   FeatureB.test.js
│   │
│   └───msw
│       │   mswHandlers.js

msw-test.5.tsx hosted with ❤ by GitHub

A few API endpoints which were commonly needed for the tests and did not clearly fit any feature were left in the commonMswHandlers.js file.

Once we’ve effectively sliced the handlers array, we started wondering how these specific request handlers should be consumed. As we saw above, we could let the test authors import setupServer with specific handlers directly in the test files.

However, this quickly became quite verbose. We decided to create helper functions in our mswHandlers.js files. An example file would look like this:

// src/FancyHomepageFeature/msw/mswHandlers.js

import { rest } from 'msw';
// import the server created for the entire test suite
// this mock server includes commonMswHandlers
import { server } from '../tools/jest/server';

const homeHandlers = [
  rest.get('https://fancy-app.com/homepage-data', (req, res, ctx) => {
    return res(
      ctx.json({
        contents: [
          {
            banner: 'Fancy Banner'
          },
        ],
      })
    );
  }),
];

export const setupHomeHandlers = () => {
  server.use(...homeHandlers);
};

msw.test.6.tsx hosted with ❤ by GitHub

As you can see in the code above, we’re using the server.use() function. This function prepends request handlers to the current server instance. This means we are using everything that has been set up in the tools/jest/server.js file, and we’re adding a specific request handler for a specific URL.

Now, to use this helper function in a test, the test author would need to write something like this:

// src/FancyHomepageFeature/__tests__/FancyHomePage.test.js
import { FancyHomePage } from "../FancyHomePage";
import { setupHomeHandlers } from "./msw/mswHandlers";

describe("<FancyHomePage />", () => {
  beforeEach(() => setupHomeHandlers());
  test("displays homepage data", async () => {
    // Render homepage with backend data
  });
});

msw.test.7.tsx hosted with ❤ by GitHub

The test author must import the server helper and run it in a beforeEach block.

Tests in this particular test suite will now look into the homeHandlers array when the components need something from the https://fancy-app.com/homepage-data endpoint, while other test suites remain unaffected by this change.

Testing errors

What if you would like to test that your website can handle network errors on specific endpoints?

Let’s add another helper function to the FancyHomepageFeature/msw/mswHandlers.js file:

// src/FancyHomepageFeature/msw/mswHandlers.js

import { rest } from 'msw';
import { server } from '../tools/jest/server';

//...

export const setupFaultyHomeHandlers = () => {
  server.use(
    rest.get('https://fancy-app.com/homepage-data', (_req, res, ctx) => {
      return res(ctx.status(200), ctx.json({weirdDataType: 'something went wrong'}));
    }),
  );
};

export const setupFailedHomeHandlers = () => {
  server.use(
    rest.get('https://fancy-app.com/homepage-data', (_req, res) => {
      return res.networkError('Failed to connect');
    })
  );
};

msw.test.8.tsx hosted with ❤ by GitHub

We can add tests for the scenarios described above: what should happen if the server returns a successful response, but the values are unexpected? How should the website behave if there is a network error?

Let’s see those tests in action:

// src/FancyHomepageFeature/__tests__/FancyHomePage.test.js
import { FancyHomePage } from "../FancyHomePage";
import {
  setupHomeHandlers,
  setupFaultyHomeHandlers,
  setupFailedHomeHandlers,
} from "./msw/mswHandlers";

describe("<FancyHomePage />", () => {
  beforeEach(() => setupHomeHandlers());
  test("displays homepage data", async () => {
    // Render homepage with backend data
  });
});

describe("<FancyHomePage /> - faulty data", () => {
  beforeEach(() => setupFaultyHomeHandlers());
  test("displays readable error when receiving unexpected data", async () => {
    // Render homepage with error information
  });
});

describe("<FancyHomePage /> - network error", () => {
  beforeEach(() => setupFailedHomeHandlers());
  test("displays network error", async () => {
    // Render homepage with network error information
  });
});

msw.test.8.tsx hosted with ❤ by GitHub

Request handler overrides

If you read the MSW documentation carefully, you may be tempted to use the one-time override (res.once()) for testing errors.

We have tried using this strategy in our codebase. We have found that using res.once() is counter-intuitive to the test author. If the test setup includes this one-time override, but the test suite has more than one test, only the first test will behave as expected.

It may take the test author quite some time and great detective work to figure out that all his tests were correct, but the MSW handlers were prepared to handle only one request. If I was ever to use res.once(), it would only be directly in a test file, where it’s easily visible, and never in setup files.

Response object overrides

There is another type of override that I do recommend using - response object overrides.

Let’s say you would like to test your network request with different, successful responses. You could write separate functions using server.use(), but that’s a lot of repetitive work.

One of my colleagues, Jan Jaworski, came up with a very elegant solution to this problem. He created a helper function that could accept override data and use it in the response object thanks to the spread operator.

The function looked roughly like this:

export const setupSmartMswHelper = (override = {}) => {
  server.use(
    rest.get("https://fancy-app.com/return-some-data", (req, res, ctx) => {
      return res(
        ctx.status(200),
        ctx.json({
          fancyData: "Im so fancy!",
          moreData: "You already know",
          ...override,
        })
      );
    })
  );
};

msw.test.9.tsx hosted with ❤ by GitHub

Here’s how this helper function would be used in a test:

// src/FancyHomepageFeature/__tests__/FancyHomePage.test.js
//...
test("handles updated data", async () => {
  setupSmartMswHelper({
    moreData: "Cant you taste this gold?",
  });
  //...
});

msw.test.10.tsx hosted with ❤ by GitHub

This strategy is especially useful for big data objects we don’t want to re-type multiple times.

Testing errors - bonus content

Since we started testing network errors, we discovered the terminal output got polluted with many console.error messages. These error messages were expected, and we didn’t want them hiding real (as in UNexpected) errors.

We decided to add a console.error override in the Jest setup file:

// tools/jest/setupTests.js
const error = console.error;

console.error = (...args) =>
  // Suppress error messages regarding network error in tests
  /Error: Request failed with status code 500/m.test(
    args[0]
  )
    ? void 0
    : error(...args);

msw.test.11.tsx hosted with ❤ by GitHub

Thanks to this little function, we hid only the specific console errors we were sure about.

Summary

If you were to take away only one thing from this blog post, I sincerely hope it would be the notion that MSW is a great tool worth trying, even in a big project.

The solutions I described worked great in a real project. They may not be 100% ideal for your needs, but I hope you find some inspiration here to create the best, most comfortable, and developer-friendly test setup possible. At the end of the day, we all want to feel like the people at the end of infomercials, no?

This article was originally published at callstack.com on September 27, 2022.

How to Use Module Federation with Re.Pack 3

Callstack Engineers — Wed, 12 Oct 2022 08:54:45 +0000

by Jakub Binda & Andrew Andilevko

Introduction

Along with the release of Re.Pack v.3 there comes a huge update for the library - stable support for Module Federation.

This feature can be a powerful ally for development departments, especially when it comes to building complex apps with Micro-Frontend architecture, requiring multiple teams to deliver the whole thing.

In this article, you’ll find out

what’s the idea behind Module Federation,
and how to use Module Federation with Re.Pack 3.

The idea behind Module Federation

Module Federation was first introduced in Webpack 5. It’s a functionality that allows for code-splitting and sharing the split code parts (chunks) between loosely coupled applications. It also helps distributed teams to ship large applications faster. And, along with its latest update, Re.Pack 3 supports this functionality out-of-the-box.

Module Federation is one of the approaches to creating Micro-frontends architecture for your application which makes the functionality a great ally in, for example, super app development or creating features on demand.

Micro-frontends

Going briefly through the Micro-Frontends working scheme, there are:

the host app that runs firstly on the device,
and Micro-frontend (MFE) apps that are used by the host app.

That means each container (MFE) that is used by the host application could be deployed and maintained independently. The host apps are able to reflect changes in Micro-frontend immediately with no need for re-deploy until the changes are connected to the JS only.

Accessing remote JS code exposed by MFE is the key feature of Module Federation and the process is called Runtime Deployment.

Scheme 1. Module Federation in the app

How to use Module Federation in Re.Pack
If you are familiar with the Webpack config for Module Federation on the web environment, you will notice a similarity in the configuration using Re.Pack. The major difference is to take into account mobile platform / React Native specifics.

Let’s assume that we have the host application, two container applications, and one module used in the first container application. Each of the apps could be deployed independently, but all of them are bound using Webpack config.

The most interesting properties for us from this config are plugins. It is an array of all the required Webpack plugins. As you can see from the code snippet below, Re.Pack exports a ModuleFederationPlugin plugin that enables Module Federation functionality:

new Repack.plugins.ModuleFederationPlugin({
        name: 'host',
        shared: {
          react: {
            ...Repack.Federated.SHARED_REACT,
            requiredVersion: '17.0.2',
          },
          'react-native': {
            ...Repack.Federated.SHARED_REACT_NATIVE,
            requiredVersion: '0.68.2',
          },
        },
      })

Host app Webpack config Module Federation plugin.js hosted with ❤ by GitHub

Code snippet 1. Host app Webpack config Module Federation plugin

new Repack.plugins.ModuleFederationPlugin({
        name: 'app1',
        exposes: {
          './App': './src/App.tsx',
          './Text': './src/Text.tsx',
          './foo': './src/foo.ts',
        },
        shared: {
          react: {
            ...Repack.Federated.SHARED_REACT,
            eager: STANDALONE,
          },
          'react-native': {
            ...Repack.Federated.SHARED_REACT_NATIVE,
            eager: STANDALONE,
            requiredVersion: '0.68.2',
          },
        },
        remotes: {
          module1: 'module1@dynamic',
        },
      })

Remote Container 1 Webpack config Module Federation plugin.js hosted with ❤ by GitHub

Code snippet 2. Remote Container 1 Webpack config Module Federation plugin

new Repack.plugins.ModuleFederationPlugin({
        name: 'module1',
        exposes: {
          './Root': './src/Root.tsx',
          './baz': './src/baz.ts',
        },
        shared: {
          react: {
            ...Repack.Federated.SHARED_REACT,
            eager: STANDALONE,
          },
          'react-native': {
            ...Repack.Federated.SHARED_REACT_NATIVE,
            eager: STANDALONE,
            requiredVersion: '0.68.2',
          },
        },
        remotes: {
          app1: 'app1@dynamic',
        },
      })

Module app Webpack config Module Federation plugin.js hosted with ❤ by GitHub

Code snippet 3. Module app Webpack config Module Federation plugin

Going through the properties in the Module Federation plugin config, we can find the same ones in all of the apps. The name property is required, so we have to provide a unique name for each of our apps. Then, we will use it across the app for importing federated modules. The next common property is called shared. This array contains libraries and provides Webpack information regarding the libraries that should be shared in other applications. Also, they should have only one instance across the apps. Re.Pack provides default settings for React and React Native libraries in shared property.

So, until there are no more other libraries that should be shared, this property could be skipped. Dependency defined inside shared property might be also set as eager, which doesn’t put the modules in an async chunk, but provides them synchronously. That’s why it is combined with STANDALONE env which should be true when a remote app is run as its standalone version. Otherwise shared modules won’t be available in the initial bundle and the app is likely to crash.

As you can see on the code snippets above, all the plugins’ configs, except the host app, have exposes property. This is a list of modules that the application will export as remote to another application. The host app can only import remote modules and cannot have pre-defined ‘exposes’ or ‘remotes’ properties in Webpack config. However, MFEs can do both, expose and import remote modules at the same time.

While ‘exposes’ and ‘remotes’ properties are sufficient to support Module Federation in web apps, it’s not enough in a mobile environment. For Re.Pack, we have to add one more thing to handle fetched scripts from remote - a resolver. That’s why the ScriptManager was introduced in Re.Pack 3.

This is a manager that eases the resolution, downloading, and executing additional code from:

arbitrary JavaScript scripts
Webpack chunks
Webpack bundles
Webpack MF containers

To make ScriptManager resolve our remote scripts properly, we need to pass URLs to remote locations that those scripts will be available to fetch. They should be passed in proper object shape accepted by the createURLResolver method from the Federated module. In a very basic example, URLs might be hardcoded and the implementation is presented in the snippet below:

const resolveURL = Federated.createURLResolver({
  containers: {
    app1: 'http://localhost:9000/[name][ext]',
    app2: 'http://localhost:9001/[name][ext]',
    module1: 'http://localhost:9002/[name][ext]',
  },
});

ScriptManager.shared.addResolver(async (scriptId, caller) => {
  let url;
  if (caller === 'main') {
    url = Script.getDevServerURL(scriptId);
  } else {
    url = resolveURL(scriptId, caller);
  }

  if (!url) {
    return undefined;
  }

  return {
    url,
    cache: false,
    query: {
      platform: Platform.OS,
    },
  };
});

ScriptManager usage inside host application.ts hosted with ❤ by GitHub

Code snippet 4. ScriptManager usage inside the host application

However, there is an option to provide remote containers URLs dynamically. That means removing hardcoded URLs and fetching them from external service right in addResolver. Implementing the external service is optional but might become very useful on a larger scale. It allows to manage remote containers' URLs from outside of the host app and to switch them without the need for the host app re-deployement. Furthermore, it might help to handle fetching theproper version of MFEs inside the host app when a version management system is required.

ScriptManager.shared.addResolver(async (scriptId, caller) => {
  let url;
    const containers = await fetchURLs();
    const resolveURL = Federated.createURLResolver({
      containers,
    });

  if (caller === 'main') {
    url = Script.getDevServerURL(scriptId);
  } else {
    url = resolveURL(scriptId, caller);
  }

  if (!url) {
    return undefined;
  }

  return {
    url,
    cache: false,
    query: {
      platform: Platform.OS,
    },
  };
});

ScriptManager usage with dynamic URLs.js hosted with ❤ by GitHub

Code snippet 4.1. ScriptManager usage with dynamic URLs

After setting up the ScriptManager, we can use Module Federation functionality in the code. Here is the App.tsx file from the host application:

// eslint-disable-next-line import/no-extraneous-dependencies
import { Federated } from '@callstack/repack/client';
import React from 'react';
import { Text, SafeAreaView } from 'react-native';

const App1 = React.lazy(() => Federated.importModule('app1', './App'));
const App2 = React.lazy(() => Federated.importModule('app2', './App'));

export default function App() {
  return (
    <SafeAreaView>
      <Text>Host App</Text>
      <React.Suspense fallback={<Text>Loading app1...</Text>}>
        <App1 />
      </React.Suspense>
      <React.Suspense fallback={<Text>Loading app2...</Text>}>
        <App2 />
      </React.Suspense>
    </SafeAreaView>
  );
}

App.tsx code from host application.tsx hosted with ❤ by GitHub

The imports are async, so we should wait till the script will be downloaded, resolved by ScriptManager, and ready to use. So, we added React.lazy and React.Suspense syntax for handling async imports. React.Suspense has the fallback property that allows showing loader component to the users during loading scripts. To dynamically import remote modules in the host app, we also used the utility function importModule from Federated namespace, to provide the correct container and module name.

But, let’s take a look at the previously presented code from code snippet 2. There is remotes property under the Module Federation plugin in Webpack config. It helps to use the same syntax as for static imports inside app1 when importing modules from remote containers. Also, it’s worth mentioning that the component name needs to be prefixed with the remote container name. In this case, it’s module1/Root. According to what was written before - the remotes property can be used only in MFEs but anyway, it should still use React.Suspense when rendering remote containers:

import * as React from 'react';
import { Text } from 'react-native';

// eslint-disable-next-line import/no-unresolved
import Module1 from 'module1/Root';
import { foo } from './foo';

export default function App() {
  const [fooText, setFooText] = React.useState<string>('');

  React.useEffect(() => {
    (async () => {
      try {
        const fooText = await foo();
        setFooText(fooText);
      } catch {
        setFooText('Failed to get foo text');
      }
    })();
  }, []);

  return (
    <>
      <Text>App 1</Text>
      <React.Suspense fallback={<Text>Loading module1...</Text>}>
        <Module1 />
      </React.Suspense>
      <Text>{fooText}</Text>
    </>
  );
}

App.tsx code from app1 application.tsx hosted with ❤ by GitHub

Code snippet 6. App.tsx code from app1 application

In code snippet 3 there is also a defined remotes property that allows importing modules exposed by app1. This pattern is called bi-directional import. It won’t be possible outside the Module Federation when importing module B in module A and module A in module B at the same time because of circular dependencies. However, Module Federation allows it and it’s totally fine until both modules are imported from different MFEs. The only thing that developers have to keep in mind is that it might be easy to end up with an endless loop e.g. by calling one function by another as presented in the code snippet below:

let counter = 3;

export async function baz() {
  if (counter <= 0) {
    return 'end';
  }

  // eslint-disable-next-line import/no-unresolved
  const { foo } = await import('app1/foo');

  counter--;
  return `baz + ${await foo()}`;
}

baz function inside module1 which uses foo function from app1.tsx hosted with ❤ by GitHub

Code snippet 7. baz function inside module1 which uses foo function from app1

Please notice that the foo function from app1 uses baz function from module1. So as mentioned above, circular dependencies are working perfectly fine:

// eslint-disable-next-line import/no-unresolved
import { baz } from 'module1/baz';

export async function foo() {
  return `foo + ${await baz()}`;
}

foo function from app1.tsx hosted with ❤ by GitHub

Code snippet 8. foo function from app1

On code snippet 7, there is a counter variable that prevents an endless loop caused by calling foo by baz and baz by foo.

Summary

Module Federation is a powerful feature implemented in Webpack 5 and carefully migrated to Re.Pack 3 package.

Thanks to its functionalities, Module Federation can be a great ally for large development teams working on complex products, like super apps. The main benefits of Module Federation are

Independent deployment. No need to re-deploy host application on remote containers changes and re-deployment
Separating huge development teams. As every container could be deployed independently each team could work on their container
Sharing the code between tightly loosely coupled applications

This article was originally published at callstack.com on October 4, 2022.

Continuous App Performance Monitoring Made Simple with Reassure

Callstack Engineers — Mon, 10 Oct 2022 15:43:21 +0000

by Michał Pierzchała

Have you ever heard about entropy?

As Stephen Hawking framed it:

You may see a cup of tea fall off a table and break into pieces on the floor... But you will never see the cup gather itself back together and jump back on the table. The increase of disorder, or entropy, is what distinguishes the past from the future, giving a direction to time.

In other words: things will fall apart eventually when unattended.

But let’s not get too depressed or comfortable with things just turning into chaos naturally. We can and do fight back against it. We can exert effort to create useful types of order resilient enough to withstand the unrelenting pull of entropy by expending energy.

Let’s start from the beginning.

What does a development cycle look like?

When developing software, we feel entropy. That’s why we usually put extra effort into following some development cycle.

For example, we start with adding a new feature. During development, we sprinkle it with a bunch of tests. When we’re done, we send it to QAs. They accept it and promote our code to a production release channel. And we’re back to adding another feature.

That’s quite a simplified version of what we usually do. Because, among other things, we don’t take into account that wild bugs may appear!

Our experience tells us to keep it cool, identify the root cause, and add a regression test so it never breaks again. Then we send it to QA once again, ship it, and go back to adding features.

We’re happier with our workflow now; it works well. We’re adding feature after feature. Our app release cycle is so well designed that even adding ten new developers doesn’t slow us down. Until we take a look at our app reviews:

Why do you need to continuously monitor the performance of your app?

We realize that our perfect workflow based on Science™, our experience, and “best practices,” which was supposed to prevent our app from falling apart, is not resilient to particular bugs. Namely, performance regressions.

Our codebase doesn’t have the tools to fight these. We know how to fix the issues once spotted, but we have no way to spot them before they hit our users.

Coming back to our entropy example, in other words, we could say that performance will fall apart eventually when unattended. If we don’t do anything to optimize our app while adding new code and letting the time go by, it will certainly get slower.

We don’t know when it will happen. Maybe tomorrow, maybe in a week,or in a year.

If only there’s been an established way of catching some of the regressions early in the development process…

Wait a minute, there is!

How to monitor app performance regression?

With fully automated regression tests! Tests that run in a remote environment on every code change, and that already are a part of our development process.

Before we pick the best tool for the job, let’s consider the impact and what’s worth testing.

The most common React (Native) performance issues

As with test coverage, there’s a healthy ratio that we strive for to provide us with the best value for the lowest amount of effort. We want to target regressions that are most likely to hit our users.

At Callstack, we identified React Native performance issues our developers deal with daily.

Slow lists and images, SVGs, React Context misusage, re-renders, slow TTI, are among the most common ones. If we look at this list from the origin of the issue point of view, we’ll notice that a vast majority of these come from the JS side.

We estimate that most of the time our developers spend fixing performance issues, around 80%, originating from the JS realm, especially from React misusage. Only the rest is bridge communication overhead and native code – like image rendering or database operations – working inefficiently.

It’s fair to say that we expect to encounter these problems in both React web apps and React Native mobile apps.

We did our research and didn’t find any library allowing us to reliably write performance regression tests for React or React Native. We’d like to have it integrated with the existing ecosystem of libraries we’re using.

The perfect library for measuring performance regression should:

measure render times and count reliably,
have a CI runner,
generate readable and parseable reports,
provide helpful insights for code review, and
have a stable design based on React public API.

Using our experience from developing the React Native Testing Library, we created Reassure—a performance regression testing companion for React and React Native components. We developed it in partnership with Entain – one of the world’s largest sports betting and gaming groups.

How does Reassure work?

Reassure builds on top of your existing React Testing Library setup and sprinkles it with an unobtrusive performance measurement API.

It’s designed to be run on a remote server environment as a part of your continuous integration suite.

To increase the stability of results and decrease flakiness, Reassure will run your tests once for the current branch and another for the base branch.

In the near future, with sufficiently stable CI, we’ll be able only to run the tests once and compare the results with the ones from the past.

To ensure a delightful Developer Experience, Reassure integrates with GitHub to enhance the code review process. Currently, we leverage Danger.js as our bot backend, but in the future, we’d like to prepare a plug-and-play GitHub Action.

Let’s take a look at what it takes to incorporate Reassure into your regression testing pipeline.

Write performance regression tests

Before you write your first test, you need to install Reassure:

yarn add --dev reassure
# or 
npm install --save-dev reassure

Now you can start writing your performance tests. Let’s take a look at this example:

// counter.perf-test.tsx
test('Count increments on press', async () => {
  const scenario = async (screen: RenderAPI) => {
    const button = screen.getByText('Action');

    await screen.findByText('Count: 0’);
    fireEvent.press(button);
    fireEvent.press(button);
    await screen.findByText('Count: 2');
  };

  const stats = await measurePerformance(
    <Counter />, 
    { scenario, runs: 20 }
  );
  await writeTestStats(stats);
});

We created a new file with “.perf-test.tsx” extension that reuses our component test in a scenario function. It takes an optional screen argument which is, in fact, a return value of Testing Library’s render helper.

The scenario is then used by the measurePerformance method from Reassure, which renders our Counter component, in this case, 20 times, letting the React Profiler to measure render count and duration times for us. In the end, we call writeTestStats to save this data to the filesystem.

And that’s usually all you have to write. Copy-paste your existing tests, adjust, and enjoy your app being a little bit safer with every test.

Run Reassure

Now that you have your first performance regression test created, it’s time to run Reassure somehow! It’s important to mention that you need to measure the performance of two versions of your code – the current (modified one) and the baseline. Reassure will compare the two to determine whether there are any regressions in the current code version.

Since the goal is to run the performance tests on the CI environment, we want to automate this task. To do that, you will need to create a performance testing script, like this one:

# Gather baseline perf measurements
git switch main
yarn install --force
yarn reassure --baseline

# Gather current perf measurements & compare results
git switch -
yarn install --force
yarn reassure

And save it in your repository, e.g. as reassure-tests.sh.

The script switches to your base branch, installs dependencies, and runs yarn reassure --baseline to gather the base metrics. Once done, it switches back to your current feature branch, installs dependencies again, as those might have changed, and runs yarn reassure again.

See the performance test results

Having all that data, Reassure can present the render duration times as statistically significant or meaningless.

Apart from render times, another useful metric that may easily degrade is render counts, which we get for free from React Profiler.

All this information is stored in a JSON format for further analysis and Markdown for readability.

We use the markdown output as a source for the GitHub commenting bot powered by DangerJS.

This is by far our favorite and recommended usage of this tool, as it enriches the code review process while allowing us to alleviate the instability of the CI we’re using.

What have we learned from developing Reassure?

Developing Reassure has taught us some valuable lessons about

running benchmarks with Node.js, and
measuring precision in JavaScript.

Let’s dive into it!

Challenges of running benchmarks with Node.js

Running benchmarks is not a piece of cake even in non-JS environments, but it’s particularly tricky with Node.js.

The key is embracing stability and avoiding flakiness. Operating in a JavaScript VM, we need to considerJIT, garbage collection, and module resolution caching.

Then we have a cost of concurrency that our test runner embraces for execution speed. We need to pick what to average, what to percentile, and how to apply statistical analysis. And a lot more.

Running tests once or twice is not enough to make sure our measurement results make sense mathematically. Taking other things into account, ten times is a good baseline for our use case. Then, to determine the probability of the result being statistically significant, we need to calculate the z-score, which needs the mean value (or average), divergence, and standard deviation.

Reassure handles all of that for you, so you don’t even have to think about it.

What you probably didn’t know about measurement precision in JavaScript

Measurement precision is another tricky topic in the JS land.

React Profiler uses performance.now() API to reliably measure rendering time. Node.js implements the W3C recommendation, which—due to privacy concerns—requires a resolution of no less than 5 microseconds.

We can measure a 1 ms render with at least 0.5% error. This is usually good enough. But because many lighter components render faster than 1 ms, and due to the variable stability of the machine, we run them at least ten times anyway and let you configure that as well.

Now, module resolution caching is great for our Node.js apps.

But it bit us when developing the library. As it turned out, subsequent execution of the same component often resulted in even ten times slower runs. As you can imagine, averaging that would make the results unreliable. So we drop the slowest test as most likely it’s skewed by the lack of cache.

Wrapping Up

Even if you don’t have performance issues at the moment, they will appear sooner or later. We speak from our experience with many clients. Reassure will allow you to spot them once they appear.

With Reassure, you can

test whole screens or even screen sequences
perform component level tests are possible but often require more runs
reuse your RNTL tests if you have them, and
all established Testing Library practices apply, so let your tests resemble users’ behavior and avoid mocking anything other than I/O.

Due to their qualities, frontend perf tests seem to resemble end-to-end tests for our apps. And it makes sense to treat them as such in our testing trophies or pyramids.

Remember that performance is not a goal. It’s a path. Walk it with confidence.

Reassure is Open Source

Like all of the tools we build at Callstack, Reassure is an Open Source software, released under an MIT license. Feel free to check it out on GitHub to see the complete installation and usage guide. And if you liked it—star it!

We’re excited to see how you use it and how it helps you guard the performance of your apps. So don’t be afraid to hit the “Issues” tab to let us know.

And if you want to listen to a talk with me, Maciej Jastrzębski, and our host, Łukasz Chludziński, take a look at one of the episodes of The React Native Show.

Happy testing!

This article was originally published at callstack.com on September 21, 2022.

Why It’s Super to Have a Super App

Callstack Engineers — Mon, 16 Aug 2021 17:29:20 +0000

by Hanna Sobolewska

Most mobile users have a dedicated application for a particular service or function. The more services they want to use, the more apps they need to install. No wonder that in 2020 alone there were 218 billion app downloads (iOS App Store, Google Play and third-party Android stores combined) and the number is always growing.

What if a number of these apps got consolidated into one? This is exactly the idea behind a super app – an integrated ecosystem made of dedicated services called mini apps. And yes, like so many things in the world, it was made in China.

What is a super app?

A super app is a multi-purpose platform that offers a plethora of services through one mobile interface. The user can chat, check news, make daily purchases, call a taxi, and so on, and they don’t need to have separate apps to do the jobs. This is exactly a super app’s superpower: giving users the access to all functions in one place.

The whole concept could be compared to a huge shopping mall that rents its space to interested retailers. When using a super app, you don’t leave the building, you just move around its premises. The “mall” saves your preferences or payment details so each retailer knows how you want to pay and where they should deliver your purchase. Once introduced, all the details are there. That also means fewer registrations as only one sign-in is required.

Examples of super apps worldwide

The super app emerged in China. The very first one, WeChat, was initially created as a messaging app (a Chinese counterpart to WhatsApp), and it soon evolved into a marketplace of various services and offerings. Now there are hundreds of public services, mini programs, coupons, bill payment options, etc., available for over a billion WeChat users.

All-in-one applications took the Asian market by storm with apps such as Alipay, Grab, Gojek or Paytm, to name just a few. It soon became an international tech trend and now the key market players are either in the process of implementing a super app, e.g. Uber, or they are planning to upgrade to a super app, e.g. Paypal, Airbnb or Amazon.

Super apps – super opportunities

There are good reasons why most giants strive to build a one-stop portal. Having a super app comes with a wealth of benefits. To start with, it’s convenient for both the user and business owner. For the former one, it means the comfort of downloading one app to access a bunch of services and hit the big market. In practical terms, it also means less registration and login hassle.

For the latter one, it definitely means a long-term reduction of development and maintenance costs. Running a super app minimizes the challenges that might occur when developing and maintaining multiple apps. All in all, it means less effort made to reach a wider audience that is very likely to make in-app purchases you will earn from.

The biggest selling point, however, is the all-in-one experience itself. Creating a one-stop shop for all things users need on a daily basis is almost bound to succeed. With a good plan and team of trusted app developers, your success should be just a matter of time.

Developing super apps

Super apps have the potential to reshape the mobile marketing landscape – no wonder that more and more companies want to develop one! How to get started?

First of all, your super app still needs to focus on one main service so you need to make sure this is already settled. WeChat did start as a messaging app and over time it did evolve into a super app, but it never moved away from its original purpose. It’s still a communication tool after all – even way more advanced than it used to be.

What do you need to develop a super app, technically speaking? There’s no “one and only” path to doing it right. There are different approaches and solutions, depending on whether you want to go for native or cross-platform development.

Possible solutions you can adopt when designing a super app architecture:

Native Android application with Feature Delivery
Native iOS application with WebViews
Cross-platform React Native application with Metro
Cross-platform React Native application with Webpack and Re.Pack

Each solution addresses different needs and comes with different benefits. Given our experience, it’s better to adopt cross-platform solutions because native applications not only use different platform languages, but also require radically different architectures.

Only React Native allows us to leverage a truly cross-platform code splitting technique which enables super apps’ implementation. Because of Webpack’s widely used and battle-tested code splitting, we can easily introduce it into React Native applications with the help of Re.Pack.

Super future

Super apps are spreading rapidly nowadays. The model is gaining popularity in Latin America and Africa. Businesses from almost every market segment take interest in developing a super app. Even though the very definition of a super app may vary from continent to continent, the trend is there. And it’s there to stay!

The worldwide use of super apps is spurring a new era in online shopping, payments and communication. Among the big brands that are planning to jump on the bandwagon are also social media giants such as Facebook or Twitter. That clearly means the super app landscape is going to further evolve.

Summary

The super app quickly went mainstream in Asian countries – with a mobile-first population, homogeneous markets, blocked competition, and huge government support, the evolution of a multi-purpose ecosystem seemed only natural.

Most probably, the super app trend will continue to grow in and out of Asia. More and more companies worldwide see the potential of retaining their users within their all-in-one application.

Building a super app can give you serious competitive advantages:

The comfort of using only one place to get things done offers a unique user experience
The fact you open up your space to different service providers lets you monetize your app easily
The implementation of super apps gives you a stronger digital presence

Code Splitting in React Native Applications

Callstack Engineers — Mon, 16 Aug 2021 16:17:05 +0000

Introduction

When it comes to React Native applications, the code for your application shares some aspects of the browser applications – web apps and we do have a well-established and thought-out solution for splitting functionality on the web which is called code splitting.

Thinking about mobile apps, we usually have a mental model of a single runnable program that includes all the possible features. In fact, that’s how most of the mobile apps are architected and there’s a simple reason for that – it’s difficult to split functionality and deliver it later in a fully native mobile application. Especially if we are talking about cross-platform solutions for both iOS and Android.

Why not bring this support to React Native? It turns out that it is in fact possible, but first, we need to understand it on a high level.

In this article, I’ll focus on the idea of code splitting to introduce the concept and create a basic understanding of the technique.
In the next one, we will go through technical details and implementation of code splitting using Webpack and Re.Pack – a Webpack-based toolkit to build your React Native application with the full support of the Webpack ecosystem.

How does React Native run your code?

Most of the time, developing React Native applications means writing the JavaScript (or TypeScript) code with the dependencies coming from repositories like NPM. However, the React Native runtime doesn’t understand our code in such form – it has no idea how to combine multiple files together or how to pull in the dependencies. It might even not understand our code at all due to unsupported syntax or type annotations. That’s why we need a tool to convert our code into a format that can be executed by React Native. This format is called a bundle, and the tool to create it – a bundler.

A bundler takes your source code, any dependencies and external libraries as well as static assets you use; transforms them, optimizes them and packs them together into a runnable bundle.

What is code splitting?

Code splitting is a technique that allows developers to create multiple bundle files instead of just one. By default, all your input files (source code, dependencies and assets) are combined into a single file. With code splitting, they are split into multiple ones.

We call each of the output files a chunk, while the main chunk (also known as entry chunk) can be referred to as a bundle.

The bundle is still used as an entry point to the application, so React Native will execute it first, then it will load additional chunks on-demand.

Code splitting is a technique to produce multiple output files which, as a whole, contains all your application’s functionality, but allows them to be loaded later on demand.

Code splitting in React Native apps – use cases

Ultimately, it’s up to you to decide if your React Native application would benefit from code splitting, but there are some categories of applications that are good candidates for code splitting.

Underperforming application

Code splitting is a viable candidate for any kind of application, which has performance issues, especially in the startup area. Moving the code from the bundle to the additional chunk is a deferral technique. If used correctly, your React Native application will load only the necessary pieces of the code and postpone the load of others, which can help improve startup performance (TTR/TTI).

Modular applications

Applications that expose different functionalities or different UIs based on user’s details are a great example of apps that would greatly benefit from code splitting.

Let’s take an e-learning application for instance. With code splitting, it’s possible to separate a student’s and a teacher’s functionalities, so the application loads either of them, while decreasing the initial download size student or teacher would have to download and improving startup performance by loading only relevant code.

Another examples of applications worth mentioning would be:

an automotive application, which gives the user features based on their subscription plan
a word processing application that provides language-specific functionalities. Each language can have a dedicated chunk loaded on-demand.

Super apps / Mini app stores

Another two groups of applications where code splitting plays a huge role are so-called super apps and applications with mini app stores. Both super apps and mini apps stores are applications built from smaller, dedicated mini apps.

Instead of having multiple applications on the App Store and Google Play you can combine them into a single one while streamlining the development and simplifying management.

You can think of super apps as all-in-one mobile experiences – a closed ecosystem on many smaller apps.

WeChat and Alipay are great examples of super-apps used by millions. With code splitting it’s possible to achieve it with React Native.

How to introduce code splitting into React Native applications?

Code splitting and the examples shown above are nothing new in Web development thanks to Webpack – a bundler for modern JavaScript applications. Due to its widespread adoption and rich feature set, we (at Callstack) decided to bring support for bundling React Native applications to Webpack.

And this is how we’ve built Re.Pack – a toolkit that allows you to use Webpack and its code splitting functionality to bundle React Native apps.

In the next article, we’ll take a closer look at how Re.Pack can help us build React Native applications and leverage code splitting.

Stay tuned!

Technical Guide, Part 1: Compiling Hermes for Apple Platforms

Callstack Engineers — Fri, 04 Jun 2021 14:19:38 +0000

Months of our intense work with teams at Facebook and Microsoft resulted in bringing Hermes to iOS. We are happy to share the details of the process in a series of articles. This article is the third in the series and the first to focus on the technical journey:

Bringing Hermes to iOS in React Native 0.64
Hermes Performance on iOS: How it Compares with JSC
Technical Guide, Part 1: Compiling Hermes Engine for Apple Platforms (you are here)
Technical Guide, Part 2: Integrating Hermes with React Native

You are going to find out how we brought Hermes to iOS and how you can implement it yourself. We provide a detailed guide to Hermes implementation based on the actual work done. So, if you want to learn more about how different core pieces play together, keep reading!

Compiling Hermes for Apple platforms

Before we talk about bringing Hermes to React Native on iOS, we actually need to compile it for Apple platforms. Hermes is written in C++ and compiled with cmake to existing platforms, so at a glance, it sounds like fun!

Just to be on the safe side, let me explain that C++ is one of these cross-platform languages that can run literally everywhere. For example, you can write native modules in C++ for Android and on iOS (hey, the Objective-C is not just similar in its name). Thanks to that, seeing a task of compiling Hermes on Apple devices didn’t sound that scary when I first started playing around that topic.

Thankfully, I didn’t have to start from the middle of nowhere (but I have to admit that playing around with cmake in general was quite an experience!). Folks at Microsoft have been working on bringing Hermes to Mac for their React Native macOS project. The work was done primarily by Eloy Durán (@alloy), who sent a PR to Hermes with the base for my work.

On a high level, this PR enables cmake to package Hermes in a dynamic library so that it can be used on a macOS platform. To make the integration with Apple ecosystem smoother, the PR adds a special Podspec so that you don’t have to manually import a framework file to your project. You can let CocoaPods do that magic for you instead.

At this point, I was amazed by the comprehensiveness of cmake and the number of out-of-the-box features it provides. If you look at the changes in the aforementioned PR, they’re all related to the build system. It’s mind blowing to see that such an advanced project like a JavaScript engine can be run on macOS by just flipping a few flags, i.e. without changing the business logic of the engine itself.

That’s good for me and all of you planning to work on C++ bits in the future! With that in mind, let’s move onto the iOS part.

On the way to iOS

Having Hermes running on macOS was a good indicator that it might work on iOS as well. In case you want a quick version – here’s my PR with all the changes. If you’re curious about all the steps and a bit of technical explanations, carry on.

#1

First thing I had to do was to tell cmake that it is no longer building Hermes for macOS, but for iOS. This can be achieved by setting a special variable CMAKE_OSX_SYSROOT to configure the build pipeline to target specific SDK.

set(CMAKE_OSX_SYSROOT ${HERMES_APPLE_TARGET_PLATFORM})

I ended up going straight with a variable. We will need to build Hermes for every platform and architecture separately, which means building it a couple of times. Having a variable definitely helps – we can change its value depending on what we are targeting.

The list of all platforms and architectures should be aligned with what React Native supports right now – otherwise, developers may run into issues on certain devices.

Here’s a breakdown of the platforms together with their architectures.

#2

Another important thing was to tell cmake where to actually output generated files for every platform.

By default, the library would be placed under a Library/Frameworks/hermes.framework path within a build folder. Unfortunately, that would result in one build process overwriting the artifacts from the previous one.

Since I wanted to keep the artifacts for every platform, I ended up tweaking the location where the files are placed:

install(DIRECTORY ${DSYM_PATH} DESTINATION Library/Frameworks/${HERMES_APPLE_TARGET_PLATFORM})

As a result, the files would be now placed under Library/Frameworks/iphonesimulator or Library/Frameworks/iphoneos, depending on whether we’re building for a device or a simulator.

#3

Now that the platform part was sorted, it was time to look at the architectures. The idea was to precompile Hermes in all possible configurations so that you don’t have to run it from source. That would be not only quite a time consuming process, but also prone to many errors, due to different configurations of our development machines.

To do so, for each invocation of cmake, I ended up setting CMAKE_OSX_ARCHITECTURES with the right value for every platform. Looking at the table I have shared just a few paragraphs earlier, that would be “armv7;armv7s;arm64” for iPhone and “x86_64;i386” for iPhone Simulator.

Since that variable can be passed as a command line argument straight to cmake, there is no custom code that I had to do to make it work.

#4

The last thing to set was the deployment target – the version that we are targeting and is the minimum supported by Hermes. Again, that one is supported by cmake out of the box, so no changes here.

The value of CMAKE_OSX_DEPLOYMENT_TARGET was set equally to “10.0” for both simulator and the device.

build_apple_framework

After testing the combinations a few times, I packaged them in a helper Bash function, called build_apple_framework, that takes these settings and tells CMake what to do.

build_apple_framework "iphoneos" "armv7;armv7s;arm64" "10.0" build_apple_framework "iphonesimulator" "x86_64;i386" "10.0"

Thanks to that, it becomes trivial to control what platforms and architectures Hermes supports on iOS.

Bonus points: it can be used to build macOS version too, so I went ahead and updated @alloy part too:

build_apple_framework "macosx" "x86_64" "10.0"

hermes.framework files

After building Hermes with CMake for all the combinations, I ended up with two hermes.framework files: for iPhone supporting armv7, armv7s and arm64 as well as for iPhone Simulator supporting x86_64 and i386.

It would be a poor developer experience if you had to change a hermes.framework in your project depending on whether you run on a device or a simulator. It would definitely hinder your work if you had to manually replace the library in your project.

Thankfully, there are universal frameworks, in other words – frameworks that support more than a single platform. Simply put – it’s a way to combine two hermes.framework into a single one!

You can create one programmatically with a lipo – a tool to create multi-architectural files. To generate a universal framework file, the invocation would look as follows:

lipo -create -output

Library/Frameworks/iphoneos/hermes.framework/hermes Library/Frameworks/iphoneos/hermes.framework/hermes Library/Frameworks/iphonesimulator/hermes.framework/hermes

To speed things up, I decided to merge all additional architectures into the iPhone binary. The first argument to lipo is the destination, the following ones are input binaries that should be combined together.

Just like before, I moved the logic into a Bash function, called create_universal_framework:

create_universal_framework "iphoneos" "iphonesimulator"

Again, such an approach allows us to easily control the contents of the final hermes.framework file.

Last but not least

The last piece was to update the Hermes.podspec created by @alloy to add iOS support.

That required changing spec.vendored_frameworks to spec.osx.vendored_frameworks and spec.ios.vendored_frameworks to tell CocoaPods that this package contains frameworks for both macOS as well as iOS (note that macOS and iOS binaries can’t be merged into a single universal framework – they are separate).

In other words, replacing this:

spec.vendored_frameworks = "destroot/Library/Frameworks/hermes.framework"

with:

spec.ios.vendored_frameworks = "destroot/Library/Frameworks/iphoneos/hermes.framework" spec.osx.vendored_frameworks = "destroot/Library/Frameworks/macosx/hermes.framework"

Try Hermes yourself

The process of doing CMake reverse engineering took me three weeks, but it was worth it. I have learned a lot about build tools and this knowledge will be very useful in the future.

You should definitely clone Hermes and play around with it. Follow our Hermes implementation guide and test it yourself. It’s quite easy to get started and working on a JavaScript engine can get really rewarding!

If you want to learn more about Hermes, check our podcast: React Native 0.64 with Hermes for iOS. My guests, Microsoft and Facebook engineers, discuss the engine in detail!

Click on the image to watch the podcast video.

What’s next?

In the next part of this guide, “Integrating Hermes with React Native,” we will go through the steps that are needed to enable a custom engine to work with React Native, instead of the default JSC.

DEV Community: Callstack Engineers

A Step-By-Step Guide to Super App Development

Building a super app from scratch

Setting up Re.Pack in both HostApp and MiniApp

Setting up ModuleFederationPlugin

Setting up ScriptManager in the HostApp

Using MainNavigator from the MiniApp in the HostApp

Migrating to a super app setup

Aligning dependencies

Assets handling

Sharing state across the app

Summary

Working With the Super-App-Showcase Repository

Architecture overview

Monorepo

Catalog server

State management

Shell app

Summary

How to Optimize Development Efficiency When You’re Building a Super App

Preparing your super app for third-party contributions

Laying down requirements

Optimizing developer experience

SDK

Mobile nuances

Fostering collaboration between teams working on your super app

Sustainable architecture

Lightweight host app

Monorepo

Summary

Migrating a React Native Library to the New Architecture

Introduction

What’s the New Architecture?

What’s Fabric?

Steps to migrate a library

Using an official migration guide for library creators

Creating a library from scratch

1. Writing TypeScript spec

2. Migrating deprecated APIs

3. Implementing Codegen generated interfaces on native platforms (Android / iOS)

4. Now it’s time to release a migrated library

Try React Native Slider with Fabric

Summary

Stripe Identity: ID Authentication Made Simple

What is Stripe Identity?

How to use the Stripe Identity React Native SDK

Getting started with the useStripeIdentity hook

Using the Stripe Identity SDK without hooks

Verifying results

Error handling

TypeScript support

Stripe Identity features

Simplified security

Automatic document capture

Prebuilt UI

Automated verification

Summary

Setting up React Native Monorepo with Yarn Workspaces

What is a monorepo?

Why use monorepo in React Native?

Setting up Yarn workspaces

Why it’s better to avoid using nohoist

Rearranging the project structure

Creating a React Native project

iOS setup

Android setup

Configure Metro

Setting up a shared package

Setting up a React project

Sharing UI components with React Native Web

Installation steps

Modify shared package to export React Native component

To sum up

A Comprehensive Guide to Mock Service Worker (MSW)

When to use a Mock Service Worker?

The basic guide to Mock Service Worker (MSW)

The advanced guide to Mock Service Worker

Testing errors

Request handler overrides

Response object overrides

Using MainNavigator from the `MiniApp` in the `HostApp`