Based Native App Template

A production-ready React Native template with AI-guided customization, comprehensive component library, and OpenSpec integration.

Build mobile apps 10x faster with a battle-tested foundation, clean architecture, and intelligent AI assistance.

✨ Features

⚡️ React Native 0.81.4 with New Architecture (JSI enabled)
🎨 Atomic Design System - Complete component library (atoms → molecules → organisms)
🎭 Theme System - Light/dark modes with design tokens
📦 WatermelonDB - Reactive, performant local database
🧭 Navigation - Bottom tabs with stack navigation ready
🤖 AI-Guided Development - OpenSpec integration for spec-driven workflows
🔧 Modular Features - Enable/disable features via configuration
📱 Production Ready - Performance optimized, tested patterns
🎯 TypeScript Strict Mode - Full type safety
🛠️ Modern Tooling - Biome for linting/formatting

🚀 Quick Start

Prerequisites

Node.js >= 18
NPM >= 9
React Native development environment (setup guide)
For iOS: Xcode 14+ and CocoaPods
For Android: Android Studio and JDK 17

Installation

Clone the template

git clone https://github.com/amitayks/react-native-template.git your-app-name
cd your-app-name

Install dependencies

npm install

iOS: Install pods

cd ios && pod install && cd ..

Run the app

# iOS
npm run ios

# Android
npm run android

Setup wizard will launch automatically on first run
- Answer questions about your app
- Or provide a pre-configured template.config.json
- Wizard customizes the template for your project

📁 Project Structure

src/
├── components/          # UI Components (Atomic Design)
│   ├── atoms/          # Basic building blocks (Button, Icon, etc.)
│   ├── molecules/      # Simple combinations (SearchBar, etc.)
│   ├── organisms/      # Complex components (SettingsDrawer, etc.)
│   └── templates/      # Page-level templates
├── contexts/           # React Context providers
│   ├── SettingsContext.tsx
│   ├── NavigationContext.tsx
│   └── ToastContext.tsx
├── hooks/              # Custom React hooks
├── models/             # WatermelonDB models
│   ├── Item.ts        # Generic placeholder model
│   └── AppSettings.ts # App settings model
├── navigation/         # Navigation configuration
│   ├── RootNavigator.tsx
│   ├── MainNavigator.tsx
│   └── OnboardingNavigator.tsx
├── screens/            # Screen components
│   ├── Home/          # Home screen
│   ├── Settings/      # Settings screen
│   └── Onboarding/    # Onboarding flow
├── services/           # Business logic & services
│   ├── database/      # Database setup & repositories
│   ├── storage/       # MMKV key-value storage
│   ├── security/      # Encryption services
│   └── performance/   # Performance monitoring
├── theme/              # Design system
│   ├── colors.ts      # Color palette & design tokens
│   └── useTheme.ts    # Theme hook
├── utils/              # Utility functions
│   ├── animations/    # Animation configurations
│   ├── constants/     # App constants
│   ├── device/        # Device utilities
│   └── templateConfig.ts # Template configuration utility
└── shared-types/       # TypeScript type definitions

openspec/               # OpenSpec integration
├── project.md         # Project context & conventions
├── AGENTS.md          # AI assistant instructions
├── specs/             # Feature specifications
├── changes/           # Change proposals
└── ai-instructions/   # Detailed AI guidance docs

template.config.json   # Template configuration

🎨 Component Library

Atoms (Basic Building Blocks)

Button - Multiple variants (primary, secondary, text, icon, ghost)
Icon - Material Design icons
Badge - Status badges
ProgressBar - Animated progress indicator
LabelTag - Tags for categorization
ToastNotification - Toast messages

Molecules (Simple Combinations)

SearchBar - Search input with icon
BottomNavContainer - Generic bottom nav wrapper
DateSectionHeader - Section headers for lists
ProcessingIndicator - Processing status display
AnimatedBottomNav - Animated bottom navigation

Organisms (Complex Components)

SettingsDrawer - Full-featured settings panel
HorizontalPageContainer - Swipeable page container
ErrorBoundary - Error handling wrapper

Templates

OnboardingTemplate - Multi-step onboarding flow

🔧 Configuration

template.config.json

The heart of the template system. Controls project configuration, features, branding, and more.

{
  "project": {
    "name": "{{APP_NAME}}",
    "packageName": "{{PACKAGE_NAME}}",
    "description": "{{APP_DESCRIPTION}}"
  },
  "features": {
    "ml": { "enabled": false },
    "camera": { "enabled": false },
    "search": { "enabled": false }
  },
  "branding": {
    "theme": {
      "primaryColor": "{{PRIMARY_COLOR}}",
      "secondaryColor": "{{SECONDARY_COLOR}}"
    }
  }
}

Placeholders {{LIKE_THIS}} are replaced during setup wizard.

Feature Flags

Enable/disable modular features:

import { isFeatureEnabled } from '@utils/templateConfig';

if (isFeatureEnabled('camera')) {
  // Camera feature code
}

🤖 AI-Guided Development

This template integrates with OpenSpec for spec-driven development with AI assistance.

AI Instruction Blocks

Throughout the code, you'll find instruction blocks:

/* AI-INSTRUCTION-START:instruction-id
 * Instructions for AI on how to customize this section
 * Detailed guidance in openspec/ai-instructions/instruction-id.md
 * OpenSpec Reference: specs/feature/spec.md
 * AI-INSTRUCTION-END */

These guide AI assistants (like Claude Code, GitHub Copilot, etc.) on proper customization.

Working with AI

AI reads openspec/project.md for project context
AI checks template.config.json for configuration
AI follows instructions in openspec/AGENTS.md
AI uses OpenSpec for creating change proposals
AI refers to openspec/ai-instructions/ for detailed guidance

Example: Adding a Feature

# AI creates proposal
openspec/changes/add-user-profile/
├── proposal.md    # What and why
├── tasks.md       # Implementation checklist
└── specs/         # Delta changes to requirements

📱 Screens

Home Screen

Minimal functional placeholder
Replace with your app's main functionality
Uses Atomic Design components
Theme-aware styling

Settings Screen

Theme selection (light/dark/system)
Clear cache
Delete all data
Legal links (privacy, terms, licenses)
App version display

Onboarding

Multi-step onboarding flow
Permission requests
Feature highlights
Skip/complete functionality

🗄️ Database

WatermelonDB

Reactive, performant SQLite database
JSI-powered for New Architecture
Lazy loading and optimistic updates

Models

Item - Generic placeholder model (replace with your entities)
AppSettings - Key-value app settings

Usage

import { database } from '@services/database/database';

const items = await database.get<Item>('{{TABLE_NAME}}').query().fetch();

🎭 Theming

Design Tokens

import { spacing, borderRadius, typography } from '@theme/colors';

const styles = StyleSheet.create({
  container: {
    padding: spacing.lg,        // 24px
    borderRadius: borderRadius.md, // 8px
  },
  text: {
    fontSize: typography.fontSize.md, // 16px
    fontWeight: typography.fontWeight.semibold, // 600
  },
});

Theme Hook

import { useTheme } from '@theme/useTheme';

function MyComponent() {
  const { colors, isDark } = useTheme();

  return (
    <View style={{ backgroundColor: colors.background }}>
      <Text style={{ color: colors.text }}>Hello</Text>
    </View>
  );
}

🔐 Release Signing Setup (Android)

Before building production releases, you MUST configure a release keystore:

1. Generate Release Keystore (One-Time Setup)

cd android/app
keytool -genkeypair -v -storetype PKCS12 -keystore release.keystore \
  -alias app-key-alias -keyalg RSA -keysize 2048 -validity 10000

You will be prompted for:

Keystore password (remember this!)
Your name
Organizational unit
Organization name
City/Locality
State/Province
Two-letter country code

2. Update Keystore Configuration

Edit android/gradle.properties and update these values:

APP_UPLOAD_STORE_FILE=release.keystore
APP_UPLOAD_KEY_ALIAS=app-key-alias
APP_UPLOAD_STORE_PASSWORD=your_password_here
APP_UPLOAD_KEY_PASSWORD=your_password_here

3. Security Best Practices

CRITICAL:

✅ Keep the keystore file (release.keystore) backed up securely
✅ Never commit gradle.properties with real passwords to Git
✅ Use environment variables for CI/CD pipelines
⚠️ If you lose the keystore, you cannot update your published app
⚠️ Add gradle.properties to .gitignore if storing real passwords

For CI/CD, use environment variables:

export APP_UPLOAD_STORE_PASSWORD=$KEYSTORE_PASSWORD
export APP_UPLOAD_KEY_PASSWORD=$KEY_PASSWORD

🧪 Scripts

# Development
npm start              # Start Metro bundler
npm run android        # Run on Android (debug)
npm run ios            # Run on iOS (debug)

# Build
npm run apk            # Build Android APK (debug)
npm run aab            # Build Android App Bundle (release - REQUIRES KEYSTORE)

# Code Quality
npm run typecheck      # TypeScript type checking
npm run lint           # Lint code with Biome
npm run lint:fix       # Fix linting issues
npm run format         # Format code
npm test               # Run tests

📦 Key Dependencies

Package	Version	Purpose
React Native	0.81.4	Core framework
React	19.1.0	UI library
TypeScript	5.9.3	Type safety
WatermelonDB	0.28.0	Database
React Navigation	7.x	Navigation
Reanimated	3.19.2	Animations
MMKV	3.3.3	Key-value storage
Biome	2.2.5	Linter/Formatter

Full dependency list: See package.json

⚠️ Important: Do NOT update package versions without testing thoroughly!

🏗️ Architecture

Atomic Design

Components follow Atomic Design methodology for maximum reusability and maintainability.

State Management

React Context + useReducer for global state
Local state for UI state
WatermelonDB observables for reactive data

Separation of Concerns

Components: UI only, no business logic
Hooks: Reusable logic
Services: Business logic, API calls, data manipulation
Contexts: Global state management
Repositories: Database access layer

🚧 Customization Workflows

Adding a Screen

Create screen component in src/screens/YourScreen/
Add to navigation in src/navigation/MainNavigator.tsx
Follow HomeScreen.tsx pattern
Add AI instruction blocks for future customization

Creating a Data Model

Define model in src/models/YourModel.ts
Update schema in src/services/database/schema.ts
Register in src/services/database/database.ts
Create repository (optional but recommended)

See openspec/ai-instructions/ for detailed guides.

📖 Documentation

openspec/project.md - Comprehensive project context & conventions
openspec/AGENTS.md - OpenSpec workflow guide
openspec/ai-instructions/ - Detailed customization guides
template.config.json - Configuration schema

🤝 Contributing

This is a template repository. Once you clone it, it's yours to customize!

If you want to contribute improvements back to the template:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📝 License

MIT License - See LICENSE file for details

🙏 Credits

Built with:

React Native
WatermelonDB
React Navigation
And many other amazing open-source projects

🆘 Troubleshooting

Build Fails

# Clean and rebuild
cd android && ./gradlew clean && cd ..
cd ios && pod install && cd ..
npm start -- --reset-cache

Type Errors

npm run typecheck

Linting Issues

npm run lint:fix

Database Issues

# Clear app data and restart
# iOS: Delete app and reinstall
# Android: Settings → Apps → Your App → Clear Data

📞 Support

Documentation: openspec/project.md
Issues: GitHub Issues
Discussions: GitHub Discussions

Built with ❤️ for the React Native community

Start building your app today! 🚀

FilesExpand file tree

README.md

Latest commit

History