@qt-test/federation-template

🚀 React Native template for creating mini-apps that integrate seamlessly with super-app

⚡ Quick Start - Focus on Your Features

# 1. Create your mini-app (replace 'MyMiniApp' with your app name)
npx @react-native-community/cli init MyMiniApp --template @qt-test/federation-template

# 2. Start developing your features
cd MyMiniApp
npm run dev

# 3. Build amazing features! 🎉

🎯 What You Get Out of the Box

✅ Zero Configuration Required

• Module Federation: Pre-configured for super-app integration
• Unique Ports: Automatically assigned to avoid conflicts
• Federation SDK: Access to shared services and native features
• TypeScript: Full type support and configuration

✅ Production Ready

• Docker: Multi-stage build with nginx
• Deployment: One-command deploy to production
• Bundle Optimization: Hermes bytecode compilation
• CORS: Pre-configured for super-app loading

✅ Developer Experience

• Organized Scripts: Categorized npm commands for every workflow
• Hot Reload: Live development with instant updates
• ADB Integration: Automated Android device setup
• Documentation: Comprehensive guides and examples

📋 Mini-App Developer Instructions

Step 1: Create Your Mini-App

# Replace 'YourAppName' with your actual mini-app name
npx @react-native-community/cli init YourAppName --template @qt-test/federation-template

What happens automatically:

• ✅ React Native project created with Module Federation
• ✅ Unique development port assigned (e.g., 8088)
• ✅ All dependencies installed
• ✅ Project configured with your app name
• ✅ Git repository initialized

Step 2: Start Development

cd YourAppName
npm run dev

Your mini-app development server is now running!

Step 3: Build Your Features

Focus on these files:

• App.tsx - Your main mini-app component
• src/components/ - Add your React components
• src/screens/ - Add your screen components
• src/services/ - Add API calls and business logic
• assets/ - Add images and static files

Step 4: Access Super-App Services

The template provides access to super-app services:

• Authentication: User login state and profile
• Navigation: Deep linking and route management
• Native Features: Camera, location, notifications
• Shared UI: Consistent styling and components

// Example: Access user authentication
import { useAuth } from "@qt-test/federation-sdk";

export default function App() {
  const { user, isAuthenticated } = useAuth();

  return (
    <View>
      {isAuthenticated ? (
        <Text>Welcome, {user.name}!</Text>
      ) : (
        <Text>Please log in via super-app</Text>
      )}
    </View>
  );
}

Step 5: Test Your Mini-App

# Test on Android device/emulator
npm run android

# Test on iOS simulator
npm run ios

# Build production version
npm run build

Step 6: Ready for Integration

When your mini-app is ready:

1. Deploy to production: npm run deploy
2. Notify the team: Provide your production URL
3. Team handles integration: They add your mini-app to the super-app

You focus on features, the team handles federation integration!

What happens:

• ✅ Production bundles built for Android/iOS
• ✅ Docker container created and tested
• ✅ Deployed to your hosting provider
• ✅ Federation URL ready for production

🛠️ Available Commands

Quick Commands (Most Used)

npm run dev         # Start development (fresh cache)
npm run build       # Build production bundles
npm run deploy      # Deploy to production

Development

npm start           # Start development server
npm run dev:fresh   # Clean cache and start development
npm run dev:build   # Build and test deployment locally

Platform Testing

npm run android     # Run on Android device/emulator
npm run ios         # Run on iOS device/simulator
npm run adbreverse  # Setup ADB reverse tunnel for Android

Build & Deploy

npm run bundle:all    # Build Android and iOS bundles
npm run docker:rebuild # Full Docker rebuild and test
npm run deploy:build  # Build and deploy to production

Maintenance

npm run clean:cache  # Clear build cache
npm run clean:full   # Full reset (includes node_modules)
npm run lint         # Run code linting
npm run test         # Run tests

MyMiniApp/ ├── App.tsx # Sample mini-app component ├── index.js # Module Federation entry point ├── rspack.config.mjs # Pre-configured build setup ├── vercel.json # Deployment configuration ├── deploy.js # Automated deployment script ├── package.json # All dependencies and scripts └── README.md # Detailed project documentation

## 🛠️ Available Scripts in Generated Project

- `npm start` - Start development server
- `npm run deploy` - Build and deploy to production
- `npm run bundle:android` - Build Android bundle
- `npm run bundle:ios` - Build iOS bundle

## 🎯 Use Cases

Perfect for:

- **Super App Architecture** - Multiple mini-apps in one host
- **Micro-Frontends** - Independent team development
- **A/B Testing** - Deploy different versions independently
- **Feature Flags** - Load features dynamically
- **White Label Apps** - Customize features per deployment

## 🔧 Customization

The generated project can be customized by:

1. Editing `App.tsx` for your app logic
2. Modifying `package.json` for dependencies
3. Updating `rspack.config.mjs` for build configuration
4. Changing `vercel.json` for deployment settings

## 📚 Documentation

Each generated project includes:

- Comprehensive README with setup instructions
- Inline code comments explaining configurations
- Troubleshooting guide for common issues
- Links to relevant documentation

## � Best Practices Included

This template includes **all Federation best practices**:
- ✅ **Organized Scripts**: Categorized npm commands
- ✅ **Unique Ports**: Automatic assignment prevents conflicts
- ✅ **Production Ready**: Docker + nginx configuration
- ✅ **Hot Reload**: Live development updates
- ✅ **Bundle Optimization**: Hermes bytecode compilation
- ✅ **CORS Configured**: Ready for federation loading
- ✅ **TypeScript**: Full type support
- ✅ **Linting**: Code quality enforcement

## 🚨 Important Notes for Developers

### ✅ **DO:**
- ✅ Customize `App.tsx` with your mini-app logic
- ✅ Add components in `src/components/`
- ✅ Use `npm run dev` for development
- ✅ Test with `npm run adbreverse` for Android
- ✅ Deploy with `npm run deploy`

### ❌ **DON'T:**
- ❌ Change port numbers (auto-assigned to avoid conflicts)
- ❌ Modify `rspack.config.mjs` federation settings
- ❌ Change the main App export structure
- ❌ Delete the post-init.js file

## 🤝 Getting Help

### Common Issues & Solutions

**Port already in use:**
```bash
# Template auto-assigns unique ports, but if conflicts occur:
# Edit package.json "start" script port number

Android connection failed:

# Always run ADB setup first:
npm run adbreverse

Federation not loading:

# Check host app mini-apps-registry.json has correct URL:
"http://localhost:[YOUR_PORT]/YourAppName.container.js"

Build failures:

# Try full clean and reinstall:
npm run clean:full
npm install
npm run dev

📚 Documentation Resources

• 📖 Generated README.md - Complete setup guide in your mini-app
• 🔧 rspack.config.mjs - Federation configuration details
• 📱 mini-apps-registry.json - Host app integration guide
• 🐳 Dockerfile - Production deployment configuration

🚀 Next Steps After Creation

1. Customize App.tsx with your mini-app functionality
2. Add components in src/components/
3. Test locally with npm run dev
4. Test with host app by adding to registry
5. Deploy to production with npm run deploy

🎉 Happy coding with Federation!

Your mini-app is ready to join the super-app ecosystem. Focus on building amazing features - we've handled all the infrastructure setup for you!