---
title: "Configuration"
description: "All WPNuxt configuration options"
canonical_url: "https://wpnuxt.com/reference/configuration"
---
# Configuration

> All WPNuxt configuration options

## @wpnuxt/core

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wpnuxt/core'],

  wpNuxt: {
    // Options here
  }
})
```

### Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        wordpressUrl
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      <strong>
        Required.
      </strong>
      
       WordPress URL (no trailing slash)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        graphqlEndpoint
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '/graphql'
      </code>
    </td>
    
    <td>
      GraphQL endpoint path
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        downloadSchema
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Download schema on build
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schemaAuthToken
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Bearer token for authenticated schema introspection
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        replaceLinks
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Intercept internal links in <code>
        <WPContent>
      </code>
      
       for client-side navigation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        imageRelativePaths
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Convert featured image URLs to relative paths
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        debug
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Enable debug logging
    </td>
  </tr>
</tbody>
</table>

**replaceLinks** — When enabled, clicks on `<a>` tags pointing to your WordPress domain inside `<WPContent>` are intercepted and handled via `navigateTo()` instead of full page reloads. Can be overridden per-instance with the `:replace-links` prop. Disable globally if you handle link routing yourself.

**imageRelativePaths** — When enabled, a `relativePath` property is added to `featuredImage.node` by stripping the WordPress domain from `sourceUrl`. Set to `true` when using relative image paths with Nuxt Image or a proxy. Leave `false` (default) for SSG or external image providers (Vercel, Cloudflare) that need full URLs.

**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.

**schemaAuthToken** — A Bearer token sent with build-time requests to your WordPress GraphQL endpoint: the introspection check and the schema download. Required when **Public Introspection** is disabled in WPGraphQL. The token is only used at build time and is never included in client bundles. Can also be set via the `WPNUXT_SCHEMA_AUTH_TOKEN` environment variable (recommended for CI/CD). See [WordPress Setup](https://wpnuxt.com/getting-started/wordpress-setup#securing-introspection) for details.

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

### Query Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        queries.extendFolder
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        'extend/queries/'
      </code>
    </td>
    
    <td>
      Custom queries location
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        queries.mergedOutputFolder
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '.queries/'
      </code>
    </td>
    
    <td>
      Merged queries output
    </td>
  </tr>
</tbody>
</table>

### Cache Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        cache.enabled
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Enable server-side caching
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cache.maxAge
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        300
      </code>
    </td>
    
    <td>
      Cache duration (seconds)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cache.swr
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Stale-while-revalidate
    </td>
  </tr>
</tbody>
</table>

**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

```ts [nuxt.config.ts]
wpNuxt: {
  wordpressUrl: 'https://wordpress.example.com',
  graphqlEndpoint: '/graphql',
  downloadSchema: true,
  replaceLinks: true,
  imageRelativePaths: false,
  debug: false,
  queries: {
    extendFolder: 'extend/queries/',
    mergedOutputFolder: '.queries/'
  },
  cache: {
    enabled: true,
    maxAge: 300,
    swr: true
  }
}
```

## @wpnuxt/blocks

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wpnuxt/core', '@wpnuxt/blocks'],

  wpNuxtBlocks: {
    // Options here
  }
})
```

### Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        imageDomains
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      <code>
        []
      </code>
    </td>
    
    <td>
      Domains for NuxtImg optimization
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skipPluginCheck
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Skip WPGraphQL Content Blocks plugin validation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        nuxtUI
      </code>
    </td>
    
    <td>
      <code>
        'auto' | boolean
      </code>
    </td>
    
    <td>
      <code>
        'auto'
      </code>
    </td>
    
    <td>
      Use Nuxt UI components when available
    </td>
  </tr>
</tbody>
</table>

**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

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

## @wpnuxt/auth

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wpnuxt/core', '@wpnuxt/auth'],

  wpNuxtAuth: {
    // Options here
  }
})
```

### Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        enabled
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Enable the auth module
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cookieName
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        'wpnuxt-auth-token'
      </code>
    </td>
    
    <td>
      Cookie name for auth token
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refreshCookieName
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        'wpnuxt-refresh-token'
      </code>
    </td>
    
    <td>
      Cookie name for refresh token
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tokenMaxAge
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        3600
      </code>
    </td>
    
    <td>
      Token expiration (seconds)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refreshTokenMaxAge
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        604800
      </code>
    </td>
    
    <td>
      Refresh token expiration (seconds)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        redirectOnLogin
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '/'
      </code>
    </td>
    
    <td>
      Redirect path after login
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        redirectOnLogout
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '/'
      </code>
    </td>
    
    <td>
      Redirect path after logout
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        loginPage
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '/login'
      </code>
    </td>
    
    <td>
      Login page path
    </td>
  </tr>
</tbody>
</table>

**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

```ts [nuxt.config.ts]
wpNuxtAuth: {
  providers: {
    password: {
      enabled: true  // Default: true
    }
  }
}
```

#### Headless Login (External OAuth)

Uses [Headless Login for WPGraphQL](https://github.com/AxeWP/wp-graphql-headless-login) plugin.

```ts [nuxt.config.ts]
wpNuxtAuth: {
  providers: {
    headlessLogin: {
      enabled: true  // Default: false
    }
  }
}
```

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

#### WordPress OAuth (miniOrange)

Uses [miniOrange WP OAuth Server](https://wordpress.org/plugins/miniorange-oauth-20-server/) plugin.

```ts [nuxt.config.ts]
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

```ts [nuxt.config.ts]
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 }
  }
}
```

## Hooks

### `wpnuxt:queries:folders`

For Nuxt module authors: contribute additional GraphQL query folders to WPNuxt's merged queries (this is how `@wpnuxt/blocks` adds its block fragments).

`@wpnuxt/core` calls this hook at `modules:done`, so you can register it during your module's `setup()` regardless of module order in `nuxt.config.ts`. Push absolute folder paths; `.gql`/`.graphql` files are copied recursively into the merged output folder.

```ts [my-module.ts]
export default defineNuxtModule({
  setup(options, nuxt) {
    const { resolve } = createResolver(import.meta.url)
    nuxt.hook('wpnuxt:queries:folders', (folders) => {
      folders.push(resolve('./runtime/queries'))
    })
  }
})
```

Merge precedence (later wins): core defaults → CPT auto-generation → contributed folders → user `extend/queries/`. A contributed `Post.fragment.gql` overrides the default fragment, while users can still override contributed fragments from their `extend/queries/` folder.

<note>

Contributed folders are intended for **fragments**. Contributed queries are passed to nuxt-graphql-middleware, but they do not get generated `use*()` composables.

</note>

## Environment Variables

### @wpnuxt/core

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Overrides
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        WPNUXT_WORDPRESS_URL
      </code>
    </td>
    
    <td>
      <code>
        wordpressUrl
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WPNUXT_GRAPHQL_ENDPOINT
      </code>
    </td>
    
    <td>
      <code>
        graphqlEndpoint
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WPNUXT_DOWNLOAD_SCHEMA
      </code>
    </td>
    
    <td>
      <code>
        downloadSchema
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WPNUXT_SCHEMA_AUTH_TOKEN
      </code>
    </td>
    
    <td>
      <code>
        schemaAuthToken
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WPNUXT_DEBUG
      </code>
    </td>
    
    <td>
      <code>
        debug
      </code>
    </td>
  </tr>
</tbody>
</table>

### @wpnuxt/auth

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Overrides
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        WPNUXT_OAUTH_CLIENT_ID
      </code>
    </td>
    
    <td>
      <code>
        providers.oauth.clientId
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WPNUXT_OAUTH_CLIENT_SECRET
      </code>
    </td>
    
    <td>
      <code>
        providers.oauth.clientSecret
      </code>
    </td>
  </tr>
</tbody>
</table>

Environment variables take precedence over `nuxt.config.ts`.

```bash [.env]
WPNUXT_WORDPRESS_URL=https://wordpress.example.com
WPNUXT_DEBUG=true

# For authenticated schema introspection (when public introspection is disabled)
WPNUXT_SCHEMA_AUTH_TOKEN=your-wpgraphql-token

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


## Sitemap

See the full [sitemap](https://wpnuxt.com/sitemap.md) for all pages.