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

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:

1. A friendly way to manage the data (ideally one a non-technical client can use).
2. A build step that turns that data into fast, static HTML.
3. 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:

1. Honeypot - a hidden field real users never see. Bots fill every field; if it's populated, the endpoint fakes success and saves nothing.
2. Timing - a hidden timestamp stamped on page load. Submissions that arrive implausibly fast (bots) or suspiciously stale (replayed pages) are dropped.
3. Origin check - posts must come from your own domain.
4. User-Agent check - blocks lazy scripted clients that don't look like a browser.
5. 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!