Semantic Version Visualizer

An interactive tool to learn and understand Semantic Versioning through visual demonstrations.

🚀 Live Demo: semver.agenticinsights.com
✅ Status: Cloudflare deployment working (duplicate Worker issue resolved)

Why Interactive Learning?

Instead of traditional presentations or static documentation, this project demonstrates the power of interactive learning experiences. By leveraging modern web technologies and AI assistance, complex concepts like semantic versioning can be transformed into engaging, hands-on tools that make learning intuitive and memorable.

This project was rapidly prototyped using:

• AI-powered development for quick iteration and component selection
• Modern React libraries (shadcn/ui, Magic UI) for polished UI
• TypeScript for type-safe development
• Cloudflare Pages for instant global deployment

The result? A fully functional learning tool deployed in hours, not weeks.

Features

🎯 Interactive Learning

• Visual Commit Stream: Watch commits flow and affect version numbers in real-time
• Commit Type Buttons: Add different types of commits to see their impact:
  • 🔴 Breaking Changes → Major version bump (X.0.0)
  • 🟢 Features → Minor version bump (x.X.0)
  • 🔵 Fixes → Patch version bump (x.x.X)
  • Plus docs, style, refactor, test, and chore commits

✨ Modern UI/UX

• Built with shadcn/ui and Magic UI components
• Smooth animations with Framer Motion
• Dark/Light theme support
• Sound effects for interactions
• Particle effects and confetti celebrations

💾 Data Persistence

• Local Storage: Automatically saves your work
• Import/Export: Backup and share your version history
• Release History: Track all your releases over time

📚 Educational Resources

• Tooltips explaining each commit type's impact
• Links to semver.org and other learning resources
• Visual feedback showing version progression

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

# Clone the repository
git clone https://github.com/killerapp/learn-semver.git
cd learn-semver

# Install dependencies
npm install

# Run development server
npm run dev

Open http://localhost:3000 to see the app.

Docker

Build and run the app in a container:

docker compose up --build

Visit http://localhost:3000 once the server starts.

Deployment

✅ Currently deployed on Cloudflare Pages at semver.agenticinsights.com

See DEPLOYMENT.md for detailed instructions on deploying your own instance.

Quick Deploy to Cloudflare Pages

# Build for production
npm run build

# Deploy to Cloudflare Pages
npm run deploy

The project is configured for static export with:

• Next.js static export (output: 'export')
• Cloudflare Pages project name: learn-semver
• Custom domain: Configured via Cloudflare DNS

How It Works

Semantic Versioning Rules

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backwards compatible manner
3. PATCH version when you make backwards compatible bug fixes

Commit Types

Type	Description	Version Impact
🔴 breaking	Breaking changes	Major (X.0.0)
🟢 feat	New features	Minor (x.X.0)
🔵 fix	Bug fixes	Patch (x.x.X)
📝 docs	Documentation	No change
🎨 style	Code style	No change
🔧 refactor	Code refactoring	No change
🧪 test	Tests	No change
📦 chore	Maintenance	No change

Tech Stack

• Framework: Next.js 15 with Turbopack
• UI Components: shadcn/ui + Magic UI
• Styling: Tailwind CSS
• Animations: Framer Motion
• Language: TypeScript
• Deployment: Cloudflare Pages

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Roadmap

• Core visualization functionality
• Sound effects and animations
• Data persistence
• Import/Export functionality
• Git integration for real commits
• Customizable commit types
• Pre-release version support
• Team collaboration features

License

MIT License - see LICENSE file for details

Credits

Built with ❤️ by Agentic Insights

Special thanks to:

• Semantic Versioning Specification
• Conventional Commits
• shadcn/ui for the component library
• Magic UI for additional components

Support

For questions or support, please:

• Open an issue
• Visit Agentic Insights

---

Learn semantic versioning the visual way! 🚀