ads.txt & sellers.json

Deploying ads.txt on static hosts and CDNs: public folders, redirects, headers and caching

Last updated Published By the editorial team6 min6 sources

Key takeaways

  • On static hosts, ads.txt belongs in the framework folder that is copied unchanged to the build output: public/ in Astro and Next.js, static/ in Hugo, a passthrough copy in Eleventy.
  • Netlify does not let a rewrite rule shadow a file that exists unless the rule ends with !, while Cloudflare Pages states that redirects in _redirects are always followed even when an asset matches.
  • Cloudflare Pages treats a project without a top-level 404.html as a single-page application and serves the root page for unknown paths, so a missing ads.txt returns HTML instead of a 404.
  • GitHub Pages creates redirects between the apex domain and www automatically when DNS records for both are configured.
  • On Amazon S3, Content-Type is object metadata you can set, and CloudFront keeps serving a cached ads.txt until it expires or is invalidated.
Close-up of an optical fiber cable with glowing strands
Image: Optical fiber cable-10ASD,Asurnipal,CC BY-SA 4.0,via Wikimedia Commons.

On a static host, ads.txt is just a file in your build output, so most failures come from the build or routing layer: the file is not copied, an SPA fallback answers /ads.txt with HTML, a redirect rule hijacks the path, or the bare domain does not reach the site. Put the file in your framework’s public folder, then verify the deployed URL on both the apex domain and www.

Where does ads.txt go in each framework?

The goal is a file at the root of the build output, served as /ads.txt. Each generator has a folder copied verbatim:

Framework Source location Documented behaviour
Astro public/ads.txt Files in public/ “will be copied into the build folder untouched”
Next.js public/ads.txt Files in public are referenced “starting from the base URL (/)”
Hugo static/ads.txt static files “will be copied to the public directory when you build”
Eleventy eleventyConfig.addPassthroughCopy("ads.txt") Passthrough copy sends files “to the output folder”
Plain HTML Next to index.html Whatever directory you deploy

Sources: Astro project structure, Next.js public folder, Hugo directory structure, Eleventy passthrough copy. Framework-specific AdSense setup is in AdSense in Astro and AdSense in Hugo and Eleventy.

Commit the file to version control. A file uploaded by hand to a host that rebuilds from Git disappears at the next deploy, and Google’s crawl help warns that a 404 on recrawl purges previously crawled entries.

Netlify

Put ads.txt in the publish directory (via your framework’s public folder). Two behaviours matter:

Rewrites do not shadow existing files. Netlify’s Rewrites and proxies page says: “By default, you can’t shadow a URL that actually exists within the site.” A typical SPA rule /* /index.html 200 leaves a real /ads.txt alone. Two exceptions: a rule forced with ! (for example /* /index.html 200!) overrides files, and if ads.txt is missing from the deploy, the catch-all serves index.html with status 200, which is a soft 404.

Headers. If you want to control caching, Netlify reads a _headers file in the publish directory:

/ads.txt
  Cache-Control: public, max-age=0, must-revalidate

Netlify’s custom headers apply “only to files Netlify serves from our own backing store”, not to responses from functions or edge functions.

Vercel

Place the file in your framework’s public folder. Vercel’s vercel.json reference documents two options that touch URLs:

  • trailingSlash: true redirects paths without a slash, but “paths with a file extension will not redirect to a trailing slash”, so /ads.txt is not affected.
  • cleanUrls removes extensions from HTML files and functions only.

Custom headers, for example a cache policy, go in vercel.json:

{
  "headers": [
    {
      "source": "/ads.txt",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=0, must-revalidate" }]
    }
  ]
}

If ads.txt is generated by a route handler or middleware instead of a static file, make sure that code path returns status 200 and text/plain on every request.

Cloudflare Pages

Place ads.txt in the static asset directory (public/ or static/ with a framework, or the build output directory without one). Two documented behaviours are traps:

Redirects always win. Cloudflare’s Redirects page states: “Redirects are always followed, regardless of whether or not an asset matches the incoming request.” A broad rule in _redirects such as /* /new-path 301 captures /ads.txt too. Keep catch-all redirects specific, or put an explicit /ads.txt exception first.

SPA fallback. According to Serving Pages, if there is no top-level 404.html, Pages “assumes that you are deploying a single-page application” and serves the root for unknown paths. A missing ads.txt then returns your home page with status 200. Adding a 404.html makes missing files return a real 404, which is easier to diagnose.

Pages keeps deployed assets cached on its CDN “until your next deployment”, so a new deploy is how you publish a changed file. Note also that Cloudflare lists domain-level redirects as unsupported in _redirects, so an apex-to-www redirect has to be configured elsewhere in Cloudflare (Bulk Redirects, for example).

GitHub Pages

Put ads.txt at the root of your publishing source (the branch root, /docs, or the artifact your Actions workflow uploads). Two points:

  • Apex and www. GitHub’s custom domain documentation says that if you configure the correct DNS records for both the apex and www, “GitHub Pages will automatically create redirects between the domains”. Configure both so the root domain reaches the file.
  • Project sites. A project site at username.github.io/project/ cannot host the root file; username.github.io/ads.txt comes from the user site repository (username.github.io). With a custom domain on the project site, the file goes at the project’s publishing root.

Amazon S3 and CloudFront

Upload ads.txt to the root of the bucket (object key ads.txt, no prefix). Two checks:

  • Content-Type. In S3, Content-Type is system metadata that the user can set, according to the S3 object metadata documentation. Confirm it is text/plain with curl -sI. The IAB specification says other content types should be treated as an error.
  • CDN cache. CloudFront serves the cached object until it expires. AWS’s invalidation guide says that to remove a file from edge caches before it expires you can invalidate it, after which “CloudFront returns to the origin to fetch the latest version.” Versioned file names are not an option for ads.txt, whose path is fixed, so invalidate /ads.txt after each change.

Also make sure the apex domain resolves to the distribution, or redirects to www with the path preserved.

Caching: how long should ads.txt be cached?

The IAB ads.txt 1.1 specification says consumers should respect standard HTTP cache headers and, when none are present, “default to an expiry of 7 days.” Google does not say how it applies cache headers; it says AdSense changes take a few days, up to a month for sites with few ad requests. A short or revalidating cache on your side means any crawler gets your current file. Next.js documents Cache-Control: public, max-age=0 for files in public, and Cloudflare Pages says it sometimes adds Cache-Control: public, max-age=0, must-revalidate.

Common mistakes on static hosts

Mistake What the crawler gets Fix
File uploaded through the host’s dashboard, not committed 404 after the next Git deploy Commit ads.txt to the public or static folder
File placed in src/ or content/ instead of the copied folder 404, or the SPA fallback page Move it to public/ or static/ (or add a passthrough copy)
SPA catch-all with force flag (200!) on Netlify Your index.html Remove ! or exclude /ads.txt
Broad rule in Cloudflare Pages _redirects A redirect away from the file Narrow the rule; redirects beat assets there
Apex domain not connected to the host Connection error or parking page Add the apex to the project and redirect it to the canonical host
Redirect from apex to www that drops the path The home page Preserve the path in the redirect
Preview or branch deploy used as the live URL A different file, or none Check the production domain, not the preview URL
Old file still cached at the CDN Previous content Purge or invalidate /ads.txt

What about monorepos and multiple sites?

If one repository builds several sites, each site’s output needs its own ads.txt, because each domain is crawled separately. When the sites share the same AdSense account and networks, generating the file from a single template at build time keeps them identical. When they differ (different publisher IDs, or one site using an extra network), keep one source file per site and check each deployed domain separately.

Should ads.txt be generated dynamically?

Only if you need to. A plain committed file is the most robust option: it is served as a static asset, gets the host’s default .txt handling and cannot fail because of a function timeout or cold start. If you build it at deploy time (from environment variables, for example), add a build step that fails when the AdSense line is missing, so a broken file never reaches production.

Checklist after every deployment

  1. curl -sIL https://example.com/ads.txt ends in 200 with content-type: text/plain.
  2. Same for http://example.com/ads.txt and both www variants (redirects allowed, see ads.txt Not found).
  3. curl -sL https://example.com/ads.txt shows your lines, not HTML.
  4. A deliberately wrong path such as /ads-test-404.txt returns 404, proving your host does not hide missing files behind an SPA fallback.
  5. Automate these checks in CI, as shown in validating ads.txt yourself.

Frequently asked questions

Where do I put ads.txt in an Astro or Next.js project?

In the public/ folder at the project root. Astro's documentation says files in public/ are copied into the build folder untouched, and Next.js serves files in public/ from the base URL, so public/ads.txt becomes /ads.txt. Commit it to your repository so every deployment includes it.

Why does my static site return the home page at /ads.txt?

Usually because the file is missing from the build output and the host falls back to your app shell. Cloudflare Pages serves the root page for unknown paths when no top-level 404.html exists, and SPA catch-all rewrites do the same on other hosts. The crawler then gets HTML with status 200. Check that ads.txt is in the deployed output.

Can I host ads.txt on a free subdomain like netlify.app or github.io?

Technically yes: github.io, netlify.app, vercel.app and pages.dev are on the Public Suffix List, so yoursite.netlify.app counts as its own root domain for ads.txt. For a GitHub Pages project site at username.github.io/project/, though, the file must be at username.github.io/ads.txt, which belongs to your user site repository.

Do I need to set a Content-Type header for ads.txt?

Check before changing anything. The IAB specification requires text/plain, so run curl -sI on your ads.txt URL and read the content-type line. If it already says text/plain, leave it. On Amazon S3, Content-Type is stored as object metadata you can set, so verify it after upload and correct it if your upload tool chose something else.

Sources

  1. Ensure your ads.txt files can be crawled · Google AdSense Help
  2. Rewrites and proxies · Netlify Docs
  3. Redirects · Cloudflare Docs
  4. Serving Pages · Cloudflare Docs
  5. Managing a custom domain for your GitHub Pages site · GitHub Docs
  6. Static Configuration with vercel.json · Vercel Docs