What you’ll learn:
Before you begin, make sure you have:
npm installedIf you haven’t already, follow the Quick Start guide to set up your app and environment.
Before you can use a Key Value Store in your Webflow Cloud app, you need to declare a binding in your app’s configuration. This binding tells your app how to connect to the storage resource.
Once the binding is declared, your app can use simple methods like .get(), .put(), and .delete() to read from and write to the Key Value Store directly in your code.
If you created a Webflow Cloud prior to 7/16/2025, you’ll need to update your app in the Webflow Cloud dashboard to use Webflow Cloud’s new storage system.
Go to your app in the Webflow Cloud dashboard.
Select the ”…” icon in the “Actions” section of the menu.
Select “Edit” (you don’t actually need to edit anything).
Press “Save Changes” to update your app.

In your app’s wrangler.json file, add a kv_namespaces array to define your Key Value Store binding:
binding: The variable name you’ll use to access the database in your code. This must be a valid JavaScript variable name.id: A unique identifier for your database (Webflow Cloud will generate this for you once you deploy your app).Now that your Key Value Store binding is set up, you can use it to cache data in your app. In this section, you’ll build an API route that fetches weather information based on the user’s location. Each response will be stored in your Key Value Store for 10 minutes, so repeated requests are fast and reduce calls to the external weather API.
Set up an API endpoint that will fetch weather data for your users.
In your Astro app, go to the src/pages/api directory. If this directory doesn’t exist, create it.
Inside this directory, create a new file called weather.ts.
Add the following code into your new file:
Access your Key Value Store binding in your API route so you can read from and write to the store.
In your weather.ts file, access the binding from the runtime environment:
env.WEATHER_CACHE gives you access to the Key Value Store you declared in wrangler.json.Extract the user’s location from the request headers. This information will be used to fetch location-specific weather data.
In your weather.ts file, add the following code to get the user’s latitude and longitude from the Cloudflare request headers:
request.cf contains the user’s location information.Before making an external API call, check if the weather data for the user’s location is already stored in your Key Value Store. If cached data exists, return it immediately to improve performance and reduce external requests.
Use the .get() method on the binding to check for cached data.
In your weather.ts file, add the following logic after retrieving the user’s location:
X-Cache-Status: HIT header.If no cached weather data is found, fetch fresh data from the Open-Meteo API, store it in your Key Value Store, and return it to the user.
Store the fresh data in your Key Value Store using the .put() method.
In your weather.ts file, add the following logic after checking for cached data:
X-Cache-Status: MISS header.Make sure your API route works as expected by sending a request from your terminal.
In your terminal, start your dev server using Cloudflare’s context.
In a new terminal, run:
<YOUR_PORT_NUMBER> is the port number of your dev server.<YOUR_BASE_PATH> is the base path of your app.Check the response headers:
X-Cache-Status: MISS (data fetched from the API and cached).X-Cache-Status: HIT (data returned from the cache).If you see the expected headers and weather data in the response, your endpoint and caching are working!
Now that your API is returning weather data, let’s display it directly on your home page. In this section, you’ll add a weather widget that shows the current temperature and a matching weather icon for your user’s location. This gives users instant, dynamic feedback and demonstrates how to connect your frontend to your new API.
Add weather icons to your app so you can visually represent the current weather.
weather-icons package provides a set of CSS classes for common weather conditionsCreate a utility to translate weather codes from your API into icon classes for display.
src directory, create a utils folder if it doesn’t already exist.utils, create a file named iconMap.ts.iconMap.ts:Fetch the latest weather data from your API and display it on your home page, along with the appropriate weather icon.
Open your home page file. (for example, src/pages/index.astro)
Import the weather icons CSS and your icon map utility at the top of the file.
Fetch the weather data from your API and extract the temperature and weather code. Then, use the weather code to get the appropriate icon class from your icon map utility.
Display the weather data and icon in your page’s markup, below the welcome message:
See the full code example below:
Make sure your app is working as expected by running it locally and verifying the weather widget displays correctly.
Visit your app in a web browser.
Go to http://<YOUR_PORT_NUMBER>/<YOUR_BASE_PATH> to see your app running locally.
<YOUR_PORT_NUMBER> is the port number of your dev server.<YOUR_BASE_PATH> is the base path of your app.You should see your app running locally with the weather widget displaying the current temperature and weather icon.

Deploy your app to Webflow Cloud. You can deploy your app in two ways:
Use the Webflow CLI
Commit and push your changes to your GitHub repository.
Go to your environment in Webflow Cloud to see your app deployed. Once deployed, you can access your app at https://<YOUR_DOMAIN>/<YOUR_BASE_PATH>.
Congratulations! You’ve successfully added a Key Value Store to your Webflow Cloud app, built a weather API with caching, and displayed live weather data on your home page.