Updated 2026-10-21

Add SEO meta tags to an Astro site at build time

Astro builds static HTML by default, which is exactly what Headlark needs: it reads each page in dist after astro build and writes the metadata into it.

1. Install and chain it onto the build

npm i -D headlark

// package.json
"scripts": {
  "build": "astro build && headlark dist --site-url https://example.com"
}

Use the same address you set as site in astro.config.mjs. Astro writes /blog/hello/ as dist/blog/hello/index.html; Headlark maps that back to https://example.com/blog/hello/.

Or use the Astro integration

npx astro add astro-headlark

It does the same after astro build, takes the address from site (and base) in your config, and skips when HEADLARK_KEY isn't set. The Astro docs cover both options.

2. Set the key

Add HEADLARK_KEY (your site's secret key from the dashboard) to the environment where the build runs. On Netlify you can use the build plugin instead of editing the script.

If you already use astro-seo or your own head component

• Your canonical, robots directive and any JSON-LD types you emit are kept as they are.
• The title, description and Open Graph/X tags are written by Headlark. It reads your existing ones as part of the page.
• Images that already have an alt keep it. Only images without one get alt text.

Good to know

• Pages rendered on demand by an SSR adapter have no HTML at build time, so the build step can't reach them. Prerendered pages work as usual.
• Rebuilds are free when a page's content hasn't changed; build timestamps and similar incidental changes don't count.
• Add --strict to fail the build if a page can't be optimized.

See what's missing first

The free site checker reads your live site's sitemap and lists duplicate titles, missing descriptions and broken link previews across up to 50 pages. No account needed.

Try it

The free plan covers one site and 25 pages. Add your site, copy its secret key, and your next build ships with SEO.