🔑 UUID Playground

A modern, production-ready web application for generating and exploring UUIDs with a beautiful glassmorphism interface. Generate UUIDs and view them in multiple formats with one click.

✨ Features

Core Functionality

• Multiple UUID Versions: Generate UUIDv1 (time-based), UUIDv4 (random), and UUIDv7 (time-ordered)
• 8 Format Representations: View each UUID in canonical, hex, braced, URN, decimal, binary, Base64, and URL-safe Base64 formats
• One-Click Copy: Copy any format to clipboard with visual feedback
• UUID Validation: Paste UUID strings (canonical, hex, braced, or URN) to normalize and view all representations
• Lock Feature: Prevent accidental regeneration with UUID lock toggle
• Auto-Generate: Automatically generate new UUIDs at configurable intervals (1-60 seconds)
• Keyboard Shortcuts: Press Space or Enter to generate new UUIDs

UI/UX Excellence

• Glassmorphism Design: Modern translucent panels with blur effects
• Light/Dark Themes: Automatic theme detection with manual toggle (preference saved)
• Smooth Animations: GPU-accelerated animations with non-linear easing
• Responsive Layout: Optimized for desktop, tablet, and mobile devices
• Toast Notifications: Elegant feedback for all user actions
• Accessibility: Full keyboard navigation and ARIA labels

🚀 Live Demo

Visit the live application at: https://uuid.xi-xu.me

🛠️ Tech Stack

• Framework: React 18 with TypeScript
• Build Tool: Vite 5
• Styling: Pure CSS with CSS Variables
• Testing: Vitest
• Deployment: GitHub Actions → GitHub Pages
• UUID Generation: Web Crypto API

📦 Installation & Development

Prerequisites

• Node.js 18+ (LTS recommended)
• npm or yarn

Local Development

1. Clone the repository

   git clone https://github.com/xixu-me/UUID-Playground.git
   cd UUID-Playground
   

2. Install dependencies

   npm install
   

3. Start development server

   npm run dev
   

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

4. Run tests

   # Run tests once
   npm test
   # Run tests in watch mode
   npm run test:watch
   

5. Lint code

   npm run lint
   

6. Build for production

   npm run build
   

   Built files will be in the dist/ directory

7. Preview production build

   npm run preview
   

🚢 Deployment

GitHub Pages Deployment

This repository is configured to automatically deploy to GitHub Pages using GitHub Actions.

Setup Instructions

1. Enable GitHub Pages

   • Go to your repository settings
   • Navigate to Pages section
   • Under "Build and deployment":
     • Source: GitHub Actions

2. Push to main branch

   git push origin main
   

3. Workflow automatically runs

   • Installs dependencies
   • Runs tests
   • Builds the project
   • Deploys to GitHub Pages

4. Access your site

   • Your site will be available at: https://<username>.github.io/<repository-name>/

Workflow Details

The deployment workflow (.github/workflows/deploy.yml):

• Triggers on push to main branch or manual dispatch
• Uses Node.js 20 LTS
• Caches npm dependencies for faster builds
• Runs tests before deployment
• Uploads build artifacts to GitHub Pages
• Deploys using official GitHub Actions

Customizing Repository Name

If you rename the repository, update the base path in vite.config.ts:

export default defineConfig({
  base: '/your-new-repo-name/',
  // ... other config
})

🎨 Customization

Changing Colors

Edit CSS variables in src/styles/App.css:

[data-theme='light'] {
  --accent-primary: #667eea;  /* Primary accent color */
  --accent-hover: #5a67d8;    /* Hover state color */
  /* ... other variables */
}

Adding New UUID Formats

1. Add format conversion in src/lib/uuid.ts:

   export interface UUIDFormats {
     // ... existing formats
     yourNewFormat: string
   }
   

2. Update getAllFormats() function to include new format

3. Add description in App.tsx formatDescriptions object

Modifying Auto-Generate Limits

In src/App.tsx, change the min/max values:

<input
  type="number"
  min="1"    // Minimum seconds
  max="60"   // Maximum seconds
  // ...

/>

🧪 Testing

The repository includes comprehensive tests for UUID utilities:

• UUID Generation: Validates correct version formatting
• UUID Normalization: Tests various input formats
• Format Conversion: Verifies all format representations
• Version Detection: Ensures correct UUID version identification

Run tests:

npm test              # Run once
npm run test:watch    # Watch mode

🔒 Security

• Uses native Web Crypto API for cryptographically secure random generation
• No external dependencies for UUID generation
• Client-side only - no data sent to servers
• No tracking or analytics

♿ Accessibility

• Full keyboard navigation support
• ARIA labels on interactive elements
• Sufficient color contrast ratios
• Respects prefers-reduced-motion
• Focus indicators on all interactive elements

📝 License

Copyright (c) Xi Xu. All rights reserved.

Licensed under the MIT license.

📚 Resources

• UUID Specification (RFC 4122)
• UUID Version 7 Draft
• Web Crypto API
• Vite Documentation
• React Documentation

🙏 Acknowledgments

• Design inspired by modern glassmorphism trends
• UUID generation using Web Crypto API standards
• Built with Vite's lightning-fast tooling

---

Made with ❤️ and TypeScript