npm package: @loudpacks/add-header-native
Description: Add a header with hamburger drawer navigation to your React Native app
Author: srwlli
Latest version: 1.0.0

# @loudpacks/add-header-native

Add a header with hamburger drawer navigation to your React Native app with a single command.

[![npm version](https://img.shields.io/npm/v/@loudpacks/add-header-native.svg)](https://www.npmjs.com/package/@loudpacks/add-header-native)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 📋 **Custom Header** - iOS/Android style header with app title
- ☰ **Hamburger Drawer Menu** - Slide-out navigation with auto-detected screens
- 🎯 **Auto Screen Detection** - Automatically finds your app screens
- 🔷 **Icon Mapping** - Automatically assigns Ionicons to screens
- 🎨 **Native Styling** - Uses StyleSheet for platform-specific look
- 🔄 **Example Screens** - Generates placeholder screens if needed
- ✨ **React Navigation** - Uses industry-standard React Navigation library

## Installation

### Using npx (recommended)

```bash
cd your-react-native-project
npx @loudpacks/add-header-native
```

### Global Installation

```bash
npm install -g @loudpacks/add-header-native
cd your-react-native-project
add-header-native
```

## Requirements

- React Native project (Expo or bare React Native)
- Node.js 18.0.0 or higher

**Peer Dependencies** (will be installed if needed):
- `@react-navigation/drawer` ^6.0.0
- `@react-navigation/native` ^6.0.0
- `react-native-gesture-handler` ^2.0.0
- `react-native-reanimated` ^3.0.0
- `@expo/vector-icons` ^14.0.0

## What It Does

This tool will:

1. ✅ Validate your React Native project
2. 🔍 Auto-detect screens in `src/screens/` or `screens/` directory
3. 📝 Read your app name from package.json
4. 🎨 Generate a `Header.js` component in `src/components/`
5. 🔷 Automatically map Ionicons to your screens
6. 📱 Generate `DrawerNavigator.js` in `src/navigation/`
7. 📄 Create example screen files if needed

## Usage

1. **Run the command:**
```bash
npx @loudpacks/add-header-native
```

2. **Install peer dependencies (if prompted):**
```bash
npm install @react-navigation/drawer @react-navigation/native
npm install react-native-gesture-handler react-native-reanimated
npm install @expo/vector-icons
```

For Expo projects, you may also need:
```bash
npx expo install react-native-gesture-handler react-native-reanimated
```

3. **Update your App.js:**
```javascript
import DrawerNavigator from './src/navigation/DrawerNavigator';

export default function App() {
  return <DrawerNavigator />;
}
```

4. **Run your app:**
```bash
# Expo
expo start

# Bare React Native
npm start
```

## Generated Files

### Header Component
**Location**: `src/components/Header.js`

```javascript
import React from 'react';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import { Ionicons } from '@expo/vector-icons';

export default function Header({ title = 'My App' }) {
  const navigation = useNavigation();

  return (
    <View style={styles.header}>
      {/* Hamburger Menu Button */}
      <TouchableOpacity
        onPress={() => navigation.openDrawer()}
        style={styles.menuButton}
      >
        <Ionicons name="menu" size={28} color="#007AFF" />
      </TouchableOpacity>

      {/* App Title */}
      <Text style={styles.title}>{title}</Text>
    </View>
  );
}
```

### Drawer Navigator
**Location**: `src/navigation/DrawerNavigator.js`

```javascript
import { createDrawerNavigator } from '@react-navigation/drawer';
import { NavigationContainer } from '@react-navigation/native';
import Header from '../components/Header';

const Drawer = createDrawerNavigator();

export default function DrawerNavigator() {
  return (
    <NavigationContainer>
      <Drawer.Navigator
        screenOptions={{
          header: ({ options }) => <Header title={options.title} />,
          drawerActiveTintColor: '#007AFF',
        }}
      >
        <Drawer.Screen name="Home" component={HomeScreen} />
        {/* Auto-generated screens */}
      </Drawer.Navigator>
    </NavigationContainer>
  );
}
```

## Project Structure

After running, your project will have:

```
your-app/
├── src/
│   ├── components/
│   │   └── Header.js              # Header component
│   ├── navigation/
│   │   └── DrawerNavigator.js     # Drawer navigator
│   └── screens/
│       ├── HomeScreen.js          # Auto-generated (if needed)
│       ├── SearchScreen.js
│       ├── ProfileScreen.js
│       └── SettingsScreen.js
├── App.js                         # Update to use DrawerNavigator
└── package.json
```

## Automatic Icon Mapping

The tool automatically assigns Ionicons based on screen names:

| Screen Name | Icon | Ionicon Name |
|-------------|------|--------------|
| home | 🏠 | `home` |
| search | 🔍 | `search` |
| favorites | ❤️ | `heart` |
| profile | 👤 | `person` |
| settings | ⚙️ | `settings` |
| about | ℹ️ | `information-circle` |
| notifications | 🔔 | `notifications` |
| messages | 💬 | `chatbubbles` |
| feed | 📝 | `list` |
| explore | 🧭 | `compass` |
| *other* | ⚫ | `apps` (default) |

## Customization

### Change Header Color

Edit `src/components/Header.js`:

```javascript
const styles = StyleSheet.create({
  header: {
    backgroundColor: '#FF0000', // Change to your brand color
  },
  title: {
    color: '#FFFFFF', // Change title color
  },
});
```

### Change Drawer Width

Edit `src/navigation/DrawerNavigator.js`:

```javascript
<Drawer.Navigator
  screenOptions={{
    drawerStyle: {
      width: 320, // Default is 280
    },
  }}
>
```

### Add Custom Icons

Edit `src/navigation/DrawerNavigator.js`:

```javascript
<Drawer.Screen
  name="CustomScreen"
  component={CustomScreen}
  options={{
    drawerIcon: ({ color, size }) => (
      <Ionicons name="star" size={size} color={color} />
    ),
  }}
/>
```

### Add Custom Header Elements

Edit `src/components/Header.js` to add notifications, search, etc.:

```javascript
export default function Header({ title }) {
  return (
    <View style={styles.header}>
      <TouchableOpacity onPress={() => navigation.openDrawer()}>
        <Ionicons name="menu" size={28} color="#007AFF" />
      </TouchableOpacity>

      <Text style={styles.title}>{title}</Text>

      {/* Add notification bell */}
      <TouchableOpacity onPress={() => {}}>
        <Ionicons name="notifications-outline" size={24} color="#007AFF" />
      </TouchableOpacity>
    </View>
  );
}
```

## Troubleshooting

### Error: "No package.json found"
**Solution**: Run the command from your React Native project root directory.

### Error: "This does not appear to be a React Native project"
**Solution**: Ensure `react-native` or `expo` is in your package.json dependencies.

### Drawer not opening
**Solution**: Make sure you've installed `react-native-gesture-handler` and added it to your app entry:

```javascript
// App.js - Add at the very top
import 'react-native-gesture-handler';
```

### Icons not showing
**Solution**: Install `@expo/vector-icons`:
```bash
npm install @expo/vector-icons
# or for Expo
npx expo install @expo/vector-icons
```

### Reanimated errors
**Solution**: Configure Reanimated plugin in `babel.config.js`:
```javascript
module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: ['react-native-reanimated/plugin'],
};
```

## Screens Detection

The tool searches for screens in these directories (in order):
1. `src/screens/`
2. `screens/`
3. `app/screens/`
4. `src/pages/`
5. `pages/`

**Screen file naming conventions:**
- `HomeScreen.js` → Home
- `ProfileScreen.tsx` → Profile
- `Settings.js` → Settings

If no screens are found, it creates default screens:
- HomeScreen
- SearchScreen
- ProfileScreen
- SettingsScreen

## Compatibility

- ✅ **Expo** (SDK 48+)
- ✅ **React Native** (0.70+)
- ✅ **TypeScript** (use .tsx files)
- ✅ **iOS & Android**

## Related Packages

- [`@loudpacks/add-header`](https://www.npmjs.com/package/@loudpacks/add-header) - Web version for Next.js PWAs
- [`@loudpacks/create-nextjs-pwa`](https://www.npmjs.com/package/@loudpacks/create-nextjs-pwa) - Create Next.js PWA

## Example App.js

```javascript
import 'react-native-gesture-handler'; // Must be at top
import React from 'react';
import DrawerNavigator from './src/navigation/DrawerNavigator';

export default function App() {
  return <DrawerNavigator />;
}
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details

## Author

srwlli

## Support

For issues and questions:
- [Open an issue on GitHub](https://github.com/srwlli/add-header-native/issues)
- Check the troubleshooting section above

---

**Part of the LoudPacks ecosystem** 🚀