feat: introducing 31 new react sdk samples

[amberkamboj77]

feat: acul samples with @auth0/auth0-acul-js sdk and @auth0/auth0-acul-react usage

Overview

This PR introduces a major architectural transformation, converting the repository from a single-template structure to a comprehensive monorepo containing production-ready Auth0 Advanced Customizations for Universal Login (ACUL) samples. This change significantly expands the repository's scope from 3 basic login screens to 31 fully-implemented authentication flows across two distinct SDK implementations.

Change Summary

• Old Architecture: Single template with 3 screens using Auth0 ACUL JS SDK
• New Architecture: Monorepo with 2 independent samples (34 screens total)
  • react-js/: 3 screens using @auth0/auth0-acul-js (production-ready)
  • react/: 31 screens using @auth0/auth0-acul-react (comprehensive coverage)

Architecture & Design

Monorepo Structure

This conversion establishes a scalable foundation for multiple ACUL implementations:
auth0-acul-samples/
├── react-js/ # JS SDK implementation (3 screens)
├── react/ # React SDK implementation (31 screens)
├── manifest.json # Central deployment manifest
└── scripts/ # Shared tooling and validation

Why Monorepo?

1. Unified Development Experience: Shared tooling, linting, and CI/CD workflows
2. SDK Comparison: Developers can compare JS SDK vs React SDK implementations side-by-side
3. Scalability: Easy to add new samples (Vue, Angular, etc.) without fragmenting documentation
4. Consistent Versioning: All samples stay synchronized with Auth0 platform updates

Auth0 CLI Integration

Manifest-Driven Deployment

The new manifest.json serves as the single source of truth for Auth0 CLI integration, enabling automated deployment of ACUL screens.

Key Features:

• Template Discovery: Auto-detects sample directories (react/, react-js/)
• Screen Registration: Maps each authentication screen to its source directory
• Base File Management: Defines shared components, utilities, and assets
• Validation Pipeline: CI validates manifest integrity on every commit

Deployment Workflow:

1. Developer builds screen locally (npm run build)
2. CI validates manifest references exist
3. Auth0 CLI reads manifest to discover screens
4. Screens are deployed to Auth0 tenant via automated pipeline

ul-context-inspector Integration

Offline Development

One of the most impactful additions is the integration of @auth0/ul-context-inspector, a development tool that eliminates the need for Auth0 tenant connections during local development.

What It Solves:

• Before: Developers needed live Auth0 tenant + complex proxy setup for local dev
• After: Fully offline development with mock Auth0 context injection

Features:

1. Visual Context Inspector: Sidebar panel showing current Auth0 context state
2. Screen Switching: Dropdown to switch between screens without navigation
3. Mock Data Injection: Load predefined context scenarios (errors, edge cases)
4. Real-Time Updates: Modify context and see screen react instantly

Implementation:

• DevScreenManager.tsx: Wraps screens with context inspector in development
• ProdScreenManager.tsx: Production-mode router (no inspector overhead)
• public/universal-login-context-*.json: Context schemas and mock data

This dramatically reduces development friction—developers can build and test screens without Auth0 tenant access.

SDK Coverage

React-JS Sample (JS SDK)

SDK: @auth0/auth0-acul-js
Paradigm: Imperative API (manual state management)

Screens:

• login - Universal login with social providers
• login-id - Identifier-first flow
• login-password - Password entry screen

Use Cases: Maximum control over state, suitable for complex custom flows

React Sample (React SDK)

SDK: @auth0/auth0-acul-react
Paradigm: React hooks (declarative, state managed by SDK)

Key Improvements

For Developers

1. Comprehensive Examples: 31 production-ready screen implementations covering entire auth journey
2. Offline Development: No Auth0 tenant required for local development
3. SDK Flexibility: Compare JS SDK vs React SDK to choose best fit
4. Type Safety: Full TypeScript coverage with Auth0 SDK types
5. Testing Infrastructure: Jest + React Testing Library with 80%+ coverage
6. Theme System: Dynamic Auth0 theme extraction and CSS variable mapping

For Operations

1. Automated Deployment: Manifest-driven Auth0 CLI integration
2. CI/CD Validation: Pre-merge checks for manifest integrity, linting, tests
3. Monorepo Tooling: Unified scripts for building, testing, deploying all samples
4. Version Control: Single repository for all ACUL sample implementations

For Product Teams

1. Reference Architecture: Production-grade patterns for custom auth screens
2. Accessibility: WCAG compliance across all components
3. Responsive Design: Mobile-first Tailwind CSS implementation
4. Extensibility: Clear patterns for adding new screens/samples

🔧 Technical Highlights

Build System

• Vite: Lightning-fast HMR with dynamic screen entry points
• Dynamic Screen Loading: Screens auto-discovered and loaded at runtime
• Tree-Shaking: Per-screen bundles for optimal performance

Component Architecture

• ULTheme Components: Auth0-branded components with CVA variants
• Theme Engine: Flattens Auth0 theme API into CSS variables
• Base UI: Shadcn/ui components as foundation layer

Quality Assurance

• ESLint: Flat config with React 19 best practices
• Prettier: Consistent code formatting
• Husky: Pre-commit hooks for lint-staged
• TypeScript: Strict mode enabled

Documentation

Each sample includes comprehensive documentation:

• README.md: Quick start, development, deployment guides
• DEPLOYMENT.md: Auth0 CLI integration and production deployment
• GitHub Actions Documentation: CI/CD pipeline explanations
• Inline Comments: JSDoc for complex utilities and hooks