WPNuxt

https://wpnuxt.com/
Admin
WPNuxt connects WordPress to Nuxt 4 via GraphQL, providing type-safe composables for fetching...
Tokens:53,380
Snippets:660
Trust Score:5.8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Run Nuxt Development Server

Source: https://wpnuxt.com/getting-started/installation

Start the Nuxt development server to verify the WPNuxt installation.

```bash
pnpm dev

```

--------------------------------

### Install @wpnuxt/auth

Source: https://wpnuxt.com/auth

Install the authentication module using pnpm.

```bash
pnpm add @wpnuxt/auth

```

--------------------------------

### Start Local Development Server with Blueprint

Source: https://wpnuxt.com/getting-started/installation

This command starts a local WordPress Playground with sample content and launches the Nuxt dev server.

```bash
pnpm dev:blueprint

```

--------------------------------

### Full @wpnuxt/core Configuration Example

Source: https://wpnuxt.com/reference/configuration

An extensive example demonstrating all available configuration options for the @wpnuxt/core module, including WordPress URL, GraphQL endpoint, schema download, link replacement, image paths, debugging, query settings, and cache parameters.

```typescript
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
  }
}
```

--------------------------------

### Install @wpnuxt/blocks with npm

Source: https://wpnuxt.com/guide/rendering-blocks

Install the `@wpnuxt/blocks` package using npm.

```bash
npm install @wpnuxt/blocks

```

--------------------------------

### Create Nuxt Project

Source: https://wpnuxt.com/getting-started/quick-start

Initialize a new Nuxt project and install dependencies.

```bash
npx nuxi@latest init my-wpnuxt-blog
cd my-wpnuxt-blog
pnpm install

```

--------------------------------

### Install Headless Login for WPGraphQL

Source: https://wpnuxt.com/auth/password

Install the Headless Login plugin for WPGraphQL using Composer.

```bash
composer require developer/wp-graphql-headless-login
```

--------------------------------

### Install wp-env Globally

Source: https://wpnuxt.com/guide/local-development

Install the WordPress environment tool globally to manage local WordPress installations via Docker.

```bash
npm install -g @wordpress/env

```

--------------------------------

### Install and Run WPNuxt MCP Server Locally

Source: https://wpnuxt.com/ai

Instructions to install dependencies and run the WPNuxt MCP server locally for development. Configure your MCP client to connect to the local server.

```bash
cd docs
pnpm install
pnpm dev

```

--------------------------------

### Start wp-env WordPress Environment

Source: https://wpnuxt.com/guide/local-development

Use this command to start the Dockerized WordPress environment configured by .wp-env.json.

```bash
wp-env start

```

--------------------------------

### Install @wpnuxt/blocks with pnpm

Source: https://wpnuxt.com/guide/rendering-blocks

Install the `@wpnuxt/blocks` package using pnpm.

```bash
pnpm add @wpnuxt/blocks

```

--------------------------------

### Install WPNuxt CLI Globally

Source: https://wpnuxt.com/reference/cli

Installs the WPNuxt CLI globally on your system using npm.

```bash
npm install -g wpnuxi

```

--------------------------------

### Setup WPNuxt Auth Module

Source: https://wpnuxt.com/reference/configuration

Basic setup for the WPNuxt authentication module, including core modules and auth-specific configuration.

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

  wpNuxtAuth: {
    // Options here
  }
})

```

--------------------------------

### Netlify CLI Deploy Commands

Source: https://wpnuxt.com/deploy/other-platforms

Commands to install the Netlify CLI, link your project, and deploy to production.

```bash
# Install Netlify CLI
npm i -g netlify-cli

# Link to your site
netlify link

# Deploy
netlify deploy --build --prod

```

--------------------------------

### Install @nuxtjs/sitemap Module

Source: https://wpnuxt.com/guide/seo

Install the `@nuxtjs/sitemap` module using pnpm to enable sitemap generation for your Nuxt project.

```bash
pnpm add -D @nuxtjs/sitemap

```

--------------------------------

### Installing Nuxt Image Module

Source: https://wpnuxt.com/guide/images

Install the `@nuxt/image` module as a dependency if you plan to use Nuxt Image standalone, without the `@wpnuxt/blocks` module.

```bash
pnpm add @nuxt/image

```

--------------------------------

### Minimal WPNuxt Setup

Source: https://wpnuxt.com/guide/examples

Configures WPNuxt using only the core module without any UI framework. This setup requires specifying the WordPress URL in the nuxt.config.ts file.

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

  wpNuxt: {
    wordpressUrl: 'https://your-wordpress.com',
  },
})


```

--------------------------------

### Nuxt Image Configuration for Production

Source: https://wpnuxt.com/guide/images

Configuration example for setting up an image provider (Cloudflare) in nuxt.config.ts for production image optimization.

```javascript
export default defineNuxtConfig({
  image: {
    provider: 'cloudflare',
    cloudflare: {
      baseURL: 'https://your-site.com'
    }
  }
})

```

--------------------------------

### Full WPNuxt Auth Configuration Example

Source: https://wpnuxt.com/reference/configuration

Comprehensive configuration for the WPNuxt auth module, including token management, redirects, and all provider settings.

```typescript
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 }
  }
}

```

--------------------------------

### Run WPNuxt CLI Command

Source: https://wpnuxt.com/reference/cli

Executes a WPNuxt CLI command without a global installation using npx.

```bash
npx wpnuxi <command>

```

--------------------------------

### Headless Login Plugin Not Detected Error

Source: https://wpnuxt.com/reference/troubleshooting

The `@wpnuxt/auth` module requires the 'Headless Login for WPGraphQL' plugin, but it's not installed or activated. Install the plugin, configure authentication providers, and run 'pnpm dev:prepare' to refresh the GraphQL schema.

```text
[WPNuxt Auth] Headless Login for WPGraphQL plugin not detected.

The @wpnuxt/auth module requires this WordPress plugin for authentication.
Your WordPress GraphQL schema is missing the required 'login' mutation.

To fix this:
1. Install the plugin: https://github.com/AxeWP/wp-graphql-headless-login
2. Configure at least one authentication provider in WordPress
3. Run 'pnpm dev:prepare' to refresh the GraphQL schema

```

--------------------------------

### Responsive Image with NuxtImg

Source: https://wpnuxt.com/guide/images

Example of using the NuxtImg component with 'sizes' and 'loading' attributes for responsive image loading and optimization.

```vue
<NuxtImg
  :src="imageUrl"
  sizes="sm:100vw md:50vw lg:800px"
  loading="lazy"
  placeholder
/>

```

--------------------------------

### Get Sample Content

Source: https://wpnuxt.com/ai/tools

The `wp_sample_content` tool provides sample content for development and testing. You can specify the `contentType` and `count` of items to retrieve.

```bash
wp_sample_content --contentType=page --count=5
```

```bash
wp_sample_content
```

--------------------------------

### Setup Navigation Menus

Source: https://wpnuxt.com/ai/tools

Generates navigation menu components for desktop, mobile, and submenus. Specify a menu name or let it auto-detect. Optionally use Nuxt UI components.

```javascript
wpnuxt_setup_menus({
  menuName: 'main-menu',
  includeNuxtUI: true
})
```

--------------------------------

### Configure @wpnuxt/core Module

Source: https://wpnuxt.com/reference/configuration

Basic setup for the @wpnuxt/core module in nuxt.config.ts. Add the module and configure core options.

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

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

--------------------------------

### Client-Only Fetching with usePosts

Source: https://wpnuxt.com/reference/composables

Example of how to use `usePosts` to fetch data only on the client side by setting `server: false`.

```javascript
// Client-only
usePosts(undefined, { server: false })
```

--------------------------------

### GraphQL Query to Verify WordPress Setup

Source: https://wpnuxt.com/getting-started/wordpress-setup

Use this GraphQL query to test your WordPress GraphQL endpoint and confirm it's ready for WPNuxt.

```graphql
{
  posts {
    nodes {
      title
    }
  }
}

```

--------------------------------

### Add WPNuxt Core to Existing Nuxt Project with npm

Source: https://wpnuxt.com/getting-started/installation

Install the WPNuxt core package into an existing Nuxt project using npm.

```bash
npm install @wpnuxt/core

```

--------------------------------

### Watching Reactive Values for Refetching

Source: https://wpnuxt.com/reference/composables

An alternative to reactive parameters, this example shows how to use the `watch` option to refetch data when specific reactive values change.

```javascript
// Watch reactive value (alternative to reactive params)
const category = ref('news')
usePosts({ categoryName: category }, { watch: [category] })
```

--------------------------------

### Add WPNuxt Core to Existing Nuxt Project with pnpm

Source: https://wpnuxt.com/getting-started/installation

Install the WPNuxt core package into an existing Nuxt project using pnpm.

```bash
pnpm add @wpnuxt/core

```

--------------------------------

### Generate WPNuxt Project

Source: https://wpnuxt.com/ai/tools

The `wpnuxt_init` command generates a complete WPNuxt project based on WordPress site analysis. It accepts parameters for project name, package manager, and optional features like Nuxt UI, page generation, component generation, menu setup, and query generation.

```bash
wpnuxt_init --projectName=my-wpnuxt-app --packageManager=yarn --includeNuxtUI=false --generatePages=false
```

```bash
wpnuxt_init --projectName=another-app
```

--------------------------------

### Fetching Previous and Next Posts

Source: https://wpnuxt.com/reference/composables

Example of using `usePrevNextPost` to retrieve the slugs, URIs, and titles of the previous and next posts relative to a given slug.

```javascript
const { prev, next } = await usePrevNextPost('my-post-slug')
// prev/next contain: { slug, uri, title }
```

--------------------------------

### wp_sample_content

Source: https://wpnuxt.com/ai/tools

Get sample content for development and testing. Allows specifying content type and count. Returns sample content items with full data structure.

```APIDOC
## wp_sample_content

### Description
Get sample content for development and testing.

### Parameters
#### Query Parameters
- **contentType** (string) - No - Content type to sample (default: `post`)
- **count** (number) - No - Number of items (1-10, default 3)

### Returns
Sample content items with full data structure.
```

--------------------------------

### Using NuxtImg with Standalone Configuration

Source: https://wpnuxt.com/guide/images

Render optimized images using the `<NuxtImg>` component when using the standalone `@nuxt/image` configuration. This example demonstrates lazy loading and specifying dimensions.

```vue
<script setup lang="ts">
const { data: post } = await usePostByUri({ uri: '/hello-world/' })
</script>

<template>
  <NuxtImg
    :src="post?.featuredImage?.node?.sourceUrl"
    :alt="post?.featuredImage?.node?.altText"
    width="800"
    height="600"
    loading="lazy"
  />
</template>

```

--------------------------------

### Production Configuration for Image Optimization and Serving

Source: https://wpnuxt.com/guide/images

Combine proxy route rules with the Nuxt Image module configuration for production. This setup ensures same-origin image serving and leverages Nuxt Image for optimization, responsive sizes, and lazy loading.

```typescript
export default defineNuxtConfig ({
  modules: ['@wpnuxt/core', '@nuxt/image'],

  // Proxy WordPress uploads through your domain
  routeRules: {
    '/wp-content/**': {
      proxy: 'https://your-wordpress.com/wp-content/**'
    }
  },

  // Allow NuxtImg to optimize images from your domain
  image: {
    domains: ['your-wordpress.com']
  }
})

```

--------------------------------

### Generate Blog Listing Page Component

Source: https://wpnuxt.com/ai

Example of a WPNuxt page component generated by an AI assistant to display a blog listing. It fetches posts and renders excerpts.

```vue
<script setup lang="ts">
const { data: posts } = await usePosts()

useHead({ title: 'Blog' })
</script>

<template>
  <div>
    <h1>Blog</h1>
    <article v-for="post in posts" :key="post.id">
      <NuxtLink :to="post.uri">
        <h2>{{ post.title }}</h2>
      </NuxtLink>
      <div v-sanitize-html="post.excerpt" />
    </article>
  </div>
</template>


```

--------------------------------

### Pre-render WordPress Routes with `prerender:routes` Hook

Source: https://wpnuxt.com/deploy/ssg

Fetch all WordPress posts and pages using a GraphQL query within the `prerender:routes` hook to ensure all content is included in the static site generation. This example demonstrates fetching routes and adding them to the context's routes set.

```typescript
const WORDPRESS_URL = 'https://your-wordpress.com'
const GRAPHQL_ENDPOINT = '/graphql'

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

  nitro: {
    preset: 'static',
    prerender: {
      concurrency: 10,
      interval: 1000,
      failOnError: false,
      routes: ['/'],
    },
  },

  hooks: {
    async 'prerender:routes'(ctx) {
      await fetchWordPressRoutes(ctx.routes)
    },
  },

  wpNuxt: {
    wordpressUrl: WORDPRESS_URL,
  },
})

async function fetchWordPressRoutes(routes: Set<string>) {
  console.log('[wpnuxt] Fetching WordPress routes for prerendering...')

  try {
    const response = await fetch(`${WORDPRESS_URL}${GRAPHQL_ENDPOINT}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        query: `
          query AllContentForPrerender {
            posts(first: 100) { nodes { uri } }
            pages(first: 100) { nodes { uri } }
          }
        `,
      }),
    })

    const data = await response.json() as {
      data?: {
        posts?: { nodes: Array<{ uri: string }> }
        pages?: { nodes: Array<{ uri: string }> }
      }
    }

    const posts = data.data?.posts?.nodes || []
    const pages = data.data?.pages?.nodes || []

    for (const post of posts) {
      if (post.uri) routes.add(post.uri)
    }
    for (const page of pages) {
      if (page.uri) routes.add(page.uri)
    }

    console.log(`[wpnuxt] Added ${posts.length} posts and ${pages.length} pages`)
  } catch (error) {
    console.warn('[wpnuxt] Failed to fetch WordPress routes:', error)
  }
}

```

--------------------------------

### Initialize New WPNuxt Project

Source: https://wpnuxt.com/reference/cli

Scaffolds a new WPNuxt project from the starter template. If no directory is provided, it will prompt for project details.

```bash
npx wpnuxi init [directory]

```

--------------------------------

### Create WPNuxt Project with npm

Source: https://wpnuxt.com/getting-started/installation

Use this command to quickly set up a new WPNuxt project with npm.

```bash
npm create wpnuxt@latest

```

--------------------------------

### Create WPNuxt Project with Bun

Source: https://wpnuxt.com/getting-started/installation

Use this command to quickly set up a new WPNuxt project with Bun.

```bash
bun create wpnuxt@latest

```

--------------------------------

### Prepare Development Environment

Source: https://wpnuxt.com/migration/v1-to-v2

If you encounter the 'Cannot find module '#wpnuxt'' error, run this command to prepare your development environment.

```bash
pnpm dev:prepare
```

--------------------------------

### Create WPNuxt Project with Yarn

Source: https://wpnuxt.com/getting-started/installation

Use this command to quickly set up a new WPNuxt project with Yarn.

```bash
yarn create wpnuxt@latest

```

--------------------------------

### Create WPNuxt Project with pnpm

Source: https://wpnuxt.com/getting-started/installation

Use this command to quickly set up a new WPNuxt project with pnpm.

```bash
pnpm create wpnuxt@latest

```

--------------------------------

### Self-Hosted Build and Run

Source: https://wpnuxt.com/deploy/other-platforms

Build the WPNuxt project and run the server locally, setting the WordPress URL.

```bash
pnpm build
WPNUXT_WORDPRESS_URL=https://your-wordpress-site.com node .output/server/index.mjs

```

--------------------------------

### wpnuxt_setup_menus

Source: https://wpnuxt.com/ai/tools

Generates navigation menu components for desktop and mobile, including dropdown submenus.

```APIDOC
## wpnuxt_setup_menus

### Description
Generate navigation menu components.

### Parameters
#### Query Parameters
- **menuName** (string) - Optional - Specific menu to generate for
- **includeNuxtUI** (boolean) - Optional - Use Nuxt UI components (default: auto-detect)

### Returns
Menu components with:
  * Desktop navigation
  * Mobile navigation
  * Dropdown submenus
```

--------------------------------

### Interactive Query Options Demo

Source: https://wpnuxt.com/guide/examples

Demonstrates how to use the `usePosts` composable with various query options like lazy, server, immediate, and clientCache. This helps understand their impact on data fetching behavior.

```javascript
const { data: posts, pending, refresh, status } = usePosts(
  {},
  {
    lazy: options.value.lazy,
    server: options.value.server,
    immediate: options.value.immediate,
    clientCache: options.value.clientCache,
  }
)


```

--------------------------------

### wpnuxt_list_composables

Source: https://wpnuxt.com/ai/tools

Lists all available WPNuxt composables for the project, including naming conventions and usage examples.

```APIDOC
## wpnuxt_list_composables

### Description
List WPNuxt composables available for the project.

### Parameters
None

### Returns
Available composables with:
  * Default composables (`usePosts`, `usePages`, `useMenu`, etc.)
  * Naming convention explanation
  * Usage examples
```

--------------------------------

### Initialize WPNuxt Project in Specific Directory

Source: https://wpnuxt.com/reference/cli

Scaffolds a new WPNuxt project in a specified directory and automatically initializes git.

```bash
npx wpnuxi init my-blog

```

--------------------------------

### Cloudflare Pages Wrangler Deploy Command

Source: https://wpnuxt.com/deploy/other-platforms

Commands to install Wrangler, build the project, and deploy to Cloudflare Pages.

```bash
# Install wrangler
npm i -g wrangler

# Build the project
pnpm build

# Deploy
wrangler pages deploy .output/public

```

--------------------------------

### Authentication Flow Overview

Source: https://wpnuxt.com/auth

Illustrates the step-by-step process of user authentication, token handling, and session management in WPNuxt.

```text
1. User submits credentials
   └─→ login() sends GraphQL mutation to WordPress

2. WordPress validates credentials
   └─→ Returns JWT auth token + refresh token

3. WPNuxt stores tokens
   └─→ Both stored in httpOnly cookies (not accessible to JavaScript)

4. Subsequent GraphQL requests
   └─→ Auth token included automatically via cookies

5. Auth token expires (default: 1 hour)
   └─→ Refresh token silently fetches a new auth token

6. Refresh token expires (default: 7 days)
   └─→ User must log in again

```

--------------------------------

### Custom Retry Delay

Source: https://wpnuxt.com/reference/composables

Example of configuring a custom delay between retries for failed requests using `retryDelay` in `usePosts`.

```javascript
// Custom retry delay
usePosts(undefined, { retry: 3, retryDelay: 2000 })
```

--------------------------------

### Basic App Layout

Source: https://wpnuxt.com/getting-started/quick-start

Set up the main application layout with a container for content.

```vue
<template>
  <div class="container">
    <NuxtPage />
  </div>
</template>

<style>
.container {
  max-width: 800px;
  margin: 0 auto;
  padding: 2rem;
}
</style>

```

--------------------------------

### Custom CoreParagraph Component

Source: https://wpnuxt.com/reference/block-components

Example of overriding the default CoreParagraph component to apply custom styling and content handling.

```vue
<script setup lang="ts">
import type { CoreParagraph } from '#wpnuxt/blocks'

defineProps<{ block: CoreParagraph }>()
</script>

<template>
  <p class="my-custom-paragraph">
    <span v-sanitize-html="block?.attributes?.content" />
  </p>
</template>
```

--------------------------------

### wpnuxt_init

Source: https://wpnuxt.com/ai/tools

Generate a complete WPNuxt project based on WordPress site analysis. Accepts project name and various options for package manager, UI inclusion, and component generation. Returns complete project files.

```APIDOC
## wpnuxt_init

### Description
Generate a complete WPNuxt project based on WordPress site analysis.

### Parameters
#### Path Parameters
- **projectName** (string) - Yes - Project folder name
- **packageManager** (string) - No - `pnpm`, `npm`, `yarn`, or `bun` (default: `pnpm`)
- **includeNuxtUI** (boolean) - No - Include Nuxt UI v4 (default: `true`)
- **generatePages** (boolean) - No - Generate page components (default: `true`)
- **generateComponents** (boolean) - No - Generate content components (default: `true`)
- **setupMenus** (boolean) - No - Generate menu components (default: `true`)
- **generateQueries** (boolean) - No - Generate GraphQL queries (default: `true`)

### Returns
Complete project files including:
  * `nuxt.config.ts`
  * `package.json`
  * `app.vue`
  * Default layout
  * Home page
  * Environment files
```

--------------------------------

### CoreHeading Component Output

Source: https://wpnuxt.com/reference/block-components

Example of a heading block (h2) rendered with an anchor ID and custom CSS class.

```html
<h2 id="anchor" class="custom-class">
  Heading text
</h2>
```

--------------------------------

### CoreParagraph Component Output

Source: https://wpnuxt.com/reference/block-components

Example of how a paragraph block is rendered, including support for anchors, CSS classes, and inline styles.

```html
<p id="anchor" class="custom-class" style="...">
  Content here
</p>
```

--------------------------------

### Fetch Multiple Menus

Source: https://wpnuxt.com/guide/menus

Demonstrates how to fetch different menus, such as a main menu and a footer menu, concurrently using `useMenu` for different parts of the website.

```vue
<script setup lang="ts">
const { data: mainMenu } = await useMenu({ name: 'main' })
const { data: footerMenu } = await useMenu({ name: 'footer' })
</script>

```

--------------------------------

### GraphQL Data Structure for Editor Blocks

Source: https://wpnuxt.com/guide/rendering-blocks

This is the structure of the data returned from GraphQL when @wpnuxt/blocks is installed, showing how editor blocks are represented.

```json
{
  "page": {
    "title": "About Us",
    "editorBlocks": [
      {
        "name": "core/heading",
        "attributes": {
          "level": 2,
          "content": "Our Story"
        }
      },
      {
        "name": "core/paragraph",
        "attributes": {
          "content": "We started building headless WordPress sites in 2023..."
        }
      },
      {
        "name": "core/image",
        "attributes": {
          "url": "https://your-site.com/wp-content/uploads/team.jpg",
          "alt": "Our team",
          "caption": "The team behind WPNuxt"
        }
      },
      {
        "name": "core/buttons",
        "innerBlocks": [
          {
            "name": "core/button",
            "attributes": {
              "text": "Contact Us",
              "url": "/contact"
            }
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Update Package Installation

Source: https://wpnuxt.com/migration/v1-to-v2

Update the WPNuxt core package to version 2.x. This command replaces the older version with the new one.

```bash
- pnpm add @wpnuxt/core@^1.0.0
+ pnpm add @wpnuxt/core@^2.0.0
```

--------------------------------

### Transforming Response Data

Source: https://wpnuxt.com/reference/composables

Example of using the `transform` option in `usePosts` to modify the fetched data, in this case, mapping to an array of titles.

```javascript
// Transform
usePosts(undefined, {
  transform: (posts) => posts?.map(p => p.title)
})
```

--------------------------------

### Display WPNuxt Environment and Project Info

Source: https://wpnuxt.com/reference/cli

Shows detailed environment and project information, useful for debugging and reporting issues.

```bash
npx wpnuxi info

```

--------------------------------

### Custom CoreCode Block Component

Source: https://wpnuxt.com/reference/block-components

Example of creating a custom component for a 'core/code' block to render preformatted code with language highlighting.

```vue
<script setup lang="ts">
defineProps<{ block: { attributes?: { content?: string, language?: string } } }>()
</script>

<template>
  <pre><code :class="`language-${block.attributes?.language}`">{{ block.attributes?.content }}</code></pre>
</template>
```

--------------------------------

### Configuring Data Fetching Options

Source: https://wpnuxt.com/guide/fetching-data

Illustrates various options for controlling data fetching behavior, including lazy loading, client-side fetching, immediate execution, and watch sources for refetching.

```javascript
const { data } = usePosts(variables, {
  lazy: true,        // Non-blocking navigation, show loading state
  server: false,     // Skip SSR, fetch on client only
  immediate: false,  // Don't fetch until execute() is called
  watch: [slug],     // Refetch when slug changes
})

```

--------------------------------

### CoreButton Component Output (without Nuxt UI)

Source: https://wpnuxt.com/reference/block-components

Example of a button rendered as a native anchor element when Nuxt UI is not available.

```html
<a href="/page" class="wp-block-button__link">
  Click me
</a>
```

--------------------------------

### Complete SEO-Optimized Blog Post Page

Source: https://wpnuxt.com/guide/seo

This script sets up meta tags, canonical URLs, and JSON-LD structured data for a blog post. It fetches post data, computes SEO-relevant fields, and utilizes `useSeoMeta` and `useHead` for optimal search engine indexing.

```vue
<script setup lang="ts">
const route = useRoute()
const config = useRuntimeConfig()
const siteUrl = config.public.siteUrl || ''

const { data: post } = await useNodeByUri({ uri: route.path })

const title = computed(() => post.value?.title || '')
const description = computed(() =>
  post.value?.excerpt?.replace(/<[^>]+>/g, '').trim() || ''
)
const imageUrl = computed(() =>
  post.value?.featuredImage?.node?.sourceUrl || ''
)

// Meta tags
useSeoMeta({
  title: title.value,
  description: description.value,
  ogTitle: title.value,
  ogDescription: description.value,
  ogImage: imageUrl.value,
  ogUrl: `${siteUrl}${route.path}`,
  ogType: 'article',
  articlePublishedTime: post.value?.date,
  twitterCard: 'summary_large_image',
})

// Canonical URL
useHead({
  title: title.value,
  link: [{ rel: 'canonical', href: `${siteUrl}${route.path}` }],
  script: [
    {
      type: 'application/ld+json',
      innerHTML: JSON.stringify({
        '@context': 'https://schema.org',
        '@type': 'BlogPosting',
        headline: title.value,
        description: description.value,
        image: imageUrl.value,
        datePublished: post.value?.date,
        dateModified: post.value?.modified,
        author: {
          '@type': 'Person',
          name: post.value?.author?.node?.name,
        },
        publisher: {
          '@type': 'Organization',
          name: config.public.siteName || 'My Site',
        },
      }),
    },
  ],
})
</script>


```

--------------------------------

### CoreButton Component Output (with Nuxt UI)

Source: https://wpnuxt.com/reference/block-components

Example of a button rendered using Nuxt UI's UButton component when available.

```html
<UButton to="/page" variant="solid" size="md">
  Click me
</UButton>
```

--------------------------------

### Fetching Data with Parameters

Source: https://wpnuxt.com/guide/fetching-data

Demonstrates fetching specific content using various parameters like URI, ID, category name, and custom ordering. Use these for targeted data retrieval.

```javascript
// By URI
const { data: post } = await usePostByUri({ uri: '/my-post' })

// By ID
const { data: page } = await usePageById({ id: '123' })

// With variables
const { data: posts } = await usePostsByCategoryName({
  categoryName: 'news'
})

// Custom ordering (defaults: DATE / DESC)
const { data: sorted } = await usePosts({ orderField: 'TITLE', order: 'ASC' })

```

--------------------------------

### Home Page with Post List

Source: https://wpnuxt.com/getting-started/quick-start

Create the home page to fetch and display a list of recent blog posts using the usePosts composable.

```vue
<script setup lang="ts">
// Fetch the 10 most recent posts
const { data: posts } = await usePosts({ first: 10 })
</script>

<template>
  <div>
    <h1>My Blog</h1>

    <div v-if="posts?.length">
      <article v-for="post in posts" :key="post.id">
        <h2>
          <NuxtLink :to="post.uri">
            {{ post.title }}
          </NuxtLink>
        </h2>
        <p>{{ post.date }}</p>
        <div v-sanitize-html="post.excerpt" />
      </article>
    </div>

    <p v-else>No posts found.</p>
  </div>
</template>

<style scoped>
article {
  margin-bottom: 2rem;
  padding-bottom: 2rem;
  border-bottom: 1px solid #eee;
}

h2 {
  margin-bottom: 0.5rem;
}

h2 a {
  color: inherit;
  text-decoration: none;
}

h2 a:hover {
  text-decoration: underline;
}
</style>

```

--------------------------------

### Add WPNuxt Core to Existing Nuxt Project with Yarn

Source: https://wpnuxt.com/getting-started/installation

Install the WPNuxt core package into an existing Nuxt project using Yarn.

```bash
yarn add @wpnuxt/core

```

--------------------------------

### Generate Types with Nuxt Prepare

Source: https://wpnuxt.com/getting-started/quick-start

Run the Nuxt prepare command to download the GraphQL schema and generate types for WPNuxt.

```bash
pnpm nuxt prepare

```

--------------------------------

### OAuth-Only Login Configuration

Source: https://wpnuxt.com/auth/oauth

Configure Nuxt.js to disable password authentication and enable OAuth authentication. This setup is for scenarios where only OAuth login is desired.

```typescript
wpNuxtAuth: {
  providers: {
    password: { enabled: false },
    oauth: {
      enabled: true,
      clientId: 'your-client-id',
      clientSecret: 'your-client-secret'
    }
  }
}

```

--------------------------------

### Connect to WordPress Site

Source: https://wpnuxt.com/ai/prompts

Use this prompt to connect to a WordPress site, list content types, show menus, detect plugins, and list WPNuxt composables. Requires a WordPress site URL.

```text
Use the connect-wordpress prompt with https://wordpress.wpnuxt.com
```

--------------------------------

### WPNuxt Architecture Overview

Source: https://wpnuxt.com/getting-started/how-it-works

Illustrates the data flow from WordPress content to the Nuxt frontend via WPGraphQL and WPNuxt.

```text
WordPress (CMS) → WPGraphQL (API) → WPNuxt (bridge) → Nuxt (frontend)
```

--------------------------------

### Manual Execution of usePosts

Source: https://wpnuxt.com/reference/composables

Demonstrates how to manually trigger data fetching using the `execute` function returned by `usePosts` when `immediate: false` is set.

```javascript
// Manual execution
const { execute } = usePosts(undefined, { immediate: false })
await execute()
```

--------------------------------

### Set WordPress URL Environment Variable

Source: https://wpnuxt.com/deploy/ssg

Set the `WPNUXT_WORDPRESS_URL` environment variable in your CI/CD environment. This example shows configuration for GitHub Actions.

```shell
# GitHub Actions example
env:
  WPNUXT_WORDPRESS_URL: https://your-wordpress.com

```

--------------------------------

### Displaying WordPress Image Directly

Source: https://wpnuxt.com/guide/images

Use this approach for simple setups or prototyping when image optimization is not a concern. It directly uses the WordPress image URL.

```vue
<script setup lang="ts">
const { data: post } = await usePostByUri({ uri: '/hello-world/' })
const imageUrl = post.value?.featuredImage?.node?.sourceUrl
</script>

<template>
  <img :src="imageUrl" :alt="post?.featuredImage?.node?.altText" />
</template>

```

--------------------------------

### Basic Data Fetching with usePosts

Source: https://wpnuxt.com/guide/fetching-data

Fetches posts and displays them, showing loading and error states. This is the default and recommended way for critical content.

```vue
<script setup lang="ts">
const { data: posts, pending, error } = await usePosts()
</script>

<template>
  <div v-if="pending">Loading...</div>
  <div v-else-if="error">{{ error.message }}</div>
  <article v-for="post in posts" :key="post.id">
    <h2>{{ post.title }}</h2>
  </article>
</template>

```

--------------------------------

### useGeneralSettings

Source: https://wpnuxt.com/reference/composables

Fetches general site settings.

```APIDOC
## useGeneralSettings

### Description
Fetches the general settings of the WordPress site, such as the site title, description, and URL.

### Method Signature
`useGeneralSettings(options?)
`

### Parameters
#### Options
- `lazy` (`boolean`) - Optional - If true, does not block navigation. Defaults to `false`.
- `server` (`boolean`) - Optional - Fetch during Server-Side Rendering. Defaults to `true`.
- `immediate` (`boolean`) - Optional - Fetch immediately upon component mount. Defaults to `true`.

### Return Value
Similar to `usePosts`, returns `data`, `pending`, `error`, `status`, `refresh`, `execute`, and `clear`.

### Examples
```javascript
// Fetch general site settings
useGeneralSettings()
```
```

--------------------------------

### Detect WordPress Plugins

Source: https://wpnuxt.com/ai/tools

The `wp_detect_plugins` tool analyzes the GraphQL schema to identify installed WordPress plugins. It requires no parameters and returns a list of detected plugins.

```bash
wp_detect_plugins
```

--------------------------------

### Test Webhook Revalidation Endpoint

Source: https://wpnuxt.com/guide/caching

Send a POST request to the revalidation endpoint with the correct secret to test if the server cache is being purged. This example uses curl.

```bash
curl -X POST https://your-site.com/api/_wpnuxt/revalidate \
  -H 'Content-Type: application/json' \
  -d '{"secret":"your-secret"}'

# Expected: {"success":true,"purged":0,"vercelPurged":true}
# Wrong secret: 401

```

--------------------------------

### OAuth Scopes Configuration

Source: https://wpnuxt.com/auth/oauth

Define the scopes for OAuth authentication to control the user information requested from the provider. This example requests openid, profile, and email scopes.

```javascript
oauth: {
  scopes: ['openid', 'profile', 'email']
}

```

--------------------------------

### Fetch Menu by Different ID Types

Source: https://wpnuxt.com/guide/menus

Demonstrates fetching a menu using its name (default), slug, or database ID. Ensure the `idType` matches the provided `name`.

```javascript
// By name (default)
const { data } = await useMenu({ name: 'main' })

// By slug
const { data } = await useMenu({ name: 'main-menu', idType: 'SLUG' })

// By database ID
const { data } = await useMenu({ name: '5', idType: 'DATABASE_ID' })

```

--------------------------------

### Component for Displaying Featured Image (Simplified)

Source: https://wpnuxt.com/guide/images

A simplified component script setup to access featured image data directly from the post object and display it using NuxtImg.

```vue
<script setup lang="ts">
const { data: post } = await usePostByUri({ uri: route.path })

const featuredImage = computed(() => post.value?.featuredImage?.node)
</script>

<template>
  <NuxtImg
    v-if="featuredImage"
    :src="featuredImage.sourceUrl"
    :alt="featuredImage.altText"
    :width="featuredImage.mediaDetails?.width"
    :height="featuredImage.mediaDetails?.height"
  />
</template>

```

--------------------------------

### List WPNuxt Composables

Source: https://wpnuxt.com/ai/tools

Lists all available WPNuxt composables for the project, including default composables like `usePosts` and `usePages`, along with naming conventions and usage examples.

```javascript
wpnuxt_list_composables()
```

--------------------------------

### Configure WordPress OAuth Provider

Source: https://wpnuxt.com/reference/configuration

Set up the WordPress OAuth provider using miniOrange, including client credentials and endpoint overrides.

```typescript
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']
    }
  }
}

```

--------------------------------

### Using NuxtImg with @wpnuxt/blocks

Source: https://wpnuxt.com/guide/images

When using `@wpnuxt/blocks`, the `CoreImage` block component automatically utilizes `<NuxtImg>` for optimized image delivery. This example shows direct usage of `<NuxtImg>`.

```vue
<NuxtImg
  src="https://your-wordpress.com/wp-content/uploads/photo.jpg"
  alt="Description"
  width="800"
  height="600"
/>

```

--------------------------------

### Netlify Deployment Configuration

Source: https://wpnuxt.com/deploy/ssg

Configure Netlify for building and publishing your static Nuxt site.

```toml
[build]
  command = "pnpm run build"
  publish = ".output/public"

```

--------------------------------

### Dockerfile for WPNuxt

Source: https://wpnuxt.com/deploy/other-platforms

A multi-stage Dockerfile to build and run WPNuxt, optimizing for a small final image size.

```dockerfile
# Build stage
FROM node:20-alpine AS build

RUN corepack enable
WORKDIR /app

COPY package.json pnpm-lock.yaml ./ 
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

# Runtime stage
FROM node:20-alpine

WORKDIR /app
COPY --from=build /app/.output .output

ENV HOST=0.0.0.0
ENV PORT=3000
EXPOSE 3000

CMD ["node", ".output/server/index.mjs"]

```

--------------------------------

### Server Options for Preview Mode

Source: https://wpnuxt.com/guide/preview-mode

Configures WPNuxt server options to forward authentication cookies and headers to WordPress for authenticated GraphQL requests.

```typescript
import { defineGraphqlServerOptions } from 'nuxt-graphql-middleware/server-options'
import { getHeader } from 'h3'

export default defineGraphqlServerOptions({
  async serverFetchOptions(event, _operation, _operationName, _context) {
    return {
      headers: {
        Cookie: getHeader(event, 'cookie') || '',
        Authorization: getHeader(event, 'authorization') || '',
      },
    }
  },
})

```

--------------------------------

### Override getCachedData for Custom Payload Handling

Source: https://wpnuxt.com/guide/caching

Customize how cached data is retrieved during hydration or refetches. This example shows how to always fetch fresh data when a manual refresh is triggered.

```javascript
const { data } = usePosts(undefined, {
  getCachedData: (key, nuxtApp, ctx) => {
    // Always fetch fresh
    if (ctx.cause === 'refresh:manual') {
      return undefined
    }
    // Use cached data
    return nuxtApp.payload.data[key]
  }
})
```

--------------------------------

### Basic Menu Display

Source: https://wpnuxt.com/guide/menus

Fetches a menu named 'main' and displays its items as navigation links. Requires the menu to exist in WordPress.

```vue
<script setup lang="ts">
const { data: menuItems } = await useMenu({ name: 'main' })
</script>

<template>
  <nav v-if="menuItems?.length">
    <NuxtLink
      v-for="item in menuItems"
      :key="item.uri"
      :to="item.uri"
    >
      {{ item.label }}
    </NuxtLink>
  </nav>
</template>

```

--------------------------------

### Single Post/Page Rendering with Catch-All Route

Source: https://wpnuxt.com/guide/examples

Renders any WordPress content by URI using a catch-all route. It supports both Gutenberg blocks and raw HTML content. The `watch` option ensures content refetches when navigating between pages.

```vue
<script setup lang="ts">
const route = useRoute()

const { data: post } = await useNodeByUri(
  { uri: route.path },
  { watch: [() => route.path] }
)
</script>

<template>
  <article v-if="post">
    <h1>{{ post.title }}</h1>

    <!-- Structured blocks (requires @wpnuxt/blocks) -->
    <BlockRenderer
      v-if="post.editorBlocks?.length"
      :node="post"
    />

    <!-- Fallback: raw HTML content -->
    <div
      v-else-if="post.content"
      v-sanitize-html="post.content"
      class="prose prose-lg dark:prose-invert max-w-none"
    />
  </article>
</template>

```
Tokens:
Raw