A modern weather application built with Next.js and React, providing accurate weather forecasts using Apple's WeatherKit API. Free Sky serves as a replacement for the discontinued Dark Sky weather service.
- Real-time Weather Data: Current conditions, hourly forecasts, and 7-day outlook
- Location-based Forecasts: Automatic location detection or manual location search
- Interactive Weather Icons: Animated weather condition icons
- Mobile-First Design: Responsive interface optimized for all devices
- Weather Alerts: Display of active weather warnings and alerts
- Offline Storage: Saves recently viewed locations for quick access
- Node.js 18+ and Yarn
- Apple Developer Account (for WeatherKit API access)
- MapBox API key (for location services)
- Redis instance (optional - for caching, see development options below)
Create a .env.local file in the root directory:
# Apple WeatherKit Configuration
APPLETEAMID=your_apple_team_id
APPLEKEYID=your_apple_key_id
# Option 1: Provide key content directly (recommended for production)
APPLE_WEATHERKIT_KEY="-----BEGIN PRIVATE KEY-----\nYourKeyContentHere\n-----END PRIVATE KEY-----"
# Option 2: Provide path to .p8 key file (for development)
APPLE_WEATHERKIT_KEY_PATH=path_to_your_p8_key_file
# MapBox Configuration
MAPBOX_ACCESS_TOKEN=your_mapbox_access_token
# Redis Configuration (optional - for caching)
REDIS_URL=redis://localhost:6379
# Sentry Configuration (optional - for error tracking)
SENTRY_DSN=your_sentry_dsn- Clone the repository:
git clone https://github.com/jimmcq/free-sky.git
cd free-sky- Install dependencies:
yarn install-
Configure environment variables (see above)
-
Start the development server:
Option A: Basic development (no caching)
yarn devOption B: With Redis for caching
# Requires Redis installed locally
yarn dev:with-redis
# Or use the smart script that auto-detects Redis
yarn dev:smart
# Or use Docker Compose (recommended)
yarn dev:dockerThe application works without Redis but benefits from caching for better performance:
Simply run yarn dev - the app will work without caching.
# macOS with Homebrew
brew install redis
brew services start redis
# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis-server
# Then use: yarn dev:with-redis or yarn dev:smart# Just run this - Redis will be automatically started
yarn dev:dockeryarn dev- Start development server (no caching)yarn dev:with-redis- Start with Redis caching (concurrent)yarn dev:smart- Intelligent start with Redis auto-detectionyarn dev:docker- Start with Docker Compose (Redis included)yarn dev:docker:down- Stop Docker Compose services
yarn build- Build production applicationyarn start- Start production server
yarn test- Run test suiteyarn eslint- Run ESLint code analysisyarn prettier- Check code formattingyarn prettier:fix- Fix code formatting
Endpoint: GET /api/forecast?latitude={lat}&longitude={lon}
Parameters:
latitude(required): Latitude coordinate (-90 to 90)longitude(required): Longitude coordinate (-180 to 180)
Response: Comprehensive weather data including current conditions, hourly forecasts, daily forecasts, and alerts.
Example:
curl "https://free-sky.net/api/forecast?latitude=37.7749&longitude=-122.4194"Endpoint: GET /api/searchplace?place={query}
Parameters:
place(required): Location search query (city name, address, etc.)
Response: Array of matching locations with coordinates and place names.
Example:
curl "https://free-sky.net/api/searchplace?place=San%20Francisco"Endpoint: GET /api/getplacename?latitude={lat}&longitude={lon}
Parameters:
latitude(required): Latitude coordinatelongitude(required): Longitude coordinate
Response: Human-readable place name for the given coordinates.
Example:
curl "https://free-sky.net/api/getplacename?latitude=37.7749&longitude=-122.4194"The application uses:
- Next.js 15 for the React framework
- React for the user interface
- TypeScript for type safety
- Apple WeatherKit for weather data
- MapBox for location services
- Redis for caching
- Sentry for error tracking
"Weather data not loading"
- Verify your Apple WeatherKit API credentials are correct
- Check that your Apple Developer account has WeatherKit enabled
- Ensure the
.p8key file path is correct in your environment variables
"Location search not working"
- Verify your MapBox access token is valid
- Check that MapBox Geocoding API is enabled for your account
"Redis connection errors"
- For development: Use
yarn devinstead ofyarn dev:with-redis - For Docker: Try
yarn dev:docker:downfollowed byyarn dev:docker - For local Redis: Ensure Redis server is running (
redis-server)
"Build errors"
- Clear Next.js cache:
rm -rf .next - Clear node_modules:
rm -rf node_modules && yarn install - Check that all environment variables are properly set
"TypeScript errors"
- Run
yarn buildto see detailed TypeScript errors - Check that all dependencies are properly installed
- Ensure your Node.js version is 18+ (
node --version)
To enable debug logging, add to your .env.local:
DEBUG=true
NODE_ENV=development- Enable Redis caching for better performance
- Check network requests in browser dev tools
- Monitor bundle size with
yarn build
The application can be deployed to any platform supporting Next.js:
vercel --prodMake sure to set all environment variables in your Vercel dashboard.
docker build -t free-sky .
docker run -p 3000:3000 free-sky- Netlify: Configure build command as
yarn buildand publish directory as.next - Railway: Connect your GitHub repository and set environment variables
- Heroku: Add Node.js buildpack and configure environment variables
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and linting
- Submit a pull request
Jim McQuillan
- GitHub: https://github.com/jimmcq
- LinkedIn: https://www.linkedin.com/in/jimmcquillan/
This project is licensed under the terms specified in the package.json file.
- Apple WeatherKit for weather data
- MapBox for location services
- The Dark Sky API (discontinued) for inspiration