npm package: @loudpacks/add-header
Description: Add a sticky header with hamburger navigation menu to your Next.js PWA project
Author: srwlli
Latest version: 1.1.6

# @loudpacks/add-header

Add a sticky header with hamburger navigation menu to your Next.js PWA project with a single command.

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

## Features

- 📋 **Sticky Header** - Always visible at the top of your app
- ☰ **Hamburger Navigation Menu** - Slide-out drawer with auto-detected tab pages
- 🎨 **Theme Integration** - Automatically integrates with your project's theme configuration
- 🎯 **Smart Tab Detection** - Automatically finds and links all your tab pages
- 🔷 **Icon Mapping** - Automatically assigns appropriate Lucide icons to pages
- 🔄 **Automatic Backup** - Creates backup of original files before modification
- ✨ **Zero Config** - Works out of the box with Next.js PWA projects
- 🎯 **V3 Tab Support** - Designed for tab-based PWA projects

## Installation

### Using npx (recommended)

```bash
cd your-nextjs-pwa-project
npx @loudpacks/add-header
```

### Global Installation

```bash
npm install -g @loudpacks/add-header
cd your-nextjs-pwa-project
add-header
```

## Requirements

- Next.js project with App Router (`src/app`)
- V3 tab-based PWA structure (`src/app/(tabs)`)
- Theme configuration file (`src/config/theme.ts`)
- `lucide-react` installed in your project
- Node.js 18.0.0 or higher

**Note**: If you don't have `lucide-react`, install it first:
```bash
npm install lucide-react
```

## What It Does

This tool will:

1. ✅ Validate your Next.js PWA project structure
2. 🔍 Auto-detect all tab pages in `src/app/(tabs)/`
3. 📝 Read your project information (app title, theme)
4. 🎨 Generate a `Header.tsx` component with hamburger navigation in `src/components/`
5. 🔷 Automatically map icons to your tab pages
6. 🔄 Update `src/app/(tabs)/layout.tsx` to include the header
7. 💾 Create a backup of your original layout file

## Usage

Simply navigate to your Next.js PWA project directory and run:

```bash
npx @loudpacks/add-header
```

The tool will automatically:
- Detect your project structure
- Extract your app title from `package.json` or `layout.tsx`
- Apply your existing theme configuration
- Add the sticky header component

## Generated Header Component

The generated `Header.tsx` component includes:

### Features:
- **Hamburger menu icon** (top left) - Toggles navigation drawer
- **App title "Next.js PWA"** (top right) - Theme-aware styling
- **Slide-out navigation drawer** - Full navigation menu with icons
- **Auto-detected tab pages** - Links to all your app pages
- **Active page highlighting** - Shows current page in navigation
- **Theme integration** - Respects grayscale/modern mode

### Component Structure:
```tsx
'use client'

import { useState } from 'react'
import Link from 'next/link'
import { usePathname } from 'next/navigation'
import { Menu, X, Home, Search, Heart, User, Settings } from 'lucide-react'
import { THEME, STYLE } from '@/config/theme'

export default function Header() {
  const [isOpen, setIsOpen] = useState(false)
  const pathname = usePathname()
  const isGrayscale = STYLE.mode === 'grayscale'

  const navItems = [
    { name: 'Home', href: '/home', icon: Home },
    { name: 'Search', href: '/search', icon: Search },
    // ... auto-detected tabs
  ]

  return (
    <>
      {/* Sticky Header with Hamburger & Title */}
      <header className={`sticky top-0 z-40 w-full border-b`}>
        <div className="container mx-auto px-4 h-14 flex items-center justify-between">
          <button onClick={() => setIsOpen(!isOpen)}>
            {isOpen ? <X /> : <Menu />}
          </button>
          <h1>Next.js PWA</h1>
        </div>
      </header>

      {/* Slide-out Navigation Drawer */}
      {isOpen && (
        <>
          <div className="fixed inset-0 bg-black/50" onClick={() => setIsOpen(false)} />
          <nav className="fixed top-14 left-0 bottom-0 w-64">
            {/* Navigation links with icons */}
          </nav>
        </>
      )}
    </>
  )
}
```

## Updated Layout

Your `src/app/(tabs)/layout.tsx` will be updated to:

```tsx
import TabNavigation from '@/components/TabNavigation'
import Header from '@/components/Header'

export default function TabsLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Header />
      <div className="pt-0 pb-16">
        {children}
        <TabNavigation />
      </div>
    </>
  )
}
```

## Project Structure

Your project should have this structure:

```
your-pwa-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   └── (tabs)/
│   │       ├── layout.tsx         # Will be updated
│   │       ├── home/page.tsx
│   │       ├── search/page.tsx
│   │       └── ...
│   ├── components/
│   │   ├── TabNavigation.tsx
│   │   └── Header.tsx             # Will be created
│   └── config/
│       └── theme.ts               # Required
└── package.json
```

## Automatic Icon Mapping

The tool automatically assigns appropriate Lucide icons based on your page names:

| Page Name | Icon | Lucide Component |
|-----------|------|------------------|
| home | 🏠 | `Home` |
| search | 🔍 | `Search` |
| favorites | ❤️ | `Heart` |
| profile | 👤 | `User` |
| settings | ⚙️ | `Settings` |
| about | ℹ️ | `Info` |
| notifications | 🔔 | `Bell` |
| messages | 💬 | `MessageCircle` |
| feed | 📝 | `List` |
| explore | 🧭 | `Compass` |
| *other* | ⚪ | `Circle` (default) |

**Custom pages** will automatically use the `Circle` icon. You can manually update the icon in the generated `Header.tsx` component.

## Configuration

The header automatically reads from your `src/config/theme.ts`:

```typescript
export const THEME = {
  primary: '#3B82F6',
  secondary: '#1E40AF',
  accent: '#60A5FA',
} as const;

export const STYLE = {
  mode: 'grayscale' as 'grayscale' | 'modern',
} as const;
```

## Customization

After installation, you can customize the header by editing:

**`src/components/Header.tsx`**

Example customizations:

### Change Navigation Icons
Edit the `navItems` array in the generated component:

```tsx
const navItems = [
  { name: 'Home', href: '/home', icon: Home },
  { name: 'Search', href: '/search', icon: Search },
  { name: 'Custom', href: '/custom', icon: Star }, // Change icon
]
```

### Adjust Drawer Width
Change the drawer width class:

```tsx
<nav className="fixed top-14 left-0 bottom-0 w-80"> {/* Changed from w-64 */}
```

### Add Additional Header Elements
Add elements to the header (like notifications):

```tsx
import { Bell } from 'lucide-react'

<header className="...">
  <div className="container mx-auto px-4 h-14 flex items-center justify-between">
    <button onClick={() => setIsOpen(!isOpen)}>
      {isOpen ? <X /> : <Menu />}
    </button>

    {/* Add notification bell */}
    <div className="flex items-center gap-4">
      <Bell className="w-5 h-5" />
      <h1>Next.js PWA</h1>
    </div>
  </div>
</header>
```

### Change Title Position
Move title to center:

```tsx
<div className="container mx-auto px-4 h-14 flex items-center justify-between">
  <button onClick={() => setIsOpen(!isOpen)}>
    {isOpen ? <X /> : <Menu />}
  </button>

  <h1 className="absolute left-1/2 transform -translate-x-1/2">
    Next.js PWA
  </h1>

  <div /> {/* Spacer for centering */}
</div>
```

## Backup & Rollback

The tool automatically creates a backup of your original layout:

**Backup location**: `src/app/(tabs)/layout.tsx.backup`

To rollback:
```bash
# Windows
copy src\app\(tabs)\layout.tsx.backup src\app\(tabs)\layout.tsx

# macOS/Linux
cp src/app/\(tabs\)/layout.tsx.backup src/app/\(tabs\)/layout.tsx
```

## Troubleshooting

### Error: "No package.json found"
**Solution**: Make sure you're running the command from your project root directory where `package.json` is located.

### Error: "This does not appear to be a Next.js project"
**Solution**: Ensure `next` is listed in your `package.json` dependencies.

### Error: "This project does not use the App Router structure"
**Solution**: This tool requires the `src/app` directory structure. Migrate to App Router if needed.

### Error: "This script is designed for V3 tab-based PWA projects"
**Solution**: Ensure you have a `src/app/(tabs)` directory. This tool is specifically for tab-based PWA projects.

### Error: "Theme configuration not found"
**Solution**: Create a `src/config/theme.ts` file with `THEME` and `STYLE` exports:

```typescript
export const THEME = {
  primary: '#3B82F6',
  secondary: '#1E40AF',
  accent: '#60A5FA',
} as const;

export const STYLE = {
  mode: 'grayscale' as 'grayscale' | 'modern',
} as const;
```

## Compatibility

Works with projects created using:
- [`@loudpacks/create-nextjs-pwa`](https://www.npmjs.com/package/@loudpacks/create-nextjs-pwa)
- Next.js 15+ with App Router
- Any V3 tab-based PWA project with the required structure

## Related Packages

- [`@loudpacks/create-nextjs-pwa`](https://www.npmjs.com/package/@loudpacks/create-nextjs-pwa) - Create a new Next.js PWA project
- `@loudpacks/add-auth-clerk` - Add Clerk authentication
- `@loudpacks/add-darkmode` - Add dark mode toggle

## 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/issues)
- Check the troubleshooting section above

---

**Part of the LoudPacks ecosystem** 🚀