npm package: @qt-test/federation-template
Description: React Native template for creating Module Federation mini-apps with zero configuration
Author: QT Team
Latest version: 1.0.27

# @qt-test/federation-template

> 🚀 React Native template for creating mini-apps that integrate seamlessly with super-app

## ⚡ Quick Start - Focus on Your Features

```bash
# 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

```bash
# 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

```bash
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

```typescript
// 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

```bash
# 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)

```bash
npm run dev         # Start development (fresh cache)
npm run build       # Build production bundles
npm run deploy      # Deploy to production
```

### Development

```bash
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

```bash
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

```bash
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

```bash
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:**

```bash
# Always run ADB setup first:
npm run adbreverse
```

**Federation not loading:**

```bash
# Check host app mini-apps-registry.json has correct URL:
"http://localhost:[YOUR_PORT]/YourAppName.container.js"
```

**Build failures:**

```bash
# 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!