Skip to content

VarunB453/Marvel-Web

BranchesTags

Repository files navigation

Marvel Universe Showcase

React TypeScript Vite License Node PRs Welcome

Overview

Marvel Universe Showcase is a production-ready, single-page React application that demonstrates modern frontend engineering practices through an interactive showcase of Marvel characters, storylines, and cinematic universes. Built with React 18, TypeScript, and advanced animation libraries (GSAP, Framer Motion), this project exemplifies clean architecture, performance optimization, and responsive design patterns.

The application runs entirely client-side with no backend dependencies, making it ideal for static hosting and CDN distribution. All state is managed through React hooks and local TypeScript modules.

Primary Use Cases:

  • Portfolio demonstration of modern React patterns
  • Educational reference for animation systems and responsive design
  • Showcase of component-driven architecture principles
  • Best practices in TypeScript and frontend tooling

Disclaimer: This project is created for educational and portfolio purposes only. It is not affiliated with, endorsed by, or in any way connected to Marvel Studios, Marvel Entertainment, Marvel Characters, Inc., or any related entities.

Table of Contents

  1. Quick Start
  2. System Requirements
  3. Installation
  4. Project Structure
  5. Features
  6. Configuration
  7. Usage & Development
  8. Build & Deployment
  9. Testing
  10. Architecture
  11. API Reference
  12. Performance Considerations
  13. Browser Support
  14. Contributing
  15. Troubleshooting
  16. License
  17. Support & Resources

Quick Start

Prerequisites

  • Node.js: v18.0.0 or higher
  • npm: v9.0.0 or higher (or yarn/pnpm/bun equivalent)
  • Git: For repository management

Installation & Launch

# Clone the repository
git clone https://github.com/VarunB453/Marvel-Web.git
cd Marvel-Web

# Install dependencies
npm install

# Start development server
npm run dev

The application will be available at http://localhost:5173

System Requirements

Minimum Requirements

Component Requirement Notes
Runtime Node.js 18+ LTS versions recommended
Package Manager npm 9+ yarn/pnpm/bun supported
RAM 512 MB For development builds
Disk Space 500 MB With node_modules
Browser Modern ES2020+ See Browser Support section

Recommended Specifications

Component Recommendation
Node.js v20 LTS or latest
RAM 2 GB+ for optimal performance
Processor Multi-core processor
Internet Broadband connection for npm packages

Installation

1. Repository Cloning

# HTTPS
git clone https://github.com/VarunB453/Marvel-Web.git

# SSH
git clone git@github.com:VarunB453/Marvel-Web.git

# GitHub CLI
gh repo clone VarunB453/Marvel-Web

2. Directory Navigation

cd Marvel-Web

3. Dependency Installation

# Using npm (default)
npm install

# Using yarn
yarn install

# Using pnpm
pnpm install

# Using bun
bun install

4. Environment Setup

The application requires no environment variables for basic operation. All configuration is contained in source files.

Optional configuration files:

  • vite.config.ts - Build and development server configuration
  • tsconfig.json - TypeScript compiler settings
  • tailwind.config.ts - Tailwind CSS customization

5. Verification

# Verify installation
npm run dev

# Expected output:
# ✔ Server started at http://localhost:5173

Project Structure

Marvel-Web/
├── public/                           # Static assets
│   ├── favicon.ico
│   └── audio/
│       └── easter-egg.mp3
│
├── src/                              # Source code
│   ├── assets/                       # Media files
│   │   ├── images/
│   │   ├── videos/
│   │   └── MOP.mp4
│   │
│   ├── components/                   # Reusable React components
│   │   ├── ui/                       # Design system components
│   │   │   ├── Button.tsx
│   │   │   ├── Card.tsx
│   │   │   ├── Dialog.tsx
│   │   │   └── [other primitives]
│   │   │
│   │   └── sections/                 # Page-level components
│   │       ├── Header.tsx
│   │       ├── Hero.tsx
│   │       ├── CharacterGallery.tsx
│   │       ├── Timeline.tsx
│   │       └── Footer.tsx
│   │
│   ├── data/                         # Static data modules
│   │   ├── characters.ts             # Character dataset
│   │   ├── universes.ts              # Universe definitions
│   │   ├── timeline.ts               # Saga timeline data
│   │   └── types.ts                  # TypeScript type definitions
│   │
│   ├── hooks/                        # Custom React hooks
│   │   ├── useAnimation.ts
│   │   ├── useResponsive.ts
│   │   ├── useScrollTrigger.ts
│   │   └── useTheme.ts
│   │
│   ├── lib/                          # Utility functions
│   │   ├── animations.ts
│   │   ├── validators.ts
│   │   ├── helpers.ts
│   │   └── constants.ts
│   │
│   ├── pages/                        # Route-based page components
│   │   ├── Home.tsx
│   │   ├── Characters.tsx
│   │   ├── Timeline.tsx
│   │   ├── Universes.tsx
│   │   └── NotFound.tsx
│   │
│   ├── test/                         # Test files
│   │   ├── components.test.tsx
│   │   ├── hooks.test.ts
│   │   └── utils.test.ts
│   │
│   ├── App.tsx                       # Root component with routing
│   ├── main.tsx                      # Application entry point
│   ├── index.css                     # Global styles
│   └── vite-env.d.ts                 # Vite type definitions
│
├── Configuration Files
│   ├── vite.config.ts                # Vite build configuration
│   ├── tsconfig.json                 # TypeScript configuration
│   ├── tailwind.config.ts            # Tailwind CSS configuration
│   ├── postcss.config.js             # PostCSS configuration
│   ├── vitest.config.ts              # Test runner configuration
│   ├── .eslintrc.json                # ESLint rules
│   ├── .prettierrc                   # Code formatter config
│   └── .gitignore                    # Git exclusions
│
├── package.json                      # Project manifest & dependencies
├── package-lock.json                 # Locked dependency versions
├── README.md                         # This file
├── LICENSE                           # Apache 2.0 license
└── .github/
    ├── CONTRIBUTING.md               # Contribution guidelines
    ├── CODE_OF_CONDUCT.md            # Community standards
    └── ISSUE_TEMPLATE/               # Issue templates

Features

1. Character Galleries

Description: Interactive gallery system for browsing Marvel characters

Capabilities:

  • Dynamic grid layout with responsive columns
  • Smooth hover animations and transitions
  • Character filtering by role (hero/villain)
  • Character search and sorting functionality
  • Detailed character information cards
  • Image lazy-loading for performance

Implementation Details:

  • Component: src/components/sections/CharacterGallery.tsx
  • Data Source: src/data/characters.ts
  • Animation Library: Framer Motion
  • Styling: Tailwind CSS + custom animations

2. Multiverse Directory

Description: Visualizes alternate universes and parallel realities

Capabilities:

  • Parallax scrolling effects
  • Cinematic transition animations
  • Layered visual depth
  • Universe-specific information sections
  • Timeline integration
  • Responsive layout across devices

Technical Stack:

  • Animation: GSAP with ScrollTrigger
  • Styling: Tailwind CSS
  • Performance: GPU-accelerated transforms

3. Infinity Saga Timeline

Description: Chronological presentation of Marvel Cinematic Universe phases

Capabilities:

  • Scroll-triggered phase animations
  • Dynamic timeline visualization
  • Key event markers and descriptions
  • Phase grouping and organization
  • Mobile-responsive layout

Technology:

  • GSAP ScrollTrigger for scroll events
  • React state management for phase tracking
  • Responsive breakpoints for mobile/tablet/desktop

4. Responsive Design System

Description: Comprehensive responsive design across all screen sizes

Breakpoints:

Mobile:     320px - 640px
Tablet:     641px - 1024px
Desktop:    1025px - 1440px
Ultra-Wide: 1441px+

Implementation:

  • Tailwind CSS utility-first approach
  • Mobile-first design methodology
  • CSS media queries
  • Flexible layouts with Flexbox/Grid

5. Animation System

Description: Sophisticated motion design throughout the application

Components:

  • Framer Motion: Component-level animations

    • Entrance animations
    • Hover effects
    • Exit transitions

  • GSAP: Advanced scroll-based animations

    • ScrollTrigger for timeline
    • Complex sequences
    • Parallax effects

Performance Metrics:

  • Target: 60 FPS minimum
  • Optimization: GPU acceleration, will-change CSS
  • Monitoring: React DevTools Profiler

6. Interactive Elements

Description: User interaction features and easter eggs

Features:

  • Right-click context menu (plays audio effect)
  • Hover state feedback on all clickable elements
  • Smooth scroll behavior
  • Keyboard navigation support
  • Touch-friendly interactions for mobile

Accessibility:

  • ARIA labels and roles
  • Keyboard focus indicators
  • Screen reader compatibility
  • Color contrast compliance (WCAG AA)

Configuration

Vite Configuration (vite.config.ts)

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    strictPort: false,
    host: true
  },
  build: {
    outDir: 'dist',
    sourcemap: false
  }
})

TypeScript Configuration (tsconfig.json)

Configured with strict mode for maximum type safety.

Environment Variables

Create .env.local for environment-specific settings:

VITE_ENVIRONMENT=development
VITE_DEBUG=true

Usage & Development

Development Workflow

# Start development server with hot-reload
npm run dev

# Run type checking
npm run type-check

# Run linter
npm run lint

# Format code
npm run format

Available Commands

Command Purpose Output
npm run dev Start dev server http://localhost:5173
npm run build Production build /dist folder
npm run preview Preview production build Local server
npm run test Run test suite Test results
npm run test:watch Watch mode testing Continuous testing
npm run lint Check code quality ESLint report
npm run format Format code Applied Prettier rules
npm run type-check TypeScript checking Type errors

Code Style Guidelines

Naming Conventions:

  • Components: PascalCase (CharacterCard.tsx)
  • Functions: camelCase (handleCharacterSelect())
  • Constants: UPPER_SNAKE_CASE (MAX_CHARACTERS = 50)
  • Hooks: camelCase starting with use (useAnimation())

Build & Deployment

Production Build

# Create optimized build
npm run build

# Verify build
npm run preview

Build Optimization

The build process includes:

  • Code minification
  • Tree-shaking unused code
  • CSS purging (Tailwind)
  • Asset compression
  • Source map generation (optional)

Deployment Targets

Vercel (Recommended)

npm i -g vercel
vercel --prod

Netlify

npm i -g netlify-cli
netlify deploy --dir=dist --prod

GitHub Pages

npm run build
git subtree push --prefix dist origin gh-pages

Cloudflare Pages

Push to repository, Cloudflare auto-deploys with:

  • Build command: npm run build
  • Output directory: dist

Testing

Test Framework Setup

# Run test suite
npm run test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Testing Strategy

Unit Tests:

  • Utility function behavior
  • Component rendering
  • Hook functionality

Integration Tests:

  • Page navigation
  • Data flow between components
  • Animation triggers

Architecture

Component Architecture

App (Root)
├── Layout
│   ├── Header
│   ├── Navigation
│   ├── MainContent (Route-dependent)
│   │   ├── Home
│   │   ├── Characters
│   │   ├── Timeline
│   │   └── Universes
│   └── Footer

State Management

React Context + Hooks (no Redux needed for this scope)

Data Flow

User Input → Event Handler → State Update 
→ Re-render Component → Animation Trigger 
→ Visual Update

API Reference

Core Components

<CharacterGallery />

Props:

interface CharacterGalleryProps {
  filter?: 'all' | 'heroes' | 'villains';
  sortBy?: 'name' | 'power' | 'appearance';
  onSelect?: (character: Character) => void;
  pageSize?: number;
}

<Timeline />

Props:

interface TimelineProps {
  startYear?: number;
  endYear?: number;
  onPhaseChange?: (phase: Phase) => void;
}

Custom Hooks

useAnimation()

const { animate, stop, isAnimating } = useAnimation({
  duration: 600,
  easing: 'ease-out'
});

Performance Considerations

Optimization Techniques

  1. Code Splitting

    • Route-based chunking
    • Lazy component loading

  2. Image Optimization

    • WebP format with fallbacks
    • Responsive images (srcset)
    • Lazy loading intersection observer

  3. Animation Performance

    • GPU acceleration (transform, opacity)
    • Will-change property
    • RequestAnimationFrame for smooth updates

  4. Memory Management

    • Cleanup subscriptions in useEffect
    • Proper event listener removal
    • Avoiding memory leaks

Browser Support

Supported Browsers

Browser Minimum Version Status
Chrome v90+ Full support
Firefox v88+ Full support
Safari v14+ Full support
Edge v90+ Full support
Opera v76+ Full support
IE 11 — Not supported

Feature Support

  • ES2020 syntax required
  • CSS Grid & Flexbox
  • CSS Variables
  • Intersection Observer API
  • LocalStorage API

Contributing

Contribution Process

  1. Fork the Repository

    git clone https://github.com/YOUR_USERNAME/Marvel-Web.git
cd Marvel-Web

  2. Create Feature Branch

    git checkout -b feature/amazing-feature

  3. Make Changes

    • Follow code style guidelines
    • Write tests for new features
    • Update documentation

  4. Commit Changes

    git commit -m "feat: Add amazing feature"

  5. Push to Fork

    git push origin feature/amazing-feature

  6. Create Pull Request

    • Describe changes clearly
    • Link related issues
    • Ensure CI/CD passes

Code Standards

Pre-commit Checklist:

  • Code follows ESLint rules
  • Code formatted with Prettier
  • TypeScript strict mode passes
  • All tests pass
  • No console errors or warnings
  • Documentation updated if applicable

Troubleshooting

Common Issues & Solutions

Port 5173 Already in Use

# Option 1: Use different port
npm run dev -- --port 3000

# Option 2: Kill process on port (macOS/Linux)
lsof -ti:5173 | xargs kill -9

TypeScript Errors After Dependency Update

rm -rf node_modules package-lock.json
npm install
npm run dev

Styles Not Updating in Development

rm -rf .vite
npm run dev

Animations Stuttering or Janky

// Enable hardware acceleration
.animated-element {
  will-change: transform;
  transform: translateZ(0);
}

Build Size Too Large

npm run build -- --analyze
# Look for opportunities to code-split or optimize images

Audio Not Playing

  • Browser autoplay policy requires user interaction first
  • Click anywhere on page before testing
  • Check browser audio permissions
  • Verify audio file path

License

This project is licensed under the Apache License 2.0.

Summary

You are free to:

  • ✅ Use the code commercially
  • ✅ Modify the code
  • ✅ Distribute copies
  • ✅ Use privately

Under the condition:

  • ⚠️ Include license and copyright notice
  • ⚠️ Document significant changes

Full License: See LICENSE file

Support & Resources

Documentation

Useful Links

Technology Documentation:

Community & Communication

Changelog

Version 1.0.0 (Initial Release)

Features:

  • Character gallery with filtering
  • Multiverse directory
  • Infinity Saga timeline
  • Fully responsive design
  • Animation system
  • Interactive elements

Tech Stack:

  • React 18.0
  • TypeScript
  • Vite
  • Tailwind CSS
  • GSAP & Framer Motion

Authors & Contributors

Original Author: Varun B. (@VarunB453)

Contributors: See contributors list

Acknowledgments

This project was created to demonstrate:

  • Modern React patterns and best practices
  • Advanced CSS animation techniques
  • Responsive design methodologies
  • Component-driven architecture
  • TypeScript in production applications
  • Performance optimization strategies

Last Updated: March 2026
Maintained By: Community Contributors
Status: Active Development

About

Marvel Universe Showcase is a React + TypeScript single-page application featuring animated hero and villain galleries, a multiverse directory, and an Infinity Saga timeline. Built with Tailwind CSS, Framer Motion, and GSAP to demonstrate modern frontend architecture, responsive design, and cinematic UI animations.

marvel.gt.tc

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages