npm package: @pattern-stack/frontend-patterns
Description: Production-ready React frontend template with atomic architecture patterns. Build ultra-lean applications by importing shared UI foundation patterns.
Author: Pattern Stack Team
Latest version: 0.2.0-alpha.11

# 🚀 React Frontend Template

[![React 18.3+](https://img.shields.io/badge/React-18.3+-blue.svg)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-green.svg)](https://www.typescriptlang.org/)
[![Code style: Prettier](https://img.shields.io/badge/code%20style-prettier-000000.svg)](https://github.com/prettier/prettier)

A production-ready React frontend template with atomic architecture patterns. Build ultra-lean applications by importing shared UI foundation patterns instead of copying boilerplate code.

## 🎯 Philosophy

**Importable Frontend Foundation** - Just like your backend template, create a shared React foundation that your applications import as a dependency, keeping individual apps ultra-lean and architecturally consistent.

## ⚡ Quick Start

### Create a New Application

```typescript
// main.tsx
import { createReactApp } from '@pattern-stack/frontend-patterns'

const app = createReactApp({
  title: "Analytics Dashboard",
  description: "Business analytics application",
  version: "1.0.0",
  enableAuth: true,
  apiUrl: "http://localhost:8080/api/v1"
})

// Add your business logic
import { DashboardRoutes, ReportsRoutes } from './routes'
app.addRoutes("/dashboard", DashboardRoutes)
app.addRoutes("/reports", ReportsRoutes)
```

### Installation

This is a private package published to npm. Install using standard npm commands:

```bash
# Install latest version
npm install @pattern-stack/frontend-patterns

# Install specific version
npm install @pattern-stack/frontend-patterns@0.2.0-alpha.0

# Or add to package.json dependencies
{
  "dependencies": {
    "@pattern-stack/frontend-patterns": "^0.2.0-alpha.0"
  }
}
```

**For Local Development:**
```bash
# Install from local filesystem
npm install file:../path/to/frontend-patterns

# Or link for active development
npm link ../path/to/frontend-patterns
```

## 🏗️ Template Architecture

```
frontend-patterns/
├── atoms/                    # Foundation primitives
│   ├── shared/              # Common dependencies (settings, events, infrastructure)
│   ├── ui/                  # UI base components (Button, Card, Input)
│   ├── types/               # Shared enums and types
│   └── security/            # JWT, auth utilities
├── molecules/               # Composed functionality
│   ├── auth/                # Authentication workflows
│   ├── forms/               # Form composition patterns
│   └── layout/              # Layout composition patterns
├── organisms/               # Complete interface modules
│   ├── providers/           # React context providers
│   ├── routing/             # Route management patterns
│   └── theming/             # Design system enforcement
├── template/                # Template-specific utilities
│   └── factory.tsx          # Configurable React app factory
└── examples/                # Example implementations
```

## 🎨 What You Get

### ✅ Production-Ready Infrastructure
- **Authentication**: JWT tokens, user workflows, protected routes
- **Design System**: 8 semantic color palettes with enforcement via ESLint
- **Type Safety**: Generated types from OpenAPI specifications
- **State Management**: TanStack Query for server state, Zustand patterns
- **Theming**: CSS custom properties with dark mode support
- **Routing**: File-based routing with authentication guards

### ❌ What You DON'T Need to Build
- Auth system (JWT, middleware, user models) - from template
- UI components (Button, Card, Form primitives) - from template
- Layout components (AppHeader, Sidebar, navigation) - from template
- Design system (colors, spacing, theming) - from template
- API client setup (axios, interceptors, types) - from template
- State management (global state, async patterns) - from template

## 🚀 Service Examples

### Minimal Application
```typescript
import { createReactApp } from '@pattern-stack/frontend-patterns'

const app = createReactApp("Simple Dashboard")

export default app.render()
```

### Full-Featured Application
```typescript
import { 
  createReactApp,
  AuthProvider,
  QueryProvider
} from '@pattern-stack/frontend-patterns'

const app = createReactApp({
  title: "User Management Dashboard",
  description: "Complete user management with analytics",
  enableAuth: true,
  enableQuery: true,
  apiUrl: "http://localhost:8080/api/v1",
  theme: "corporate"
})

// Your business logic only
import { UserRoutes, AnalyticsRoutes } from './routes'
app.addRoutes("/users", UserRoutes)
app.addRoutes("/analytics", AnalyticsRoutes)
```

## 🔧 Template Features

### Configurable App Factory
```typescript
createReactApp({
  title: "My Service",
  description: "Service description",
  version: "1.0.0",
  
  // Core features
  enableAuth: true,
  enableQuery: true,
  enableTheming: true,
  enableRouting: true,
  
  // API configuration
  apiUrl: "http://localhost:8080/api/v1",
  apiTimeout: 10000,
  
  // Theme configuration
  theme: "corporate",
  darkMode: true,
  
  // Custom providers
  customProviders: [MyCustomProvider]
})
```

### Authentication Patterns
```typescript
import { useAuth, ProtectedRoute } from '@pattern-stack/frontend-patterns'

function MyAuthComponent() {
  const { user, login, logout, isAuthenticated } = useAuth()
  
  return (
    <ProtectedRoute>
      <Dashboard user={user} />
    </ProtectedRoute>
  )
}
```

### Type-Safe API Patterns
```typescript
import { useApiQuery, ApiClient } from '@pattern-stack/frontend-patterns'
import type { User, CreateUserRequest } from '@pattern-stack/frontend-patterns/types'

function UserManagement() {
  const { data: users } = useApiQuery<User[]>('/api/users')
  const createUser = useApiMutation<User, CreateUserRequest>('/api/users')
  
  return <UserList users={users} onCreate={createUser.mutate} />
}
```

## 🔥 Template Benefits

### 🔐 Centralized Security
- Update JWT logic once, all apps get it
- Consistent authentication patterns
- Security best practices enforced

### 🚀 Rapid Development  
- New app = business logic only
- No authentication or UI component boilerplate
- Production-ready from day one

### 📊 Unified Design System
- Same component library across apps
- Consistent user experience
- Design system compliance enforced

### 🛡️ Consistent Quality
- Template enforces code patterns
- Shared linting and formatting rules
- Centralized dependency management

### ⚡ Easy Updates
- Update template version, all apps benefit
- Breaking changes managed centrally
- Feature rollouts across entire platform

## 🎯 Use Cases

Perfect for:
- **Micro-frontend architectures** with shared patterns
- **Platform teams** providing infrastructure to product teams
- **Startups** needing rapid, consistent development
- **Enterprise** standardizing frontend patterns

## 📚 Examples

Check out the `examples/` directory for complete app implementations:

- **Simple App**: Minimal template usage
- **Auth App**: Complete authentication with user management
- **Dashboard App**: Full business dashboard with charts and data
- **Multi-tenant App**: Tenant isolation patterns

## 🔄 Template Versioning

```bash
# Pin to specific version for stability
npm install @pattern-stack/frontend-patterns@1.2.0

# Use latest for new development
npm install @pattern-stack/frontend-patterns@latest
```

### Version History
- **v1.0.0** - Initial release with auth + design system patterns
- **v1.1.0** - Added advanced routing + state management
- **v1.2.0** - Enhanced theming + performance optimizations
- **v2.0.0** - Breaking: Redesigned component API patterns

## 🛠️ Development & Testing

### Building the Library

```bash
# Clean and build distribution files
npm run build:lib

# Clean dist folder only
npm run clean

# Development server (for template development)
npm run dev
```

### Testing Locally Before Publishing

```bash
# 1. Build the library
npm run build:lib

# 2. Create a test application
mkdir test-app && cd test-app
npm init -y
npm install react react-dom @types/react @types/react-dom

# 3. Install the template
npm install @pattern-stack/frontend-patterns

# 4. Create test app
cat > main.tsx << 'EOF'
import { createReactApp } from '@pattern-stack/frontend-patterns'

const app = createReactApp({
  title: "Test App",
  enableAuth: true
})

export default app
EOF

# 5. Test imports work
npx tsc --noEmit main.tsx
```

### Package Contents Verification

```bash
# Check what will be published
npm pack --dry-run

# Verify dist folder contents
ls -la dist/
```

## 🤝 Contributing

1. Fork the template repository
2. Create a feature branch
3. Add your enhancement to the appropriate layer (atoms/molecules/organisms)
4. **Build and test locally** with `npm run build:lib`
5. Add tests and documentation
6. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details.

---

**Built with ❤️ for the micro-frontend era**

This template enables the Netflix/Airbnb model for frontend development - shared foundation, app-specific innovation, zero architectural drift! 🎯