Updated 2026-10-20

Add SEO meta tags to a Next.js static export

With output: "export", next build writes plain HTML files to out. Headlark reads those files and writes the metadata into them before deploy.

1. Static export

// next.config.mjs
export default { output: "export" };

2. Install and chain it onto the build

npm i -D headlark

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

Set HEADLARK_KEY to your site's secret key in the build environment. The Next.js docs have the reference, including what to do with a basePath.

Want to see what crawlers get from your deployed pages first? The free site checker lists duplicate titles, missing descriptions and broken link previews across up to 50 pages.

What happens to your Metadata API tags

• alternates.canonical, robots and JSON-LD types you render are kept.
• The title, description and Open Graph/X tags are written by Headlark, using your existing ones as input.

Good to know

• Client-side navigation: Headlark rewrites the HTML files. When a visitor clicks between pages, Next.js can apply metadata from its own route payload, so the browser tab may show your original title after navigation. Crawlers and link previewers load each page's HTML directly and see Headlark's tags.
• Server rendering, ISR and route handlers aren't part of a static export and aren't covered by the build step.
• The generated 404.html is processed too; error pages get noindex unless you already set robots.

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.