App Integration

This guide explains how to integrate Mapples into your existing React Native application or set up a new project with Mapples.

Wrapping Your Application

The @mapples/app package provides the MapplesApp component that serves as the main wrapper for your application. This component provides the core Mapples ecosystem functionality.

Basic Usage

import React from 'react';
import MapplesApp from '@mapples/app';

function App() {
  return (
    <MapplesApp>
      {/* Your app components */}
    </MapplesApp>
  );
}

export default App;

With Custom Assets and Styles

import React from 'react';
import MapplesApp from '@mapples/app';

const customAssets = {
  'ref(font:123:CustomFont.ttf)': require('./fonts/CustomFont.ttf'),
  'ref(image:456:logo.png)': require('./images/logo.png'),
};

const customStyle = {
  // Your custom style configuration
};

function App() {
  return (
    <MapplesApp
      assets={customAssets}
      style={customStyle}
    >
      {/* Your app components */}
    </MapplesApp>
  );
}

export default App;

Integration with App Router (Root _layout.tsx)

For applications using app-router structure, you should wrap your entire application at the root level in your _layout.tsx file:

import React from 'react';
import MapplesApp from '@mapples/app';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <MapplesApp>
      <Slot />
    </MapplesApp>
  );
}

💡 Root Level Wrapping

Always wrap your application with MapplesApp once at the root level. This ensures proper initialization of the Mapples ecosystem and prevents potential conflicts or duplicate providers in your component tree.

Metro Configuration

To properly use Mapples with SVG assets and other resources, you need to update your Metro configuration.

⚠️ Important: React Native SVG Transformer Required

Before configuring Metro, make sure to install and set up react-native-svg-transformer in your project. This is essential for proper SVG handling in Mapples applications. Follow the setup instructions in the react-native-svg-transformer documentation.

Installing React Native SVG Transformer

npm install --save-dev react-native-svg-transformer
# or
yarn add --dev react-native-svg-transformer

Updating metro.config.js

Create or update your metro.config.js file in the root of your project:

const { getDefaultConfig } = require('expo/metro-config');
const { mapplesResolver } = require('@mapples/app/expo');

module.exports = (() => {
  const config = getDefaultConfig(__dirname);

  const { transformer, resolver } = config;

  // React native SVG transformer configuration required to handle SVG assets
  config.transformer = {
    ...transformer,
    babelTransformerPath: require.resolve('react-native-svg-transformer/expo'),
  };
  config.resolver = {
    ...resolver,
    assetExts: resolver.assetExts.filter((ext) => ext !== 'svg'),
    sourceExts: [...resolver.sourceExts, 'svg'],
  };

  // Add Mapples resolver to handle automatic asset and style loading
  config.resolver.resolveRequest = mapplesResolver(
    (context, moduleName, platform) => {
      // add your custom resolvers here
      return context.resolveRequest(context, moduleName, platform);
    },
  );

  return config;
})();

MapplesApp Props

The MapplesApp component accepts the following props:

• children - Child components to render within the Mapples context
• style? - Optional custom style configuration to override the default Mapples styling
• assets? - Optional custom assets configuration to override the default Mapples assets
• showFontLoadingIndicator? - Whether to show a loading indicator while fonts are loading
• FontLoadingIndicator? - Custom loading indicator component to display while fonts are loading

---

What's Next?

🚀 Quick Start

Get started with Mapples in under 5 minutes with our step-by-step quick start guide.

Get Started →

🎨 Mapples Creator

Learn how to use the visual creator tools to design your application interface.

Explore Creator →

📦 Packages

Discover available Mapples packages to extend your application functionality.

Browse Packages →