Skip to main content

​
Quickstart Guide

Get SkyCast IA displaying weather data in under 5 minutes. This guide will take you from zero to a working weather application with minimal setup.
This quickstart assumes you have Node.js (v20+) and npm installed. For detailed installation instructions, see the Installation page.

​
Prerequisites

Before starting, obtain these free API keys:
  1. OpenWeatherMap API Key - Sign up here
  2. Groq API Key - Get one here
1
Clone and Install
2
Clone the repository and install dependencies:
3
git clone <repository-url> skycast-ia
cd skycast-ia
npm install
4
Configure Environment Variables
5
Create a .env.local file in the root directory:
6
NEXT_PUBLIC_OPENWEATHER_API_KEY=your_openweather_api_key_here
GROQ_API_KEY=your_groq_api_key_here
RECAPTCHA_SECRET_KEY=your_recaptcha_secret_here
NEXT_PUBLIC_RECAPTCHA_SITE_KEY=your_recaptcha_site_key_here
7
NEXT_PUBLIC_ prefix is required for client-side environment variables. Keys without this prefix are only available on the server.
8
Start Development Server
9
npm run dev
10
Open http://localhost:3000 in your browser. The app will automatically request your location and display weather data.

​
Your First Weather Display

Once the dev server is running, SkyCast IA will:
  1. Request browser geolocation permission
  2. Fetch current weather for your location
  3. Display AI-generated weather analysis
  4. Show hourly forecast and interactive map

​
Understanding the Main Dashboard

The main page (src/app/page.tsx) orchestrates all weather features:
src/app/page.tsx
import { getCurrentWeather, getWeatherForecast } from "@/lib/api/weather";
import { getAiWeatherAnalysis } from "@/lib/api/mistral";
import { useLocation } from "@/hooks/useLocation";

// Automatic location detection
const { coords, loading, error, refresh } = useLocation();

// Fetch weather data
const fetchData = async (lat: number, lon: number) => {
  const [current, hourly] = await Promise.all([
    getCurrentWeather(lat, lon),
    getWeatherForecast(lat, lon),
  ]);
  
  if (current) {
    setWeather(current);
    const analysis = await getAiWeatherAnalysis(current);
    setAiAnalysis(analysis);
  }
};

​
Fetching Weather Data

The weather API client (src/lib/api/weather.ts) provides three core functions:

​
Get Current Weather by Coordinates

import { getCurrentWeather } from "@/lib/api/weather";

const weather = await getCurrentWeather(40.7128, -74.0060); // NYC coordinates

console.log(weather);
// {
//   name: "New York",
//   main: { temp: 22, humidity: 65, pressure: 1013 },
//   weather: [{ main: "Clear", description: "cielo claro" }],
//   wind: { speed: 3.5 },
//   coord: { lat: 40.7128, lon: -74.0060 }
// }

​
Get Weather by City Name

import { getWeatherByCity } from "@/lib/api/weather";

const weather = await getWeatherByCity("London");
// Returns same structure as getCurrentWeather

​
Get Hourly Forecast

import { getWeatherForecast } from "@/lib/api/weather";

const forecast = await getWeatherForecast(40.7128, -74.0060);

// Returns array of forecast objects (every 3 hours for 5 days)
forecast.slice(0, 8).forEach(item => {
  console.log(`${item.dt_txt}: ${item.main.temp}°C`);
});
All temperature values are in Celsius by default. The API calls include units=metric and lang=es parameters.

​
Displaying Weather with Components

Use pre-built components to display weather data:

​
Main Weather Card

import MainWeatherCard from "@/components/ui/MainWeatherCard";

<MainWeatherCard
  weather={weatherData}
  localTime={localTime}
  loadingAi={false}
  aiAnalysis="Día perfecto para salir. Lleva gafas de sol ☀️"
  getTempColor={(temp) => temp > 28 ? "text-orange-500" : "text-white"}
/>
This displays:
  • City name and country
  • Local time
  • Large temperature display with weather icon
  • AI-generated analysis box
  • Dynamic styling based on weather conditions

​
Forecast Card

import ForecastCard from "@/components/ui/ForecastCard";

<ForecastCard forecast={forecastArray.slice(0, 8)} />
Shows hourly forecast with temperature trends and weather icons.

​
Weather Stats

import WeatherStats from "@/components/ui/WeatherStats";

<WeatherStats weather={weatherData} variant="horizontal" />
Displays detailed metrics:
  • Humidity percentage
  • Wind speed
  • Atmospheric pressure
  • Feels-like temperature

​
Adding AI Analysis

The AI analysis feature uses Groq’s Llama 3.1 model to generate weather insights:
src/lib/api/mistral.ts
import { getAiWeatherAnalysis } from "@/lib/api/mistral";

const analysis = await getAiWeatherAnalysis(weatherData);
// Returns: "Día fresco y ventoso. Lleva una chaqueta ligera 🧥"
The AI receives:
  • City name
  • Temperature and humidity
  • Wind speed
  • Weather description
And returns a concise recommendation (max 20 words) with an emoji. 
{
  role: "system",
  content: "Eres una API de clima práctica. Tu objetivo es dar un consejo de vestimenta o actividad basado en los datos. Máximo 20 palabras y un emoji. Sé directo, breve y no uses comillas ni introducciones."
},
{
  role: "user",
  content: `Ciudad: ${weatherData.name}, Temp: ${Math.round(weatherData.main.temp)}°C, Humedad: ${weatherData.main.humidity}%, Viento: ${weatherData.wind.speed}km/h, Estado: ${weatherData.weather[0].description}.`
}

​
Testing Location Detection

The useLocation hook handles geolocation:
src/hooks/useLocation.ts
import { useLocation } from "@/hooks/useLocation";

function WeatherApp() {
  const { coords, loading, error, refresh } = useLocation();
  
  if (loading) return <div>Detecting location...</div>;
  if (error) return <div>Error: {error}</div>;
  
  return <div>Lat: {coords.lat}, Lon: {coords.lon}</div>;
}
Key features:
  • Automatic location request on mount
  • 15-second timeout for GPS acquisition
  • Manual refresh function for retry
  • Detailed error messages for permission issues

​
Common Quickstart Issues

If the browser denies location access:
  1. Click the lock icon in the browser address bar
  2. Set location permission to “Allow”
  3. Refresh the page or click “Mi Ubicación” button
  4. Alternatively, use the search bar to manually enter a city
If you see “Falta la API Key” or fetch errors:
  1. Verify .env.local file exists in root directory
  2. Check variable names match exactly (case-sensitive)
  3. Restart the dev server after adding environment variables
  4. Ensure OpenWeatherMap key is activated (can take 10 minutes)
The WeatherMap component uses dynamic import to prevent SSR issues:
const WeatherMap = dynamic(() => import("@/components/ui/WeatherMap"), {
  ssr: false,
  loading: () => <div className="animate-pulse" />
});
If the map doesn’t load, check browser console for Leaflet errors.

​
Next Steps

Now that you have SkyCast IA running:
  1. Explore Components: Check src/components/ui/ for all available components
  2. Customize Themes: Modify weather-based color schemes in src/app/page.tsx
  3. Add Features: Integrate the AI chat component for conversational weather queries
  4. Deploy: See the Installation guide for production deployment
The app includes a beautiful animated footer with mountains, trees, and flying birds. Explore page.tsx to see the SVG implementation.

Build docs developers (and LLMs) love

Get started for freeTalk to us