- About
- Key Features
- Tech Stack
- Project Structure
- Getting Started
- Configuration
- Usage
- API Integration
- Contributing
- License
- Contact
WeatherSphere is a cutting-edge weather intelligence platform that delivers hyperlocal, real-time meteorological data with advanced visualization capabilities. Built with modern web technologies, it provides comprehensive atmospheric insights through interactive maps, detailed forecasts, and air quality monitoring.
To democratize access to professional-grade weather intelligence through an intuitive, fast, and reliable web application.
- 🚀 Lightning Fast: Built with Vite for optimal performance
- 🗺️ Interactive Maps: Powered by Mapbox GL JS with multiple weather layers
- 📱 Responsive Design: Seamless experience across all devices
- 🌓 Theme Support: Dark and light modes for comfortable viewing
- 🔐 Type Safe: Structured with modern JavaScript patterns
- ♿ Accessible: WCAG 2.1 AA compliant
- ✅ Real-Time Weather Data - Current conditions updated every 15 minutes
- ✅ 24-Hour Forecast - Hourly temperature and precipitation predictions
- ✅ 7-Day Extended Forecast - Weekly weather planning at a glance
- ✅ Location Search - Search any city worldwide with autocomplete
- ✅ Geolocation Support - Automatic detection of user's location
- ✅ Temperature Maps - Global heat maps with gradient visualization
- ✅ Wind Patterns - Real-time wind speed and direction analysis
- ✅ Air Quality Index (AQI) - Pollution levels with health recommendations
- ✅ Cloud Coverage - Satellite-based cloud layer visualization
- ✅ Interactive Radar - Zoom and pan across detailed weather layers
- ✅ Historical Trends - Average temperature analysis over time
- ✅ Weather Alerts - Severe weather notifications
- ✅ UV Index - Sun exposure safety guidelines
- ✅ Humidity & Pressure - Detailed atmospheric metrics
| Technology | Purpose | Version |
|---|---|---|
 |
UI Framework | 18.3.1 |
 |
Build Tool | 6.3.5 |
 |
Routing | 7.1.3 |
 |
Animations | 11.20.0 |
 |
Styling | 3.4.17 |
| Technology | Purpose |
|---|---|
| Mapbox GL JS | Interactive mapping engine |
| D3.js | Data visualization library |
| Chart.js | Chart rendering |
| Leaflet | Alternative mapping solution |
- WeatherAPI.com - Primary weather data provider
- OpenWeatherMap - Air quality and supplementary data
- Mapbox - Geocoding and map tiles
- ESLint - Code linting
- Prettier - Code formatting
- Git - Version control
WeatherSphere/
├── 📂 public/ # Static assets
│ ├── logo.png
│ └── favicon.ico
│
├── 📂 src/ # Source code
│ ├── 📂 assets/ # Images, fonts, icons
│ │ └── react.svg
│ │
│ ├── 📂 components/ # Reusable UI components
│ │ ├── 📂 Footer/
│ │ │ └── Footer.jsx
│ │ └── 📂 Navbar/
│ │ └── Navbar.jsx
│ │
│ ├── 📂 contexts/ # React Context providers
│ │ └── ThemeContext.jsx # Dark/Light theme management
│ │
│ ├── 📂 pages/ # Route-based page components
│ │ ├── AqiMap.jsx # Air Quality Index visualization
│ │ ├── AverageTemperature.jsx # Historical temp analysis
│ │ ├── CloudMap.jsx # Cloud coverage maps
│ │ ├── ErrorPage.jsx # 404 error handling
│ │ ├── HomePage.jsx # Landing page
│ │ ├── Root.jsx # Main layout wrapper
│ │ ├── TemperatureMap.jsx # Temperature heatmaps
│ │ └── WindyMap.jsx # Wind pattern visualization
│ │
│ ├── 📂 routes/ # Routing configuration
│ │ ├── PrivateRoute.jsx # Protected route wrapper
│ │ └── router.jsx # Main router setup
│ │
│ ├── App.css # Global styles
│ ├── App.jsx # Root application component
│ ├── index.css # Base CSS & Tailwind imports
│ └── main.jsx # Application entry point
│
├── 📄 .env.example # Environment variables template
├── 📄 .gitignore # Git ignore rules
├── 📄 eslint.config.js # ESLint configuration
├── 📄 index.html # HTML template
├── 📄 package.json # Dependencies & scripts
├── 📄 README.md # Project documentation
├── 📄 tailwind.config.js # Tailwind configuration
└── 📄 vite.config.js # Vite build configuration
Reusable UI components that can be used across multiple pages.
- Footer - Application footer with links and branding
- Navbar - Navigation bar with theme toggle
React Context API providers for global state management.
- ThemeContext - Manages dark/light theme preferences
Page-level components mapped to specific routes.
- HomePage - Main landing page with weather overview
- TemperatureMap - Interactive temperature visualization
- WindyMap - Wind speed and direction maps
- AqiMap - Air quality index display
- CloudMap - Cloud coverage visualization
- AverageTemperature - Historical temperature trends
Application routing configuration.
- router.jsx - Defines all application routes
- PrivateRoute.jsx - Authentication wrapper for protected routes
Before you begin, ensure you have the following installed:
- Node.js (v18.0.0 or higher) - Download
- npm (v9.0.0 or higher) or yarn (v1.22.0 or higher)
- Git - Download
- WeatherAPI - Get Free API Key
- Mapbox - Get Free API Key
- OpenWeatherMap (Optional) - Get Free API Key
-
Clone the repository
git clone https://github.com/MRaysa/WeatherSphere.git cd WeatherSphere -
Install dependencies
npm install # or yarn install -
Set up environment variables
Create a
.envfile in the root directory:cp .env.example .env
Add your API keys:
VITE_WEATHER_API_KEY=your_weatherapi_key_here VITE_MAPBOX_TOKEN=your_mapbox_token_here VITE_OPENWEATHER_API_KEY=your_openweather_key_here
-
Start the development server
npm run dev # or yarn dev -
Open your browser
Navigate to
http://localhost:5173
| Variable | Description | Required | Default |
|---|---|---|---|
VITE_WEATHER_API_KEY |
WeatherAPI.com API key | Yes | - |
VITE_MAPBOX_TOKEN |
Mapbox GL JS access token | Yes | - |
VITE_OPENWEATHER_API_KEY |
OpenWeatherMap API key | No | - |
The project uses Vite for building. Configuration can be modified in vite.config.js:
export default defineConfig({
plugins: [react()],
server: {
port: 5173,
host: true
},
build: {
outDir: 'dist',
sourcemap: true
}
})# Start development server
npm run dev
# Run with specific port
npm run dev -- --port 3000
# Open in browser automatically
npm run dev -- --open# Create production build
npm run build
# Preview production build locally
npm run preview
# Analyze bundle size
npm run build -- --mode analyze# Run ESLint
npm run lint
# Fix ESLint issues automatically
npm run lint:fix
# Format code with Prettier
npm run formatconst fetchWeather = async (location) => {
const response = await fetch(
`https://api.weatherapi.com/v1/forecast.json?key=${API_KEY}&q=${location}&days=7`
);
return response.json();
};mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN';
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/streets-v11',
center: [lng, lat],
zoom: 9
});We welcome contributions from the community! Here's how you can help:
- Fork the repository
- Create a feature branch
git checkout -b feature/AmazingFeature
- Commit your changes
git commit -m 'Add some AmazingFeature' - Push to the branch
git push origin feature/AmazingFeature
- Open a Pull Request
- Follow the existing code style
- Write meaningful commit messages
- Add comments for complex logic
- Update documentation as needed
- Test your changes thoroughly
Found a bug? Open an issue with:
- Clear description
- Steps to reproduce
- Expected vs actual behavior
- Screenshots (if applicable)
- Environment details
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 WeatherSphere
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
Project Maintainer - MRaysa
- GitHub: @MRaysa
- Project Link: https://github.com/MRaysa/WeatherSphere
- Live Demo: https://weather-sphere-seven.vercel.app/
- WeatherAPI.com - Weather data provider
- Mapbox - Mapping platform
- React - UI framework
- Vite - Build tool
- Vercel - Hosting platform
- Icons by Heroicons