Worldtimez 🌍

Worldtimez is a modern, user-friendly timezone comparison application built with React and Material-UI. It allows users to easily compare times across different timezones with an intuitive drag-and-drop interface.

✨ Features

• 🕒 Compare multiple timezones simultaneously
• 📅 Set specific date & time to compare
• 🔄 Drag-and-drop interface for reordering timezones
• 🌓 Dark/Light mode support
• 📱 Responsive design for all devices
• 🔍 Smart timezone search with city suggestions
• 💾 Persistent storage of user preferences
• ⚡ Fast and efficient time conversions

🚀 Setup

1. Clone the repository:

git clone https://github.com/ziarahman/worldtimez.git
cd worldtimez

2. Install dependencies:

npm install

3. Copy .env.example to .env.local and fill in your API keys:

cp .env.example .env.local

4. Start the development server:

npm run dev

🚀 Deployment

1. Local Development

   • Copy .env.example to .env.local
   • Fill in your API keys in .env.local
   • Run npm run dev

2. Production Deployment (Vercel)

   • Go to your Vercel project settings
   • Navigate to "Environment Variables"
   • Add the following variables:
     • VITE_GEODB_API_KEY
     • VITE_OPENCAGE_API_KEY
     • VITE_OPENWEATHER_API_KEY
     • VITE_TIMEZONEDB_API_KEY
   • Click "Deploy" to rebuild with new environment variables

3. Managing Environment Variables and API Keys

   • Create a new file named .env in the root of your project
   • Add your API keys to the .env file, for example:
     • VITE_GEODB_API_KEY=YOUR_GEODB_API_KEY
     • VITE_OPENCAGE_API_KEY=YOUR_OPENCAGE_API_KEY
     • VITE_OPENWEATHER_API_KEY=YOUR_OPENWEATHER_API_KEY
     • VITE_TIMEZONEDB_API_KEY=YOUR_TIMEZONEDB_API_KEY
   • Make sure to add the .env file to your .gitignore file to avoid committing sensitive information

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm (v9 or higher)

Installation

1. Clone the repository:

git clone https://github.com/ziarahman/worldtimez.git
cd worldtimez

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

4. Open http://localhost:4242 in your browser

🏗️ Production Deployment

Building for Production

1. Create a production build:

npm run build

2. Start the production server:

npm start

Docker Deployment

1. Build the Docker image:

docker build -t worldtimez .

2. Run the container:

docker run -p 4242:4242 worldtimez

🚀 Technologies

• Frontend: React 18, TypeScript, Vite
• UI Components: Material-UI (MUI)
• State Management: Zustand
• Date/Time Handling: Luxon
• API Services:
  • GeoDB Cities API: For city data and geolocation
  • OpenCage Geocoding API: For geocoding and reverse geocoding
  • OpenWeatherMap API: For weather data and geolocation
  • TimezoneDB API: For timezone information
  • Nominatim API: For additional geocoding capabilities

🛠️ Tech Stack

• React - UI Framework
• TypeScript - Language
• Material-UI - Component Library
• Luxon - DateTime Handling
• @dnd-kit - Drag and Drop
• Vite - Build Tool

📦 Project Structure

worldtimez/
├── src/
│   ├── components/        # React components
│   ├── data/             # Timezone data and utilities
│   ├── lib/              # Helper functions
│   ├── types/            # TypeScript type definitions
│   ├── App.tsx           # Main application component
│   └── main.tsx          # Application entry point
├── public/               # Static assets
├── server.js            # Production server
└── package.json         # Project dependencies

🤝 Contributing

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

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👏 Acknowledgments

• Timezone Database for timezone data
• Material-UI for the beautiful components
• @dnd-kit for the drag and drop functionality

🔗 Links

• Live Demo
• Documentation
• Issue Tracker

---

Made with ❤️ by Zia Rahman + Vibe Coding with AI 🤖 using Windsurf.