249 lines
6.1 KiB
Markdown
249 lines
6.1 KiB
Markdown
# 🔑 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.
|
|
|
|
[](https://github.com/xixu-me/UUID-Playground/actions/workflows/deploy.yml)
|
|
|
|
## ✨ 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](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**
|
|
|
|
```bash
|
|
git clone https://github.com/xixu-me/UUID-Playground.git
|
|
cd UUID-Playground
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Start development server**
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
The app will be available at `http://localhost:5173`
|
|
|
|
4. **Run tests**
|
|
|
|
```bash
|
|
# Run tests once
|
|
npm test
|
|
# Run tests in watch mode
|
|
npm run test:watch
|
|
```
|
|
|
|
5. **Lint code**
|
|
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
6. **Build for production**
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
Built files will be in the `dist/` directory
|
|
|
|
7. **Preview production build**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```typescript
|
|
export default defineConfig({
|
|
base: '/your-new-repo-name/',
|
|
// ... other config
|
|
})
|
|
```
|
|
|
|
## 🎨 Customization
|
|
|
|
### Changing Colors
|
|
|
|
Edit CSS variables in `src/styles/App.css`:
|
|
|
|
```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`:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
<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:
|
|
|
|
```bash
|
|
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) license.
|
|
|
|
## 📚 Resources
|
|
|
|
- [UUID Specification (RFC 4122)](https://datatracker.ietf.org/doc/html/rfc4122)
|
|
- [UUID Version 7 Draft](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format)
|
|
- [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)
|
|
- [Vite Documentation](https://vitejs.dev/)
|
|
- [React Documentation](https://react.dev/)
|
|
|
|
## 🙏 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
|