WordPress Setup

Follow these steps to prepare your WordPress site for WPNuxt.

Step 1: Install WPGraphQL (Required)

WordPress doesn't expose a GraphQL API by default. WPGraphQL adds one, which WPNuxt uses to fetch your content with type safety and auto-generated composables.

1. In WordPress Admin, go to Plugins → Add New
2. Search for WPGraphQL or download it here
3. Click Install Now, then Activate

Step 2: Configure WPGraphQL Settings

In WordPress Admin → GraphQL → Settings, configure:

Step 3: Install WPGraphQL Content Blocks (Optional)

The standard GraphQL API returns post content as a single HTML string. This plugin exposes individual Gutenberg blocks as structured data, so @wpnuxt/blocks can render each block with its own Vue component.

Required only if you use @wpnuxt/blocks to render Gutenberg blocks as Vue components.

1. Download from WPGraphQL Content Blocks
2. In WordPress Admin, go to Plugins → Add New → Upload Plugin
3. Upload the zip file and click Activate

This exposes block data in the GraphQL schema so @wpnuxt/blocks can render them.

Step 4: Install Headless Login for WPGraphQL (Optional)

WordPress authentication uses cookies tied to the WordPress domain. This plugin adds JWT-based authentication to WPGraphQL, enabling login flows from your Nuxt frontend.

Required only if you use @wpnuxt/auth for WordPress authentication.

1. Download from Headless Login for WPGraphQL
2. In WordPress Admin, go to Plugins → Add New → Upload Plugin
3. Upload the zip file and click Activate

After installation, configure providers in WordPress Admin → GraphQL → Headless Login:

1. Enable the Password provider for username/password authentication
2. Optionally configure OAuth providers (Google, GitHub, etc.) for social login

See the Authentication Guide for detailed setup instructions.

Securing Introspection

By default, WPGraphQL exposes the schema publicly. This is fine during development, but in production you may want to disable Public Introspection to hide your schema from unauthenticated users.

WPNuxt supports authenticated schema introspection via the schemaAuthToken option. When configured, WPNuxt sends the token as a Bearer header during build-time operations (endpoint validation and schema download), allowing introspection to work without public access.

Setup

1. In WordPress Admin, go to GraphQL → Settings
2. Keep Enable Introspection set to Yes
3. Set Public Introspection to No
4. Generate an application password or authentication token for a WordPress user with sufficient permissions
5. Add the token to your environment:

WPNUXT_SCHEMA_AUTH_TOKEN=your-auth-token

Or set it directly in nuxt.config.ts:

wpNuxt: {
  wordpressUrl: 'https://wordpress.example.com',
  schemaAuthToken: process.env.WPNUXT_SCHEMA_AUTH_TOKEN
}

Verify Your Setup

Visit https://your-site.com/graphql in a browser. You should see the GraphQL IDE.

Try this query:

{
  posts {
    nodes {
      title
    }
  }
}

If you see your posts, WordPress is ready. Continue to Installation.

Summary