---
title: "WordPress Setup"
description: "Configure WordPress for WPNuxt"
canonical_url: "https://wpnuxt.com/getting-started/wordpress-setup"
---
# WordPress Setup

> Configure WordPress for WPNuxt

<callout type="info" icon="i-heroicons-information-circle">

Don't have a WordPress site yet? See [Local Development](https://wpnuxt.com/guide/local-development) for setting one up locally.

</callout>

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](https://www.wpgraphql.com/docs/introduction) 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](https://wordpress.org/plugins/wp-graphql/)
3. Click **Install Now**, then **Activate**

## Step 2: Configure WPGraphQL Settings

In **WordPress Admin → GraphQL → Settings**, configure:

<table>
<thead>
  <tr>
    <th>
      Setting
    </th>
    
    <th>
      Value
    </th>
    
    <th>
      Why
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      GraphQL Endpoint
    </td>
    
    <td>
      <code>
        /graphql
      </code>
    </td>
    
    <td>
      Default, matches WPNuxt config
    </td>
  </tr>
  
  <tr>
    <td>
      Enable Introspection
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Introspection lets WPNuxt query the GraphQL schema itself — discovering all available types, fields, and queries — so it can generate TypeScript types and validate your <code>
        .gql
      </code>
      
       files at build time. Without introspection enabled, <code>
        pnpm nuxt prepare
      </code>
      
       fails with a schema download error
    </td>
  </tr>
  
  <tr>
    <td>
      Public Introspection
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Required during development so WPNuxt can download the schema without authentication
    </td>
  </tr>
</tbody>
</table>

<callout type="warning">

Disable **Public Introspection** in production if your schema contains sensitive information. You have two options:

1. **Recommended:** Set `schemaAuthToken` (or the `WPNUXT_SCHEMA_AUTH_TOKEN` env var) to a WPGraphQL authentication token. WPNuxt sends this as a Bearer token during build-time schema operations, so introspection works without being publicly exposed. See [Securing Introspection](#securing-introspection) below.
2. Set `downloadSchema: false` and commit `schema.graphql` to your repository. You must manually update the schema file whenever your WordPress schema changes.

</callout>

<callout type="info">

**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](https://wpnuxt.com/reference/troubleshooting#wordpress-permalink-structure) for more details.

</callout>

<callout type="info">

**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](https://wpnuxt.com/reference/troubleshooting#cors-errors) for details.

</callout>

## 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](https://github.com/wpengine/wp-graphql-content-blocks/releases)
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](https://github.com/AxeWP/wp-graphql-headless-login/releases)
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](https://wpnuxt.com/auth) 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:

```bash [.env]
WPNUXT_SCHEMA_AUTH_TOKEN=your-auth-token
```

Or set it directly in `nuxt.config.ts`:

```ts [nuxt.config.ts]
wpNuxt: {
  wordpressUrl: 'https://wordpress.example.com',
  schemaAuthToken: process.env.WPNUXT_SCHEMA_AUTH_TOKEN
}
```

<callout type="info">

The `schemaAuthToken` is only used at build time for schema operations. It is never included in client bundles or runtime requests. For runtime authentication, use `@wpnuxt/auth`.

</callout>

## Verify Your Setup

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

Try this query:

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

If you see your posts, WordPress is ready. Continue to [Installation](https://wpnuxt.com/getting-started/installation).

## Summary

<table>
<thead>
  <tr>
    <th>
      Plugin
    </th>
    
    <th>
      Required For
    </th>
    
    <th>
      Install Link
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://wordpress.org/plugins/wp-graphql/" rel="nofollow">
        WPGraphQL
      </a>
    </td>
    
    <td>
      All WPNuxt projects
    </td>
    
    <td>
      WordPress plugin directory
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://github.com/wpengine/wp-graphql-content-blocks" rel="nofollow">
        WPGraphQL Content Blocks
      </a>
    </td>
    
    <td>
      <code>
        @wpnuxt/blocks
      </code>
      
       only
    </td>
    
    <td>
      GitHub releases
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://github.com/AxeWP/wp-graphql-headless-login" rel="nofollow">
        Headless Login for WPGraphQL
      </a>
    </td>
    
    <td>
      <code>
        @wpnuxt/auth
      </code>
      
       only
    </td>
    
    <td>
      GitHub releases
    </td>
  </tr>
</tbody>
</table>


## Sitemap

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