CloudyCool

CloudyCool is a premium weather app built with React + Vite + TypeScript.

It includes:

• Current weather by city search
• GPS and IP-based location detection
• Hourly forecast for today
• 5-day forecast
• AQI (air quality index) summary
• Light/dark theme toggle
• Dynamic weather-based atmospheric backgrounds
• Mobile-first glassmorphism UI
• Installable PWA support (Android prompt + iOS Add to Home Screen guidance)

Tech Stack

• React 18
• Vite 5
• TypeScript
• Tailwind CSS
• shadcn/ui (Radix UI primitives)
• TanStack Query
• Vitest
• vite-plugin-pwa + Workbox

Prerequisites

• Node.js 18+ (or newer LTS)
• npm (or Bun, since lockfiles for both are present)

Run Locally

npm install
npm run dev

Default local URL:

• http://localhost:8080/cloudycool/

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run build:dev - Build using development mode
• npm run preview - Preview the production build locally
• npm run lint - Run ESLint
• npm run test - Run tests once (Vitest)
• npm run test:watch - Run tests in watch mode

Deployment

• Source branch: main
• Hosting: GitHub Pages
• Live URL: https://shoyshai.github.io/cloudycool/
• Base path: /cloudycool/
• Deployment runs automatically via GitHub Actions (.github/workflows/deploy.yml)

PWA Support

CloudyCool is configured as an installable PWA.

• Manifest generated at /cloudycool/manifest.webmanifest
• Service worker generated by vite-plugin-pwa
• Icons:
  • public/pwa-192x192.png
  • public/pwa-512x512.png
  • public/pwa-maskable-512x512.png
  • public/apple-touch-icon.png
• Install behavior:
  • Android/Chrome: shows install prompt when eligible
  • iOS/Safari: uses Share > Add to Home Screen guidance

Caching strategy:

• Static app shell/assets are precached
• OpenWeather API requests use NetworkOnly to keep weather data fresh

Project Structure

src/
  components/       Reusable UI and feature components
  hooks/            App hooks (weather, theme, etc.)
  lib/              Utilities and weather background helpers
  pages/            Route pages
  test/             Test setup and examples

Weather Data Sources

The app currently integrates:

• OpenWeatherMap APIs (weather, forecast, AQI)
• OpenStreetMap Nominatim reverse geocoding
• ipapi.co for IP-based fallback location

API Key Note

src/hooks/useWeather.ts currently contains a hardcoded OpenWeatherMap API key.

For production, move this to an environment variable (for example VITE_OPENWEATHER_API_KEY) and read it via import.meta.env.

Routing

Routes are defined in src/App.tsx:

• / -> main weather page
• * -> not found page

BrowserRouter uses basename={import.meta.env.BASE_URL} for GitHub Pages compatibility.