next-sitemap: generating sitemap.xml and robots.txt for Next.js builds

The gap next-sitemap fills between a Next.js build and search crawlers

A Next.js build knows every route it produced. Nothing in that build writes a sitemap. The framework's output is HTML, JS chunks and route manifests, not a crawler-facing index. Teams usually notice the gap only after launch, when Search Console reports that pages are discovered slowly or not at all.

next-sitemap is aimed at that exact seam. It is a postbuild step: it runs after `next build`, reads the build output, and writes sitemap files plus an optional robots.txt into the public directory. The README describes it as generating sitemaps for "all static/pre-rendered/dynamic/server-side pages", which is the honest scope. It is for Next.js developers who want the sitemap to be a build artifact rather than a manually curated file that drifts out of date.

It is not a crawler and it is not a runtime service. If a page only exists after a user creates it, the build has no way to know about it, and next-sitemap will not discover it on its own.

How the generation step actually runs inside your build

The mechanism is deliberately plain. You add next-sitemap to the `postbuild` script in package.json. When `next build` finishes, npm runs `next-sitemap`, which loads `next-sitemap.config.js` from the project root, resolves `siteUrl`, enumerates routes from the build output, and writes files.

The README notes that environment variables from `.env` files are loaded by default, which is why the example config can use `process.env.SITE_URL` with a fallback. That matters on platforms where the production URL differs from local development.

From v2.x onward, `sitemap.xml` is an index sitemap: it contains URLs of the other generated sitemap endpoints rather than page URLs directly. For a small site that indirection is noise, and the README says it can be turned off with `generateIndexSitemap: false`. For a large site it is the point, because a single sitemap file has practical size limits and splitting keeps each file small.

Splitting is controlled by `sitemapSize`. The README's example sets it to 7000 and states that when the URL count exceeds that number, next-sitemap creates files such as `sitemap-0.xml` and `sitemap-1.xml` alongside the index. That is the whole data flow: build output in, XML files out.

Installing next-sitemap and producing your first sitemap.xml

Install it as a project dependency. The README gives the yarn form:

yarn add next-sitemap

Next, create `next-sitemap.config.js` in the project root. The README marks this file as required and gives this minimal shape, where `generateRobotsTxt` is optional:

/** @type {import('next-sitemap').IConfig} */
module.exports = {
  siteUrl: process.env.SITE_URL || 'https://example.com',
  generateRobotsTxt: true, // (optional)
}

Then wire it into the build as a postbuild script, so it runs automatically after every production build:

{
  "build": "next build",
  "postbuild": "next-sitemap"
}

After a build you should find the generated sitemap files in your public output, with `sitemap.xml` acting as an index when index sitemaps are enabled. If you prefer a different config filename, the README documents passing `--config`, for example `next-sitemap --config awesome.config.js`, and it ships a `custom-config-file` example.

One packaging detail trips people up. The README states that with pnpm you must create a `.npmrc` file in the project root containing `enable-pre-post-scripts=true` if you want the postbuild step to run at all. Without it, `next build` succeeds and no sitemap appears, which looks like a next-sitemap bug but is a package manager default.

Dynamic routes, transform, and the limits of build-time enumeration

The README separates static generation from "Generating dynamic/server-side sitemaps" and points to a custom transformation function for adjusting entries. The `transform` hook is where you change what a route looks like in the output, and `additionalPaths` is the documented way to inject URLs the build did not enumerate.

That is a real limitation, not a footnote. A blog with posts stored in a CMS, a marketplace with per-seller pages, or a docs site whose routes come from a database will not be fully covered by whatever the build emitted. You have to supply those URLs yourself. If the list changes between deploys, the sitemap is only as fresh as the last build.

The configuration surface is broad. The README's options table lists `siteUrl`, `output` (with `standalone` and `export` modes), `changefreq` defaulting to `daily`, and `priority` defaulting to `0.7`, among others. Defaults like a daily changefreq applied to every URL are a blunt instrument; search engines treat changefreq and priority as hints, and uniform values carry little information. Overriding them per route through the transform function is possible, but it is work the tool will not do for you.

The repository layout also shows the tooling the project itself uses: a workspace with `packages/*`, `examples/*` and `docs`, built with turbo and tested with bun. That tells you the maintainers run a modern monorepo, not that your integration will be frictionless.

Where next-sitemap is the wrong choice

The clearest failure mode is a site whose URL set is not knowable at build time. If pages are created by users after deploy, a build-time sitemap will always lag, and re-running the build to refresh it is the wrong lever. A server route that queries the database on each request for `/sitemap.xml` fits that shape better.

A second case is a site that is not built with Next.js. The tool is coupled to Next.js build output and its config is typed against `import('next-sitemap').IConfig`. Pointing it at a static site generator or a different framework means fighting the assumptions rather than using them.

A third is a very small site where the index sitemap adds a layer for no benefit. The README acknowledges this by offering `generateIndexSitemap: false` for "small/hobby sites which does not require an index sitemap". If you are in that group, the default behaviour is more machinery than the problem needs.

Finally, there is the question of what the tool does not do. It writes sitemaps and robots.txt. It does not submit them to search engines, does not validate that the URLs return 200, and does not report which routes were omitted. A missing route is silent.

How next-sitemap compares with a hand-written sitemap route

The most direct alternative is a Next.js route handler or API route that returns XML, built by hand or with a small XML library. The difference is where the URL list comes from. A route handler runs per request and can query a database or CMS at that moment, so a page created a minute ago can appear immediately. next-sitemap runs once, after `next build`, and reflects the build.

That trade is real in both directions. The route handler needs caching, because regenerating XML on every crawler hit is wasteful, and it needs its own logic for splitting, indexing, robots.txt and XML escaping. next-sitemap gives you those behaviours as configuration: `sitemapSize` for splitting, `generateIndexSitemap` for the index, `generateRobotsTxt` for robots.txt, and a transform hook for per-URL edits. You get a static file that is cheap to serve and versioned with the deploy.

There is also the manual option: write `sitemap.xml` by hand and commit it. That works until the route list changes, at which point the file is stale and nobody notices. The reason to use a generator at all is to make staleness impossible for the routes the build knows about.

If your content is database-driven and updated continuously, the route handler is the better architecture and next-sitemap is the wrong layer. If your routes are code, next-sitemap removes a class of manual work.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-05-13. The most recent release listed is v4.2.3 from 2023-09-06, with v4.2.2 and v4.2.1 before it in August 2023. So there is ongoing repository activity while the published releases have been stable for some time. If you are evaluating this for a long-lived project, that gap between commits and releases is worth understanding before you assume new features are coming.

The licence is MIT, stated in the repository and in the workspace package.json. That permits commercial use and modification, but this is not legal advice and you should read the LICENSE file yourself if licence terms matter to your organisation.

Upgrade cost is mostly configuration compatibility. The v2.x change that made `sitemap.xml` an index sitemap is the kind of shift that alters what crawlers see, so a major upgrade deserves a check of the generated files rather than a blind bump. The changelog.md at the repository root is where the project records changes; the README does not document a rollback procedure, so pinning a known-good version in package.json is the practical safeguard. Because the tool runs as a postbuild step, a broken upgrade fails the build rather than silently shipping bad XML, which is a favourable failure mode.

Editorial conclusion

Adopt next-sitemap if you run a Next.js site whose routes are stable enough to enumerate at build time and you want sitemap.xml and robots.txt produced by the same build that ships the pages. Skip it if your URLs are created at runtime by user content, or if you need per-request sitemap generation that reflects data written after the deploy. Before wiring it into CI, verify two things: that your dynamic routes are covered by additionalPaths or transform, and that your package manager runs postbuild scripts at all, since the README documents that pnpm needs enable-pre-post-scripts=true in .npmrc.

Frequently asked questions

Official sources

1. iamvishnusankar/next-sitemap on GitHub
2. License: MIT
3. Project website
4. README
5. Releases