🚀 React Frontend Template

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

// 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:

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

# Install specific version
npm install @pattern-stack/[email protected]

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

For Local Development:

# 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

import { createReactApp } from '@pattern-stack/frontend-patterns'

const app = createReactApp("Simple Dashboard")

export default app.render()

Full-Featured Application

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

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

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

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

# Pin to specific version for stability
npm install @pattern-stack/[email protected]

# 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

# 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

# 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

# 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! 🎯