uuid-playground/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

UUID Playground is a React + TypeScript single-page application for generating and exploring UUIDs. It supports multiple UUID versions (v1, v4, v7) and displays each UUID in 8 different format representations. The application uses Web Crypto API for cryptographically secure UUID generation and features a glassmorphism UI with light/dark themes.

Development Commands

# Development
npm run dev              # Start Vite dev server at http://localhost:5173

# Testing
npm test                 # Run tests once with Vitest
npm run test:watch       # Run tests in watch mode

# Linting & Building
npm run lint             # ESLint check with TypeScript
npm run build            # TypeScript check + Vite production build
npm run preview          # Preview production build locally

Architecture & Code Structure

Core UUID Logic (src/lib/uuid.ts)

The heart of the application - all UUID generation and conversion logic:

• Generation Functions: generateUUIDv1(), generateUUIDv4(), generateUUIDv7() use Web Crypto API directly
• Format Conversions: getAllFormats() converts a UUID to 8 representations (canonical, hex, braced, URN, decimal, binary, base64, base64url)
• Validation: normalizeUUID() accepts various input formats (canonical, hex, braced, URN) and normalizes to canonical format
• Byte Operations: Uses Uint8Array for low-level UUID manipulation, BigInt for 128-bit arithmetic
• Version Detection: detectUUIDVersion() reads version bits from UUID bytes

When modifying UUID logic, remember that UUIDs are 128-bit (16 bytes) with specific bit positions for version and variant fields.

Custom Hooks (src/hooks/)

Reusable React hooks following standard patterns:

• useTheme: Manages light/dark theme, persists to localStorage key uuid-playground-theme, syncs with data-theme attribute
• useToast: Toast notification system with 3-second auto-dismiss, generates random IDs
• useKeyboard: Global keyboard handler that ignores events from input/textarea elements

All hooks return stable references using useCallback where appropriate.

Component Architecture

• App.tsx: Main component with all application state (UUID, formats, lock, version, auto-generate). Uses React hooks for state management
• FormatCard: Reusable card component for displaying each UUID format with copy functionality
• ValidationPanel: Handles UUID input/validation using normalizeUUID()
• Toast: Notification component styled with glassmorphism
• InfoPanel: Static information display

State flows unidirectionally from App to components via props.

Styling (src/styles/App.css)

Pure CSS with CSS variables for theming. Uses [data-theme='light'] and [data-theme='dark'] attribute selectors. Glassmorphism effects achieved through backdrop-filter. All animations use GPU-accelerated transforms.

Testing

Tests are in src/lib/uuid.test.ts using Vitest with jsdom environment. The test suite covers:

• UUID generation for each version (validates format and version bits)
• Normalization of various input formats
• Format conversions (all 8 representations)
• Version detection
• Edge cases and error handling

When adding UUID functionality, add corresponding test cases following existing patterns.

Deployment Configuration

GitHub Pages Setup

The repository uses GitHub Actions for deployment (.github/workflows/deploy.yml):

• Triggers on push to main branch
• Runs npm test before building (deployment fails if tests fail)
• Builds with npm run build (creates dist/ directory)
• Deploys to GitHub Pages

Important: Repository Name Changes

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

export default defineConfig({
  base: '/your-new-repo-name/',  // Must match repository name
  // ...
})

The base path is required for asset URLs to work correctly on GitHub Pages.

Key Implementation Details

UUID Generation Strategy

• v4 (Random): Uses crypto.randomUUID() when available, falls back to manual byte manipulation
• v1 (Time-based): Calculates Unix timestamp with UUID epoch offset (0x01b21dd213814000), uses random node ID
• v7 (Time-ordered): Uses 48-bit millisecond timestamp followed by random bits

All versions set correct version (4 bits at byte[6]) and variant (2 bits at byte[8]) fields per RFC 4122.

State Management Pattern

The app uses standard React hooks without external state management:

• useState for all application state
• useEffect for side effects (auto-generate timer, initial UUID generation)
• Lock state prevents both manual and auto-generation
• Version selection persists only for current session (not localStorage)

BigInt Usage

UUID decimal representation requires 128-bit integers. The code uses BigInt for arithmetic:

const decimal = bytes.reduce((acc, byte, i) => {
  const shift = BigInt(15 - i) * 8n
  return acc + (BigInt(byte) << shift)
}, 0n).toString()

Always use BigInt literals (0n) and constructors when working with large numbers.