Skip to Content

Framework Adapters

Serve sitemap and robots routes with Fetch handlers and framework adapters.

@puzzle-ui/seo provides framework-independent server handlers and small adapters for Next.js, TanStack Start, and React Router.

Install

See the complete SEO tutorial for endpoint mounting and choosing a single SSR metadata writer.

npm install @puzzle-ui/seo react

React 19 is a peer dependency. Framework adapters do not require a framework package at runtime.

Quick start

import { createSeoRouteHandlers } from "@puzzle-ui/seo/server";

const handlers = createSeoRouteHandlers({
  sitemap: {
    sitemap: { baseUrl: "https://example.com", entries: [{ url: "/" }] },
    cacheControl: "public, max-age=3600",
  },
  robots: {
    robots: { rules: [{ userAgent: "*", allow: ["/"] }], sitemap: "https://example.com/sitemap.xml" },
    cacheControl: "public, max-age=3600",
  },
});
// Mount handlers.sitemap and handlers.robots where your server receives Request objects.

Both handlers return Promise<Response>. The sitemap handler serves the configured index path and generated sitemap filenames; it serves the single file at the index path when no index is needed. The robots handler serves the configured robots path. Unknown paths return 404; generation issues return 500 with no-store. Configure your platform to route generated filenames as well as the index.

Handler options

NameTypeDefaultDescription
sitemap.sitemapSitemapGenerationOptionsrequiredSitemap generation input.
sitemap.pathstring/{filename}.xmlPublic index path; filename defaults to sitemap.
sitemap.cacheControlstring"public, max-age=3600, s-maxage=3600"Response cache policy.
robots.robotsRobotsOptionsrequiredrobots.txt generation input.
robots.pathstring/robots.txtPublic robots path.
robots.cacheControlstring"public, max-age=3600, s-maxage=3600"Response cache policy.

createSitemapHandler and createRobotsHandler return text response objects instead of Fetch responses. Their optional Request lets them select the requested path. Review generation errors and cache settings before exposing routes in production.

Framework adapters

Each adapter accepts the same route options as createSeoRouteHandlers. Create the options in a shared server module, then mount the returned functions in the framework's route files:

import { createNextSeoRoutes } from "@puzzle-ui/seo/next";
import { createTanStackSeoRoutes } from "@puzzle-ui/seo/tanstack";
import { createReactRouterSeoRoutes } from "@puzzle-ui/seo/react-router";

const options = {
  sitemap: { sitemap: { baseUrl: "https://example.com", entries: [{ url: "/" }] } },
  robots: { robots: { rules: [{ userAgent: "*", allow: ["/"] }] } },
};

const next = createNextSeoRoutes(options);
const tanstack = createTanStackSeoRoutes(options);
const reactRouter = createReactRouterSeoRoutes(options);
FrameworkSitemap mountRobots mount
Next.jsExport next.sitemapGET as GET from a dynamic root route such as app/[seoFile]/route.ts.Export next.robotsGET as GET from app/robots.txt/route.ts.
TanStack StartMount tanstack.sitemapGET as the GET server handler for a dynamic root route such as /$seoFile. It receives { request }.Mount tanstack.robotsGET on /robots.txt.
React RouterExport reactRouter.sitemapLoader as loader from a dynamic root resource route such as /:seoFile.Export reactRouter.robotsLoader as loader from the /robots.txt resource route.

Framework routing conventions and route priority remain the application's responsibility. Ensure the static robots route wins over the dynamic sitemap route and that custom path settings match the routes you mount.

Exports

  • @puzzle-ui/seo/server: createSitemapHandler, createRobotsHandler, createSeoRouteHandlers and server types.
  • @puzzle-ui/seo/next: createNextSeoRoutes and NextSeoRoutes.
  • @puzzle-ui/seo/tanstack: createTanStackSeoRoutes and the TanStack route types.
  • @puzzle-ui/seo/react-router: createReactRouterSeoRoutes and the React Router loader types.