Working With the React Native Super App Showcase Repository
Authors
Building a super app in React Native raises an important engineering question: how can independent feature teams ship on their own without fragmenting the codebase, increasing binary size, or causing runtime crashes? To explore one answer, this article looks at Callstack’s Super App Showcase, an open-source reference application for React Native super app architecture. We provide an overview of its design and explain each component’s role to help you architect and manage super apps in your own projects.
The showcase organizes its packages in a monorepo and uses Re.Pack with Module Federation V2 to build and load federated bundles at runtime. To the end user, the application functions like a standard mobile app, while each feature domain operates as a microfrontend that is downloaded over the network when needed. For a smaller implementation, you can build from scratch, follow our step-by-step guide to super app development with Re.Pack 5.
Architecture overview
The system has three structural roles and relies on two non-negotiable architectural rules.
The first role belongs to the Host Shell, which is the only package containing native binaries. It owns root navigation, boot logic, authentication gates, and declares where remote mini apps originate. The second role consists of the federated mini apps, which represent isolated feature domains that each expose a single navigator or context provider as a federated remote bundle. The third role is the Shared SDK, a singleton library that defines the dependency contract and provides runtime code that must exist in exactly one instance across the entire process lifetime. This includes real-time streaming connections, shared state contexts, and design system tokens.
Two rules keep this multi-bundle ecosystem stable. First, native code lives in the Host Shell because registering two instances of a native module causes an immediate application crash rather than soft warnings. Second, every shared package reads its version from the same dependency catalog. The showcase registers each dependency as a singleton and uses the pinned value for both version and requiredVersion. Module Federation does not enforce strict equality here, so the catalog and alignment checks keep dependencies consistent across packages. A second React instance can break hooks and internal state.
App lifecycle and cold start
The cold start sequence shows how these boundaries work in practice. When the host binary boots, it configures script management with persistent local storage, so downloaded remote bundles survive application restarts. The host then mounts shared data providers from the SDK above root navigation and opens global data streams before any feature-specific mini app mounts.
Next, the host fetches the authentication bundle over the network behind a suspense boundary, displaying the native splash screen as a fallback. The auth provider remains in its initial loading state while it verifies stored tokens, keeping the native splash screen visible until session state resolves and eliminating any UI flash of a sign-in screen. Once authenticated, primary navigation renders, and JavaScript bundles for individual feature domains download only when the user explicitly navigates to the corresponding tab or feature.
Shell app
Diving deeper into individual components reveals several key implementation strategies for the Shell.
The Host Shell defines a unique container namespace and configures Module Federation V2 to resolve manifest endpoints dynamically for each target platform. Mounting a remote mini app requires no custom framework code, as dynamic imports are rewritten into container lookups at build time. Every remote mount point needs an error boundary, so that, if a remote feature bundle fails to download due to network issues, that specific tab displays a local fallback error while the rest of the application remains fully functional.
Global application services, such as authentication, also connect directly to the Shell. The Host Shell must evaluate sign-in state before rendering navigation tabs, while the authentication UI and logic should remain independently deployable. Exposing an auth provider as a federated render prop allows the host to branch on state provided by a container it does not own.
Federated mini apps
Federated mini apps own their domains by exposing a complete stack navigator rather than individual screens. This allows feature teams to add dozens of internal routes without requiring a single code change in the host repository. To avoid bundling native code, mini apps declare native dependencies purely as peer dependencies.
plugins: [
...
new Repack.plugins.ModuleFederationPluginV2({
name: 'trading',
filename: 'trading.container.js.bundle',
dts: false,
exposes: {
'./App': './src/navigation/MainNavigator',
},
shared: getSharedDependencies({eager: false}),
}),
...
]The bundler resolves these dependencies by pointing its resolution root directly to the host's module directory, while TypeScript configurations use path mapping entries to locate types. At build time, the mini app compiles against the host's dependencies, but at runtime it carries none of that native code in its bundle, resolving instead to the shared singleton already loaded by the shell.
Monorepo and catalog management
The Shared SDK keeps contracts aligned across all packages through a central dependency contract and automated alignment rules. A single utility function generates shared dependency declarations for every bundler configuration, ensuring that adding or updating a shared singleton takes one line of code, and the change propagates across the workspace.
Adding a new feature module to this monorepo setup follows a predictable five-step workflow:
- Initialize the package directory with a configuration that points to Re.Pack commands.
- Define the bundler configuration with a unique container name, output filename, exposed navigator path, and shared dependency flags set to consume shared modules.
- Point module resolution in the bundler to the host’s node directory and map peer dependencies in the TypeScript configurations.
- Register the remote entry in the host’s Module Federation V2 plugin and declare its types.
- Wrap the dynamic import with a lazy boundary and skeleton fallback
State management and real-time performance
Decoupling an app into runtime bundles is straight engineering, but making those seams invisible to users requires intentional performance patterns. When multiple feature tabs consume the same background data feed, opening duplicate socket connections wastes resources and risks state drift. The core real-time data service resides entirely within the Shared SDK singleton, ensuring newly mounted components receive cached state synchronously when they subscribe and display accurate values on the first frame.
While a remote is loading, the Host displays a local placeholder with an activity indicator and feature label. High-frequency price subscriptions are isolated in leaf components so that updates do not cause the entire row to re-render.
Only the price text re-renders on each update, while the highlight animation runs on the UI thread using Reanimated shared values. Price updates use React transitions, and React Compiler is enabled in the Host, Trading, and Wallet.
Production considerations
Preparing this architecture for production requires planning for two integration points: dynamic remote resolution and version compatibility.
In production, local manifest URLs must be replaced with stable remote hosting or trusted discovery service. Teams should also define caching, rollback, offline behavior, monitoring & signature-verification policies. The showcase signs the Auth production bundle. However, the Host must explicitly enable signature verification to verify signed remotes when loading them.
Remote feature bundles deploy instantly over the air, while host binaries go through app store review cycles. For version compatibility, backend routing must therefore prevent an older host binary from fetching an incompatible bundle version.
Summary
The Super App Showcase is designed to make a complex architecture easier to explore in context. Rather than presenting Module Federation, Re.Pack, shared dependencies, and runtime bundle loading as isolated concepts, the repository shows how they work together in a real React Native application.
Following the Host Shell, federated mini apps, and Shared SDK through the repository, you can see where each responsibility belongs: how the shell owns the native runtime and application bootstrap, how feature domains remain independently deployable, and how the shared SDK keeps common services and dependencies consistent across every bundle.
Use the Showcase as a reference super app, then adapt its structure, dependency contracts, loading patterns, and release strategy to your own application and team structure. And if you’re considering taking these patterns into production and want to compare notes, our super app development team is happy to talk.
