DEV Community: Mathias Ahlgren

I Built a Local Directory Site with Astro, Airtable, and Cloudflare - Here is the Architecture

Mathias Ahlgren — Thu, 18 Jun 2026 23:51:26 +0000

I've built a few local directory sites lately - the "best X in town" kind of thing - and I kept reaching for the same stack: Astro for the frontend, Airtable as the CMS, Cloudflare to host it. After the third one I realised the architecture was the interesting part, not any individual site. So this is a writeup of how the pieces fit together, the decisions that actually mattered, and the two or three gotchas that cost me an afternoon each.

If you're building anything that's mostly structured, read-heavy content - a directory, a catalogue, a "links" site, a small marketplace - this pattern is worth stealing.

Why this stack for a directory

A directory is a particular shape of website. It's a pile of structured records (each listing has a name, a category, some photos, hours, a location) that changes a few times a week, not a few times a second. Visitors read far more than they write.

That shape matters, because it tells you what you don't need. You don't need a PHP runtime and a database doing a query on every single page view to show a list of restaurants that barely changes. That's the WordPress model, and for this job it's mostly overhead - plus a plugin ecosystem you have to keep patched.

What you actually need is three things:

A friendly way to manage the data (ideally one a non-technical client can use).
A build step that turns that data into fast, static HTML.
Somewhere cheap and fast to serve it from.

Airtable, Astro, and Cloudflare map onto those three jobs almost one-to-one. Let's go through each.

The data layer: Airtable as a build-time CMS

The instinct when you hear "CMS" is to reach for something with an admin panel - WordPress, Strapi, a headless SaaS. But for a directory, Airtable is hard to beat, and the reason is purely about the editing experience.

Your content is a table. Listings are rows. Categories are linked records. "Feature this on the homepage" is a checkbox. "Hide this" is unchecking another. That's an interface a client or a virtual assistant can use on day one without you building anything. You get a real relational-ish data model (linked records between listings and categories) and a spreadsheet UI, for free.

The key architectural decision: read Airtable at build time, not at request time. A loader script runs during the build, pulls every table over the Airtable API, and hands the data to Astro to render into static pages. There's no live API call when a visitor hits the site - the content is already baked into HTML.

  Airtable base                 build step                 static output
┌───────────────┐        ┌────────────────────┐        ┌──────────────────┐
│ Items         │        │ loaders/airtable   │        │ HTML in dist/     │
│ Categories    │  ───►  │ • fetch all tables │  ───►  │ • /listings       │
│ Areas         │        │ • links → slugs    │        │ • /place/<slug>   │
│ + images      │        │ • download images  │        │ • /category/<slug>│
└───────────────┘        └────────────────────┘        └──────────────────┘

The consequence you have to design around: a content change only appears after a rebuild. In dev you restart the server; in production you trigger a deploy. That sounds like a limitation, and for some apps it would be - but for a directory that updates a few times a week, it's a perfectly fine trade for never running a database. (More on automating that rebuild later.)

The image gotcha that bites everyone

Here's the one that cost me time, and it's worth the price of the whole article: Airtable's attachment URLs expire. If you fetch a record and hot-link the image URL it gives you, your photos will silently 404 a while later.

So the loader can't reference Airtable's URLs directly. Instead, at build time it downloads every image and self-hosts the local copy. The build pulls the bytes down, drops them in a public folder, and the rendered HTML points at your own domain. Photos become stable and fast, with the side effect that adding a photo (like any content change) needs a rebuild to show up.

If you take one thing from this section: any "use Airtable as a CMS" tutorial that hot-links attachment URLs is quietly broken. Download them.

The frontend: Astro, and designing for reuse

Astro is the obvious fit here because directories are content-first and Astro ships zero JavaScript by default - you only opt into client-side JS where you actually need interactivity (a filter drawer, a map). For a page that's fundamentally "a styled list of records," that means very fast pages out of the box.

But the more interesting decision was structural. After the first build I didn't want to rewrite components every time I started a new directory in a different niche. So I wrote the whole thing in generic primitives and pushed every niche-specific word into one config file.

Nothing in the components or routes says "restaurant." The code talks about:

an Item (the thing you list)
Taxonomies (the ways you categorise it)
an optional Tier (a price level)

What those mean lives entirely in config:

item: {
  singular: 'Place to Eat',
  plural: 'Places to Eat',
  slugBase: 'place',          // detail pages live at /place/<slug>
},
taxonomies: [
  { key: 'cuisine', label: 'Cuisine', plural: 'Cuisines', slugBase: 'cuisine' },
  { key: 'area',    label: 'Area',    plural: 'Areas',     slugBase: 'area' },
  { key: 'tag',     label: 'Tag',     plural: 'Tags',      slugBase: 'tags' },
],

The trick that makes re-skinning safe: keys vs labels

This is the part I'm most pleased with, and it generalises to any config-driven system. Each taxonomy has both a key and a label:

The key (cuisine, area, tag) is a stable internal identifier. The loader and components are wired to it. You never change it once you have content and URLs depending on it.
The label, plural, and slugBase are human-facing. They're what shows in the UI and the URLs. You rename these freely.

So the taxonomy the code calls cuisine can display as "Specialty" and live at /specialty/..., while every component still references the stable cuisine key under the hood. To turn a restaurant directory into a hairdresser one, you change labels - Cuisine → Specialty, Tags → Services, Place → Salon - and rename the matching Airtable tables. No component touched, no route rewritten.

That's the difference between a codebase you reuse and one you fork-and-gut every time. The vertical becomes data, not code.

Dynamic routes from the data

Astro's file-based routing does the heavy lifting. Two dynamic route files cover most of the site:

src/pages/
  [itemBase]/[slug].astro   → a listing's detail page  (/place/the-old-spence)
  [taxonomy]/[slug].astro   → a category browse page    (/cuisine/italian)

Each uses getStaticPaths() to enumerate every listing and every category from the build-time data and emit a static page per record. Combined with the config above, the slugBase values decide the URL shapes - so when you relabel place to salon, the routes follow automatically.

The hosting: Cloudflare, and the "mostly static" hybrid

Here's a nuance people miss: a directory is almost fully static, but not quite. The listing pages, category pages, map, and blog are static HTML. But you usually want a few forms - "submit a business," contact, newsletter - and a form needs something server-side to receive the POST.

The clean answer on Cloudflare is a hybrid. The vast majority of the site is static assets served from the edge. The handful of form endpoints run as server functions (in Astro you mark just those routes with export const prerender = false). So you get static performance everywhere that matters, and a tiny bit of compute exactly where you need it - no more.

Static (edge):  /  /listings  /place/*  /cuisine/*  /map  /blog/*
Server (Worker): /api/submit  /api/contact  /api/subscribe

This keeps hosting costs at rounding-error levels - most of the traffic never touches compute - while still letting the public interact with the site.

Spam protection without CAPTCHA

Those public form endpoints are the one attack surface, so they're worth hardening. I really didn't want to slap a CAPTCHA on real users, so I went with a layered guard that's invisible to humans, cheapest checks first:

Honeypot - a hidden field real users never see. Bots fill every field; if it's populated, the endpoint fakes success and saves nothing.
Timing - a hidden timestamp stamped on page load. Submissions that arrive implausibly fast (bots) or suspiciously stale (replayed pages) are dropped.
Origin check - posts must come from your own domain.
User-Agent check - blocks lazy scripted clients that don't look like a browser.
Per-IP rate limit - using Cloudflare's rate-limiting binding, each IP gets a cap (e.g. 3 per minute per form).

The design detail I like: the bot-shaped rejections (1–4) return a fake success, so a bot gets no signal about what tripped it. Only the rate limit and genuine validation errors show a real message. For most directories this is plenty; you can always add Cloudflare Turnstile on top if you're a bigger target.

Keeping a static site fresh

The obvious objection to "rebuild to publish" is: isn't that annoying? It doesn't have to be. Two patterns solve it:

Build hook + Airtable automation. Create a deploy hook, then add an Airtable automation: "when a record is created or updated → call this webhook." Now editing a listing triggers a rebuild on its own. Edit in the spreadsheet, the site updates a minute later.
Scheduled rebuild. A Cloudflare Cron Trigger (or any CI) that rebuilds hourly/daily.

For a low-edit directory, honestly, deploying by hand when you change something is fine too. But the automation path means "static" never means "manual."

The trade-offs, honestly

No stack is free of them, and pretending otherwise is how you end up with angry comments.

It's a developer's setup. Initial setup and deploy are command-line work - clone, configure, deploy. Day-to-day content editing is all in Airtable and needs no code, but you have to be comfortable getting it running. If you'll never open a terminal, a hosted directory builder is a better fit even at the cost of monthly fees.
Content is build-time. Covered above - great for directories, wrong for anything needing per-request freshness (live inventory, user accounts, real-time anything).
Airtable's free tier has limits. Fine for hundreds of listings; if you're modelling tens of thousands of rows with heavy API traffic, reassess.

For the directory shape specifically, those trade-offs land on the right side of the line for me every time.

Wrapping up

The pattern in one breath: Airtable as a build-time CMS, Astro turning that data into static pages via generic Item/Taxonomy primitives, Cloudflare serving it from the edge with a few server-side form endpoints for the interactive bits. Fast, cheap, owned outright, and - if you do the key/label separation - re-skinnable to any niche without rewriting components.

If you want to build this from scratch, everything above is the blueprint; none of it is secret sauce. If you'd rather not wire up the Airtable loader, the image-download step, the spam guard, and the dynamic routing yourself, I packaged this exact stack as a commercial Astro directory template called LocalFinds - Astro 6, Tailwind v4, Airtable, Cloudflare, with the one-config re-skinning baked in. There's a live demo linked there if you just want to poke at the end result and see whether the architecture feels right before building your own.

Either way - build it or buy it - the stack itself is the takeaway. For read-heavy structured-content sites, this combination is genuinely hard to beat.

Happy building!

How to Set Up a Headless WordPress Site with Astro

Mathias Ahlgren — Thu, 27 Jun 2024 07:26:14 +0000

Here, I'm diving into the exciting world of headless WordPress and Astro. If you're looking to combine the content management power of WordPress with the blazing-fast performance of a static site generator, you're in for a treat. Let's get started!

Introduction

So, what's all this fuss about headless WordPress and Astro? Well, imagine taking WordPress's fantastic content management capabilities and pairing them with a modern, lightning-fast front end. That's exactly what we're doing here!

Headless WordPress means we're using WordPress solely as a backend, handling all our content creation and management. Meanwhile, Astro steps in as our front-end superhero, delivering that content to users with incredible speed and flexibility.

Why bother with this setup? Simple: you get the best of both worlds. Content editors can stick with the familiar WordPress interface, while developers can build a blazing-fast, SEO-friendly frontend using modern tools and frameworks. It's a win-win!

Before we dive in, I've got a hot tip for you: check out AstroWP - headless WordPress starter kit. It's an awesome resource that can jumpstart your headless WordPress project with Astro. While we'll be building our site from scratch in this tutorial, AstroWP is definitely worth exploring if you want to hit the ground running on future projects.

Prerequisites

Before we jump in, let's make sure you've got everything you need:

A WordPress installation (don't worry, we'll cover this)
Basic knowledge of JavaScript and React (we'll be using some React components)
Node.js and npm installed on your machine
Familiarity with the command line (nothing too scary, I promise!)

Got all that? Great! Let's dive in.

Setting Up WordPress

First things first, let's get WordPress up and running:

If you haven't already, install WordPress on your favorite web host. There are tons of great guides out there if you need help with this step.
Once WordPress is installed, log into your admin panel and head to the Plugins section. You need to install a crucial plugin called WPGraphQL. This nifty tool exposes your WordPress data through a GraphQL API, which we'll use to fetch content for our Astro site.
Search for "WPGraphQL" in the plugin directory, install it, and activate it. Easy peasy!
Now, let's create some sample content. Add a few blog posts and pages so we have something to work with. Don't stress about making it perfect – we're just testing things out.

Alright, our WordPress setup is good to go. Time to switch gears and set up Astro!

Setting Up Astro

Now for the fun part – let's get Astro up and running:

Open up your terminal and navigate to where you want your project to live.
Run the following command to create a new Astro project:

   npm create astro@latest

Follow the prompts to set up your project. When asked which template to use, choose the "Empty" (minimal) option from the list.
Once the installation is complete, cd into your new project directory and run:

   npm install

This will install all of the needed dependencies.

   npm run dev

This starts the development server and gives you a local preview of your site.

Open up your browser and navigate to http://localhost:4321. You should see a blank Astro site. Not very exciting yet, but we're about to change that!

Heads up (Astro 6+): If you picked the minimal template and npm run dev throws a ! integrations: Required config error, just add an empty integrations: [] array to your astro.config.mjs. We'll be adding the React integration there in a moment anyway, so this resolves itself in the next section.

Take a moment to explore the project structure. You'll see a src folder with pages and components subdirectories. This is where we'll be spending most of our time.

Connecting Astro to WordPress

Now that we have both WordPress and Astro set up, it's time to introduce them to each other:

First, let's add the React integration. Astro ships with an astro add command that installs the integration, pulls in its peer dependencies, and wires up your config in one step. Run the following and accept the prompts:

   npx astro add react

This automatically updates your astro.config.mjs so it looks something like this:

   import { defineConfig } from 'astro/config';
   import react from "@astrojs/react";

   export default defineConfig({
     integrations: [react()]
   });

If you ever see a Cannot find package 'react' warning when starting Astro, install the peer dependencies manually with npm install react react-dom @types/react @types/react-dom.

Now, we need to set up our environment variables. Create a new file in your project root called .env and add the following:

   WP_URL=https://your-wordpress-site.com/graphql

Replace https://your-wordpress-site.com with your actual WordPress site URL.

Great job! We've now got the groundwork laid for our headless WordPress + Astro site. In the next section, we'll start fetching data from WordPress and displaying it in our Astro site. Exciting times ahead!

Fetching Data from WordPress

Alright, now we're getting to the good stuff. Let's fetch some data from WordPress and display it in our Astro site:

First, let's create a new file in the src/pages directory called index.astro. This will be our homepage.
Open up index.astro and add the following code:

   ---
   const response = await fetch(import.meta.env.WP_URL, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       query: `
         query HomePagePosts {
           posts(first: 5) {
             nodes {
               title
               excerpt
               slug
             }
           }
         }
       `
     })
   });

   const json = await response.json();
   const posts = json.data.posts.nodes;
   ---

   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <title>My Headless WordPress Site</title>
     </head>
     <body>
       <h1>Welcome to My Blog</h1>
       <ul>
         {posts.map((post) => (
           <li>
             <h2>{post.title}</h2>
             <p set:html={post.excerpt}></p>
             <a href={`/posts/${post.slug}`}>Read more</a>
           </li>
         ))}
       </ul>
     </body>
   </html>

This code does a few things:

It sends a GraphQL query to our WordPress site to fetch the latest 5 posts.
It then takes that data and renders it in a simple HTML structure.

Save the file and check out your Astro dev server. You should now see your WordPress posts displayed on the page!

Pretty cool, right? We're now pulling data from WordPress and displaying it in our Astro site. But we can do even better. In the next section, we'll set up dynamic routing to create individual pages for each of our blog posts.

Creating Dynamic Routes

Now that we've got our posts showing up on the homepage, let's create individual pages for each post:

Create a new file in src/pages called posts/[slug].astro. The square brackets in the filename tell Astro that this is a dynamic route.
Open [slug].astro and add the following code:

   ---
   export async function getStaticPaths() {
     const response = await fetch(import.meta.env.WP_URL, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         query: `
           query AllPosts {
             posts {
               nodes {
                 slug
               }
             }
           }
         `
       })
     });

     const json = await response.json();
     const posts = json.data.posts.nodes;

     return posts.map((post) => {
       return {
         params: { slug: post.slug },
         props: { slug: post.slug },
       };
     });
   }

   const { slug } = Astro.props;

   const response = await fetch(import.meta.env.WP_URL, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       query: `
         query SinglePost($slug: ID!) {
           post(id: $slug, idType: SLUG) {
             title
             content
           }
         }
       `,
       variables: {
         slug: slug,
       }
     })
   });

   const json = await response.json();
   const post = json.data.post;
   ---

   <html lang="en">
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <title>{post.title}</title>
     </head>
     <body>
       <h1>{post.title}</h1>
       <div set:html={post.content}></div>
       <a href="/">Back to Home</a>
     </body>
   </html>

This code does a few important things:

The getStaticPaths function fetches all post slugs from WordPress and tells Astro to create a page for each one.
We then fetch the specific post data for each page and render it.

Now, if you click on the "Read more" links on your homepage, you should be taken to individual post pages!

Awesome work! We've now got a fully functional headless WordPress site built with Astro. Of course, there's always room for improvement. In the next sections, we'll look at styling our site and optimizing its performance.

Styling Your Astro Site

Now that we've got our content displaying correctly, let's make it look a bit nicer:

Astro supports several styling options out of the box. For this tutorial, we'll use Astro's built-in CSS support.
Create a new file in src/styles called global.css.
Add some basic styles to global.css:

   body {
     font-family: Arial, sans-serif;
     line-height: 1.6;
     color: #333;
     max-width: 800px;
     margin: 0 auto;
     padding: 20px;
   }

   h1, h2 {
     color: #2c3e50;
   }

   a {
     color: #3498db;
     text-decoration: none;
   }

   a:hover {
     text-decoration: underline;
   }

Now, let's import this CSS file in our pages. In both index.astro and posts/[slug].astro, add this line in the <head> section:

   <link rel="stylesheet" href="/styles/global.css" />

Refresh your browser, and you should see a much nicer-looking site!

Remember, this is just a starting point. Feel free to expand on these styles and make the site your own!

Optimizing Performance

One of Astro's big selling points is its focus on performance. Let's take advantage of some of Astro's features to make our site even faster:

Astro uses partial hydration, which means it only sends JavaScript to the browser when it's needed. This is great for performance, but we haven't actually used any client-side JavaScript yet. If you need interactivity, you can use Astro's client directives like client:load or client:idle on your components.
For image optimization, Astro has a built-in Image component. Let's use it for our post thumbnails. First, install the sharp package:

   npm install sharp

Before we can render a thumbnail, we need to actually fetch the featured image data. Update the GraphQL query in your index.astro to include the featuredImage field:

   query HomePagePosts {
     posts(first: 5) {
       nodes {
         title
         excerpt
         slug
         featuredImage {
           node {
             sourceUrl
           }
         }
       }
     }
   }

Then, in your index.astro file, import the Image component and use it for your post thumbnails:

   ---
   import { Image } from 'astro:assets';
   // ... rest of your frontmatter code
   ---

   <!-- In your HTML, inside the posts.map() loop -->
   {post.featuredImage && (
     <Image
       src={post.featuredImage.node.sourceUrl}
       width={300}
       height={200}
       alt={post.title}
       inferSize
     />
   )}

Note: Remote images from WordPress need their domain authorized in astro.config.mjs under the image.domains (or image.remotePatterns) setting before Astro will optimize them.

Astro also automatically optimizes your CSS and HTML. It removes unused CSS and minifies your HTML in production builds.

Deployment

We're in the home stretch! Let's get your site deployed:

First, build your site with:

   npm run build

This will create a dist folder with your production-ready site.
You can deploy this folder to any static hosting service. Netlify, Vercel, and Cloudflare Pages are popular options that work great with Astro.
If you're using Netlify, you can simply drag and drop your dist folder onto their site to deploy.
For automated deployments, you can set up a GitHub repository for your project and connect it to your hosting service. Then, every time you push to your main branch, your site will automatically rebuild and deploy.

Summary

And there you have it! We've successfully set up a headless WordPress blog with Astro. We've covered everything from initial setup to deployment, touching on data fetching, routing, styling, and performance optimization along the way.

Remember, this is just the beginning. There's so much more you can do with this setup. You could add custom post types, implement search functionality, or even turn your site into a full-fledged e-commerce platform.

I hope this tutorial has been helpful and has sparked some ideas for your own projects. Happy coding!

Troubleshooting Common Issues

Before we wrap up, let's quickly address some common issues you might run into:

CORS errors: If you're getting CORS errors when trying to fetch data from WordPress, you may need to install a CORS plugin in WordPress or configure your server to allow cross-origin requests.
GraphQL errors: Double-check your query syntax if you're getting GraphQL errors. The WPGraphQL plugin provides a GraphiQL interface in the WordPress admin panel where you can test your queries.
Astro build problems: If you're having issues building your Astro site, make sure all your dependencies are up to date. You can also try clearing your .astro cache folder.

Remember, the Astro and WordPress communities are very helpful. If you run into any issues you can't solve, don't hesitate to reach out for help!

P.S. if you haven't already, you definitely need to check out EmDash, a CMS built on Astro and Cloudflare.

This article has been updated from its original version. Changes include: clarifying the "Empty" (minimal) Astro template name, switching React setup to the recommended npx astro add react command, adding a fix for the Astro 6 integrations: Required error, and correcting the featured-image example to fetch the featuredImage field it relied on.