Getting Started

WordPress Setup

Configure WordPress for WPNuxt

Don't have a WordPress site yet? See Local Development for setting one up locally.

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.

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

Step 2: Configure WPGraphQL Settings

In WordPress Admin → GraphQL → Settings, configure:

Setting	Value	Why
GraphQL Endpoint	`/graphql`	Default, matches WPNuxt config
Enable Introspection	Yes	WPNuxt downloads your schema at build time to generate TypeScript types — without introspection enabled, `pnpm nuxt prepare` fails with a schema download error
Public Introspection	Yes	Required during development so WPNuxt can download the schema without authentication

Disable Public Introspection in production if your schema contains sensitive information. In that case, set downloadSchema: false and commit schema.graphql to your repository.

Permalinks: WPNuxt's URI-based composables (usePostByUri, useNodeByUri) require "pretty" permalinks. Go to Settings → Permalinks and select Post name or any non-plain structure. With "Plain" permalinks, WordPress returns no URI paths and these composables return null. See Troubleshooting for more details.

CORS: If WordPress and Nuxt run on different origins (common in local dev, e.g. WordPress on port 8080 and Nuxt on port 3000), you need to configure allowed origins in GraphQL → Settings → CORS. Add your Nuxt development URL to the allowed origins list. See Troubleshooting for details.

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.

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

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

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.

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

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

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

See the Authentication Guide for detailed setup instructions.

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

Plugin	Required For	Install Link
WPGraphQL	All WPNuxt projects	WordPress plugin directory
WPGraphQL Content Blocks	`@wpnuxt/blocks` only	GitHub releases
Headless Login for WPGraphQL	`@wpnuxt/auth` only	GitHub releases

Edit this pageorReport an issue

Installation

Get WPNuxt running in 2 minutes

Quick Start Tutorial