A Step-By-Step Guide to Super App Development
Tags: superapp, reactnative, repack
Published: 2023-05-18 10:34:17

[by Jakub Romańczyk](https://www.callstack.com/blog-author/jakub-romanczyk)

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](https://www.callstack.com/blog/super-app-business-faq?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide) 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](https://github.com/callstack/super-app-example). 

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](https://www.callstack.com/blog/module-federation-with-re-pack-3?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide). 

Why this combination of technologies? [Re.Pack](https://www.callstack.com/open-source/re-pack?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide) 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](https://www.callstack.com/blog/implementing-code-splitting-in-react-native-with-re-pack?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide) – 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:
{% embed https://gist.github.com/pytqqq/0396642ac1110e53e12b683e38b14b61 %}

## Setting up Re.Pack in both HostApp and MiniApp
In both _packages/host-app and packages/mini-app_ install Re.Pack with its dependencies:
{% embed https://gist.github.com/pytqqq/f0494c4197b9edc62b014556c43e451d %}

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):
{% embed https://gist.github.com/pytqqq/8c3c224570b711e920ce8fcee03bd031 %}

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:
{% embed https://gist.github.com/pytqqq/3ae2c5cd0b85190fb5f8d0ce1e120d66 %}

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](https://github.com/callstack/repack/blob/main/templates/webpack.config.mjs) or the [CommonJS equivalent here](https://github.com/callstack/repack/blob/main/templates/webpack.config.cjs). 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:

1. Click on the project in the Project navigator panel on the left
2. Go to Build Phases tab
3. Expand Bundle React Native code and images phase
4. Add export BUNDLE_COMMAND=webpack-bundle to the phase
{% embed https://gist.github.com/pytqqq/ff6307ac55c8ed2cdd93fa427b9f703b %}

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`:
{% embed https://gist.github.com/pytqqq/2a95d0471d2c3637fe5dcde37e837bd1 %}

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. 
{% embed https://youtu.be/zWQ-WfVxs-8 %}

Let’s add a new instance of `RePack.ModuleFederationPlugin` to our `webpack.config` in the `HostApp`: 
{% embed https://gist.github.com/pytqqq/3affceac27c1b5b38a3067700fa28eeb %}

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:

1. Inside webpack.config.mjs, let’s grab `STANDALONE` from the process.env
{% embed https://gist.github.com/pytqqq/bd9908ae2bc973aaeedab0802fe726e8 %}

2. Now let’s add the `ModuleFederationPlugin` just like in the `HostApp`
{% embed https://gist.github.com/pytqqq/5147fdbb8cbd1243c9fbc2607910dad3 %}

3. 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)
{% embed https://gist.github.com/pytqqq/1f323471707f7be6e84c8f91168fda04 %}

`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 
{% embed https://gist.github.com/pytqqq/993ec608a5b0668cc630a4e25b31417d %}

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:
{% embed https://gist.github.com/pytqqq/e9b947d13ce56e94625ffa8e036d538a %}

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`: 
{% embed https://gist.github.com/pytqqq/43fea3fe330e9bc8e724bd235ee928bd %}

`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`:
{% embed https://gist.github.com/pytqqq/d65e913bb2f5714bd6249fa7e9369d68 %}

{% embed https://gist.github.com/pytqqq/afac72a9daaf640f637231ef3d445e75 %}

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:
{% embed https://gist.github.com/pytqqq/9e2208654d65f892665918cde8520493 %}

Click on the newly added button to Navigate to MiniApp and enjoy your super app!
{% embed https://youtu.be/LR7Kf16ptrQ %}

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](https://github.com/callstack/repack) 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](https://github.com/callstack/super-app-template). Use it to your advantage, and don’t hesitate to reach out to us if you have any questions about [super app developmen](https://www.callstack.com/super-app-development?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide)t.

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](https://www.callstack.com/blog/optimize-development-efficiency-when-building-super-app?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide). We’ve also published [a case study of a super-app-showcase](https://www.callstack.com/blog/case-study-super-app-template?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide) that might significantly speed up your work.

_This article was originally published at [callstack.com](https://www.callstack.com/blog/step-by-step-guide-to-super-app-development?utm_campaign=super_apps&utm_source=dev.to&utm_content=Super_App_Guide) on April 12, 2023._