@onderwijsin/nuxt-directus-sitemaps

@onderwijsin/nuxt-directus-sitemaps

Generate @nuxtjs/sitemap URLs from Directus. Collection configuration defines what to fetch and maps each record to an application URL, without assuming a Directus schema, slug field, or SEO structure.

Requirements

Installation

pnpm add @onderwijsin/nuxt-directus-client @nuxtjs/sitemap @onderwijsin/nuxt-directus-sitemaps

Install @onderwijsin/nuxt-directus-config too when you need shared executable mappers or custom fetchers:

pnpm add @onderwijsin/nuxt-directus-config

Register the shared config module before its consumers:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    "@onderwijsin/nuxt-directus-config",
    "@onderwijsin/nuxt-directus-client",
    "@onderwijsin/nuxt-directus-sitemaps",
    "@nuxtjs/sitemap"
  ]
});

Configuration

The sitemap module works standalone. Its direct directusSitemaps options are data-only and support collections, static, cache, and the other delivery settings. The optional @onderwijsin/nuxt-directus-config module adds executable shared configuration.

Standalone field mapping

export default defineNuxtConfig({
  directusSitemaps: {
    collections: [
      {
        collection: "articles",
        sitemap: {
          fields: ["slug", "updated_at"],
          fieldmap: { loc: "slug", lastmod: "updated_at" }
        },
        prerender: false
      }
    ]
  }
});

fieldmap maps sitemap properties to properties on each Directus record. loc is required. If no fieldmap or mapper is configured, the fetched record is passed directly to sitemap-entry validation.

Shared configuration

Create directus.config.ts in the Nuxt root. This is the recommended place for sitemap collections: the source is server-only, so it preserves mapper and fetcher functions without serializing them into client or runtime configuration.

// directus.config.ts
import { defineDirectusConfig } from "@onderwijsin/nuxt-directus-config/config";

export default defineDirectusConfig({
  instance: { baseUrl: "https://cms.example.com" },
  collections: [
    {
      collection: "articles",
      sitemap: {
        _sitemap: "articles",
        fields: ["slug", "updated_at"],
        filter: { status: { _eq: "published" } },
        mapper: (item) => {
          if (
            !item ||
            typeof item !== "object" ||
            !("slug" in item) ||
            typeof item.slug !== "string"
          ) {
            return null;
          }

          return {
            loc: `/articles/${item.slug}`,
            lastmod:
              "updated_at" in item && typeof item.updated_at === "string"
                ? item.updated_at
                : undefined,
            priority: 0.8
          };
        }
      },
      prerender: false
    }
  ],
  sitemaps: {
    static: [{ loc: "/about" }],
    apiEndpoint: "/api/_directus-sitemaps/urls",
    cache: { maxAge: 300, staleMaxAge: 0, swr: true },
    prerenderSitemaps: false
  }
});

Collection configuration

collections is shared with related Directus modules. A collection uses sitemap generation when sitemap is an object; set it to false to exclude it.

The default fetcher reads the configured collection with its fields and filter. Runtime mapping uses this precedence: custom shared fetcher, executable shared mapper, declarative fieldmap, then identity mapping. Direct module options cannot contain executable functions.

mapper(item) returns one entry, null, or undefined:

Set sitemap._sitemap to route a collection’s entries to a named sitemap. The module registers the corresponding child source with @nuxtjs/sitemap; multiple collections may use the same name. Named XML routes use the sitemap module’s sitemapsPathPrefix (by default, /__sitemap__/<name>.xml) and /sitemap redirects to /sitemap_index.xml.

Sitemap delivery options

Configure delivery independently of collection selection under sitemaps:

directusSitemaps accepts collections and the delivery settings directly, plus enabled:

// nuxt.config.ts
export default defineNuxtConfig({
  directusSitemaps: {
    enabled: true,
    cache: false,
    prerenderSitemaps: true
  }
});

Direct module settings take precedence over matching shared collection settings by collection name. Nested sitemap settings are merged. Executable shared mapper and fetcher functions are preserved; direct module options cannot define or replace them.

Source endpoint

The module registers sitemaps.apiEndpoint as an @nuxtjs/sitemap source. It returns a JSON array of sitemap URL entries and accepts these optional query parameters:

Invalid query values receive a 400 response. This endpoint is intended for @nuxtjs/sitemap; it does not expose Directus credentials or collection configuration.

Caching, prerendering, and failures

cache affects only the public source response. Every cache revalidation fetches Directus again; the module does not cache Directus data itself. With prerenderSitemaps: true, Directus must be reachable during the build.

Collections run independently. A failed collection fetch or invalid mapper result is logged and omitted by default, while successful collections and static URLs remain in the response. Set failureMode to "hard-failure" to propagate collection-fetch failures. Built-in Directus fetches use bounded offset pagination with queryLimit; custom fetchers receive their existing context unchanged and remain responsible for pagination.

Public API and compatibility

This package is a Nuxt module and does not expose runtime composables or client aliases. Configure it through directusSitemaps, directus.config.ts, and the sitemap source endpoint described above.

Requires Nuxt 4, Node.js 24+, @onderwijsin/nuxt-directus-client 0.4+, and @nuxtjs/sitemap 8+. It uses Nitro-compatible server APIs and supports Node and edge-style Nitro deployments.