Directory site with Astro and client-side search on Netlify
For curators who need a directory with filtering and search, static pages, Git-based updates and no database.
This recipe is assembled from official documentation and was not built end to end for this page.
The parts
| Role | Tool | Why |
|---|---|---|
| Framework | Astro | Astro statically compiles structured JSON datasets into fast individual profile pages and index listings with zero JavaScript overhead. |
| Hosting | Netlify | Netlify provides global static asset hosting, Git-triggered rebuilds, and automatic branch previews for incoming community submissions. |
Why this stack fits
Curated directories depend on being easy to find and quick to browse. By storing directory entries directly as version-controlled JSON data in the repository and building with Astro on Netlify, operators eliminate database maintenance, lower the risk of downtime, and get fast page loads.
Astro is well suited to generating large sets of static pages from structured data. As documented on the Astro official website and in the Astro getting started guide, Astro compiles templates directly into static HTML files during the build phase. Using Astro content collections, curators define strict schemas for their data files using Zod, so every tool, product, or community listing has valid URLs, descriptions, categories, and tags before it is published.
Netlify provides an edge network and continuous deployment. According to the Netlify official website and the Netlify documentation, Netlify automatically triggers builds upon every Git commit or pull request. This lets community members submit listings as GitHub pull requests. Each one gets a branch preview for editorial review before it is merged.
How the components connect
Data files become edge-cached HTML in five steps:
- Structured data storage: Directory listings are stored as individual JSON or YAML files inside
src/content/directory/. - Schema validation: During the build, Astro validates every record against the collection schema, preventing broken links or missing tags from entering production.
- Static pre-rendering: Astro iterates through the dataset using
getStaticPaths(), compiling individual detail pages (such as/tools/my-tool) and categorized index pages into pure static HTML. - Client-side search index: At build time or on page load, a lightweight JSON search index is generated. A compact client-side search component filters and sorts listings in the visitor's browser without calling an external search server.
- Edge hosting: Netlify deploys the compiled directory across its global content delivery network, caching pages at edge locations for fast global delivery.
What it costs to run
Because the site compiles to static files with no active database:
- Astro: Free and open source under the MIT license with no recurring software fees (Astro License).
- Netlify: Operates on a freemium pricing model, offering a free tier that includes continuous Git builds, SSL for custom domains, and monthly bandwidth (Netlify Pricing).
For directories containing up to a few thousand listings, the entire platform runs within free tier limits at zero monthly hosting cost.
When to pick something else
Consider these alternative solutions when directory requirements evolve:
- Cloudflare Pages: If your directory experiences very high traffic volumes, Cloudflare Pages provides static hosting with unlimited bandwidth on its free plan (Cloudflare Pages documentation and Cloudflare Pages platform limits).
- Relational database (PostgreSQL / Supabase): If your directory scales beyond tens of thousands of items, requires real-time user upvoting, or accepts direct self-service user submissions that cannot wait for a static build step, switching to a managed database backend becomes necessary.
Setup steps
- Initialize an Astro project using npm create astro@latest.
- Structure directory data as JSON or YAML files within the src/content/ directory.
- Define a type-safe collection schema in src/content.config.ts using Astro content collections to validate item properties.
- Build dynamic listing routes in src/pages/[slug].astro using getStaticPaths() to pre-render every directory item at build time.
- Implement a lightweight client-side search and filter bar using vanilla JavaScript or a client-side search library embedded into the directory index page.
- Deploy the repository to Netlify with automated Git continuous deployment.
Tradeoffs
- Catalog updates require triggering a site build and deployment rather than updating records dynamically in a live database table.
- Client-side search and filtering require downloading the catalog index in the browser, which can increase payload size as the directory grows beyond thousands of items.
- Community submissions must be ingested via pull requests, forms, or webhook integrations rather than direct self-service database entries.
Swap options
Hosting: Cloudflare Pages. Swap to Cloudflare Pages for unlimited bandwidth and fast edge caching across Cloudflare global data center network.