@onderwijsin/nuxt-directus-config

@onderwijsin/nuxt-directus-config

Shared, executable Directus configuration for Nuxt. It discovers directus.config.ts, validates it once during Nuxt setup, and makes the resolved settings available to related Directus modules.

The module is optional: each Directus module can still be configured in nuxt.config.ts. When both are used, direct module options take precedence over shared configuration.

Installation

pnpm add @onderwijsin/nuxt-directus-config

Register it before modules that consume the configuration:

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

Shared configuration

Create directus.config.ts in the application root:

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

export default defineDirectusConfig({
  instance: {
    baseUrl: "https://cms.example.com",
    proxyToken: process.env.DIRECTUS_PROXY_TOKEN
  },
  client: {
    commands: ["readItem", "readItems"],
    auth: {
      enabled: true,
      sessionSecret: process.env.DIRECTUS_SESSION_SECRET,
      user: {
        enabled: true,
        fields: ["id", "email", "first_name", "last_name", { role: ["id", "name"] }],
        mapper: (user) => ({
          id: user.id,
          name: [user.first_name, user.last_name].filter(Boolean).join(" "),
          role: user.role?.name ?? null
        })
      }
    }
  },
  collections: [
    {
      collection: "articles",
      sitemap: {
        _sitemap: "articles",
        filter: { status: { _eq: "published" } },
        mapper: () => ({ loc: "/articles" })
      },
      prerender: false
    }
  ],
  sitemaps: {
    static: [{ loc: "/" }],
    apiEndpoint: "/api/_directus-sitemaps/urls",
    sitemapsPathPrefix: "/__sitemap__/",
    enablePrettyUrls: true,
    cache: { maxAge: 300, staleMaxAge: 0, swr: true },
    prerenderSitemaps: false
  },
  prerenderer: {
    includeStaticSitemapUrls: false,
    queryLimit: 100,
    failureMode: "best-effort"
  }
});

The source is executable TypeScript. Use it for server-only values and functions; Nuxt config is serialised and is not suitable for those values. defineDirectusConfig() preserves concrete field selections and mapper return types so consuming Directus modules can generate precise application types from the source. Mapper parameters expose the selected SDK user fields as optional values and keep custom fields available as unknown until the mapper narrows them.

For authentication, cookies, sealing, and secret rotation details, see the @onderwijsin/nuxt-directus-client Authentication documentation. Generate a session secret with:

openssl rand -base64 32

instance

Both fields are sensitive and never appear in the client-safe virtual configuration. proxyToken may remain secret, but its permissions are not private: browser callers can exercise them through the application proxy.

client

client contains Directus client module settings. Its nested schemas provide defaults.

Asset caching is disabled by default. assets.cache.storage names a Nitro storage mount supplied by the application; the module does not create or choose its driver. Use filesystem storage for Node deployments and a raw-byte-capable mount such as Cloudflare R2 for Cloudflare deployments. Cloudflare KV's text-only storage is not recommended. Authenticated or private assets are never cached.

The resolved prune configuration is { enabled: false, onRequest: true, interval: 3600 }. Pruning is opt-in and does not enable Nitro tasks. To use scheduled or manual pruning, the consumer creates its own task file re-exporting @onderwijsin/nuxt-directus-client/runtime/prune-task, explicitly enables Nitro experimental tasks, and optionally configures nitro.scheduledTasks.

Magic links require the directus-magic-links-bundle extension in Directus. The configured callback URL is server-only and is not included in the client-safe configuration.

The default cookie is { name: "directus_session", secure: true, sameSite: "lax", path: "/", maxAge: 2592000 }. commands, authentication cookie settings, refresh timing, session sealing secrets, password-reset URL, and type-generation settings are sensitive and excluded from the client-safe configuration.

The supported command names are exported as supportedDirectusCommands from @onderwijsin/nuxt-directus-config/schema.

collections

collections is a shared list of executable collection behaviour. It is intentionally portable: the sitemap and prerender modules use their respective configuration blocks.

Each collection entry has these options:

Runtime mapping prefers a custom fetcher, then an executable mapper, then a fieldmap, and finally the record itself. A sitemap mapper returns a sitemap entry with required loc and optional lastmod, changefreq, priority, images, videos, news, alternatives, and sitemap metadata fields. The entry may also include noIndex: true to omit it. priority is one of 0, 0.1, …, 1.

The complete sitemap-entry schema is maintained in src/schema/sitemap-entry.ts. Import its exports from @onderwijsin/nuxt-directus-config/schema instead of recreating the shape.

Prerender configuration supports fields, filter, a fieldmap with required route, an executable mapper returning one or more route paths, and an executable fetcher. Use the mapper for composite routes such as ${item.parent.path}/${item.slug}. The prerender module only adds content routes; sitemap XML prerendering remains controlled by sitemaps.prerenderSitemaps.

Collection configuration, including mappers and fetchers, is sensitive and never sent to client code.

sitemaps

sitemaps contains module-wide sitemap delivery settings, independent of which collections are selected:

Sitemap settings are sensitive because they may include static URLs and delivery policy; they are available only to consuming server-side modules.

prerenderer

prerenderer contains module-wide build-time route discovery settings. Direct options under directusPrerenderer take precedence over these shared values.

Virtual modules

The module exposes two aliases with different trust boundaries:

// server/api/example.get.ts
import directusConfig from "#directus-config-server";

Never import #directus-config-server from client code. Nuxt also type-checks server routes in the application context, so this alias is declared for both Nuxt and Nitro type contexts; see Nuxt’s documented limitation.

Discovery and module options

The Nuxt module options are configured under directusConfig:

A missing default file is valid and resolves to an empty shared configuration.

When a config source is discovered, the module adds its path to Nuxt's generated Node TypeScript project. This keeps ambient declarations from tools such as Varlock available in directus.config.ts when it is opened in an IDE.

Public API

@onderwijsin/nuxt-directus-config/config exports:

• defineDirectusConfig(config) — strict identity helper that preserves concrete field selections and mapper return types.
• validateDirectusConfig(config) — validates unknown input and returns ResolvedDirectusConfig.
• getResolvedDirectusConfigFromSource(rootDir, configFile) — loads and validates a consumer source during Nuxt module dependency discovery.
• applyOverridesToCollectionConfig(collections, overrides, property) — merges module-specific collection overrides while preserving unrelated collection behavior.
• DirectusConfig and ResolvedDirectusConfig types.

@onderwijsin/nuxt-directus-config/schema exports the source-of-truth Zod schemas, their inferred option types, UserFieldSelection, supportedDirectusCommands, getPublicSchema, and the resolved-config helpers used by related modules. Fields marked .sensitive() are automatically removed by getPublicSchema(); do not maintain a separate client-side sanitizer.

Compatibility

Requires Nuxt 4 and Node.js 24 or newer. Node.js 22 may work but is untested and unsupported.