Configuration

@wpnuxt/core

export default defineNuxtConfig({
  modules: ['@wpnuxt/core'],

  wpNuxt: {
    // Options here
  }
})

Options

downloadSchema — WPNuxt downloads your WordPress GraphQL schema at build time to generate TypeScript types and validate queries. Set to false only if you commit schema.graphql to version control and update it manually. If false and no schema file exists, the build fails.

debug — Logs query merging, endpoint validation, module load times, and cache config to the server console. No production performance impact. Useful when composables aren't being generated or the WordPress connection fails.

graphqlEndpoint — Only change this if a security plugin renames your WordPress GraphQL endpoint to something other than /graphql.

Query Options

Cache Options

How enabled and swr interact:

• Both true (default): The first request fetches from WordPress. Subsequent requests serve cached content while a background revalidation runs. Users always get a fast response.
• swr: false: Cached content is served until maxAge expires. The next request after expiry waits for fresh data from WordPress before responding.
• enabled: false: No server-side caching. Every request fetches directly from WordPress. Client-side request deduplication from Nuxt still applies.

maxAge guidance: 300 seconds (5 minutes, the default) works well for content sites. Use 3600 seconds (1 hour) for stable content that rarely changes. Use 60 seconds for frequently-updated content. Setting maxAge: 0 disables the server cache but keeps client-side deduplication.

Full Example

wpNuxt: {
  wordpressUrl: 'https://wordpress.example.com',
  graphqlEndpoint: '/graphql',
  downloadSchema: true,
  debug: false,
  queries: {
    extendFolder: 'extend/queries/',
    mergedOutputFolder: '.queries/'
  },
  cache: {
    enabled: true,
    maxAge: 300,
    swr: true
  }
}

@wpnuxt/blocks

export default defineNuxtConfig({
  modules: ['@wpnuxt/core', '@wpnuxt/blocks'],

  wpNuxtBlocks: {
    // Options here
  }
})

Options

imageDomains — Domain names (without protocol) that <NuxtImg> is allowed to optimize. You must include your WordPress domain here, and any CDN domains that serve your WordPress media. Without this, <NuxtImg> falls back to unoptimized <img> tags.

skipPluginCheck — On startup, WPNuxt checks that the WPGraphQL Content Blocks plugin is installed by inspecting the GraphQL schema. Set to true if this check incorrectly fails (e.g., because you're using a custom schema or the plugin is detected under a different name).

Example

wpNuxtBlocks: {
  imageDomains: ['wordpress.example.com', 'cdn.example.com'],
  skipPluginCheck: false,  // Set to true to skip plugin validation
  nuxtUI: 'auto'           // 'auto' | true | false
}

@wpnuxt/auth

export default defineNuxtConfig({
  modules: ['@wpnuxt/core', '@wpnuxt/auth'],

  wpNuxtAuth: {
    // Options here
  }
})

Options

Token lifecycle: The auth token (default: 1 hour) is included with every GraphQL request. When it expires, the refresh token (default: 7 days) silently fetches a new auth token in the background. When the refresh token expires, the user must log in again.

redirectOnLogin / redirectOnLogout — Set to false to handle navigation yourself in the login/logout handler. This is useful when you want to show a success message before redirecting, or when the redirect target depends on the user's role.

Provider Options

Password Authentication

wpNuxtAuth: {
  providers: {
    password: {
      enabled: true  // Default: true
    }
  }
}

Headless Login (External OAuth)

Uses Headless Login for WPGraphQL plugin.

wpNuxtAuth: {
  providers: {
    headlessLogin: {
      enabled: true  // Default: false
    }
  }
}

Providers (Google, GitHub, etc.) are auto-discovered from WordPress.

WordPress OAuth (miniOrange)

Uses miniOrange WP OAuth Server plugin.

wpNuxtAuth: {
  providers: {
    oauth: {
      enabled: true,
      clientId: process.env.WPNUXT_OAUTH_CLIENT_ID,
      clientSecret: process.env.WPNUXT_OAUTH_CLIENT_SECRET,
      // Optional overrides:
      authorizationEndpoint: '/wp-json/moserver/authorize',
      tokenEndpoint: '/wp-json/moserver/token',
      userInfoEndpoint: '/wp-json/moserver/resource',
      scopes: ['openid', 'profile', 'email']
    }
  }
}

Full Example

wpNuxtAuth: {
  cookieName: 'wpnuxt-auth-token',
  refreshCookieName: 'wpnuxt-refresh-token',
  tokenMaxAge: 3600,
  refreshTokenMaxAge: 604800,
  redirectOnLogin: '/profile',
  redirectOnLogout: '/',
  loginPage: '/login',
  providers: {
    password: { enabled: true },
    headlessLogin: { enabled: true },
    oauth: { enabled: false }
  }
}

Environment Variables

@wpnuxt/core

@wpnuxt/auth

Environment variables take precedence over nuxt.config.ts.

WPNUXT_WORDPRESS_URL=https://wordpress.example.com
WPNUXT_DEBUG=true

# For OAuth (miniOrange)
WPNUXT_OAUTH_CLIENT_ID=your-client-id
WPNUXT_OAUTH_CLIENT_SECRET=your-client-secret