---
title: "Local Development"
description: "Set up a local WordPress environment for your WPNuxt project"
canonical_url: "https://wpnuxt.com/guide/local-development"
---
# Local Development

> Set up a local WordPress environment for your WPNuxt project

To develop your WPNuxt project locally, you need a WordPress installation with WPGraphQL. Here are your options.

## Quick Comparison

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Best For
    </th>
    
    <th>
      Requires Docker?
    </th>
    
    <th>
      Setup Time
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="#option-1-wordpress-playground-recommended">
        WordPress Playground
      </a>
    </td>
    
    <td>
      Quick start, no installation needed
    </td>
    
    <td>
      No
    </td>
    
    <td>
      ~1 min
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#option-2-localwp">
        LocalWP
      </a>
    </td>
    
    <td>
      Persistent local environment with GUI
    </td>
    
    <td>
      No
    </td>
    
    <td>
      ~5 min
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#option-3-wp-env-docker">
        wp-env
      </a>
    </td>
    
    <td>
      CI/CD, reproducible environments
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      ~10 min
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#option-4-existing-wordpress">
        Existing WordPress
      </a>
    </td>
    
    <td>
      Teams with a staging site already running
    </td>
    
    <td>
      No
    </td>
    
    <td>
      ~2 min
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#demo-wordpress">
        Demo instance
      </a>
    </td>
    
    <td>
      Quick exploration, no WordPress needed
    </td>
    
    <td>
      No
    </td>
    
    <td>
      0 min
    </td>
  </tr>
</tbody>
</table>

## Option 1: WordPress Playground (Recommended)

The WPNuxt starter template includes a [WordPress Playground](https://developer.wordpress.org/playground/) blueprint that launches a fully configured WordPress instance in your browser — no server, no Docker, no installation.

### Setup

1. Create a project with the starter template (if you haven't already):```bash
npm create wpnuxt@latest
```
2. Start the dev server with WordPress Playground:```bash
pnpm dev:blueprint
```

This starts a WordPress Playground with WPGraphQL, sample content (posts, pages, menus, images), and pretty permalinks — then launches the Nuxt dev server pointed at it.

### What's Included

The blueprint configures WordPress with:

- WPGraphQL plugin (activated)
- Pretty permalinks (`/%postname%/`)
- Sample blog posts, pages, and a navigation menu
- Public introspection enabled

### Limitations

- Data may not persist between sessions — treat it as a disposable environment
- Not suitable for testing WordPress plugins or custom themes
- Runs in Node.js via WebAssembly, not a full PHP/MySQL environment

<callout type="tip">

WordPress Playground is ideal for development and testing. For persistent content, use LocalWP or an existing WordPress installation.

</callout>

## Option 2: LocalWP

[LocalWP](https://localwp.com/) is a free, user-friendly app for running WordPress locally.

### Setup

1. Download and install [LocalWP](https://localwp.com/)
2. Click **Create a new site**
3. Choose a site name (e.g., "my-wpnuxt-site")
4. Use the default PHP/MySQL settings
5. Set your admin credentials

### Install Required Plugins

In your LocalWP site's WordPress admin:

1. Go to **Plugins → Add New**
2. Search for and install **WPGraphQL**
3. Activate the plugin

For Gutenberg blocks support, also install:

- [WPGraphQL Content Blocks](https://github.com/wpengine/wp-graphql-content-blocks) (download from GitHub)

For authentication (`@wpnuxt/auth`):

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

### Connect to Nuxt

Find your site URL in LocalWP (e.g., `http://my-wpnuxt-site.local`) and add it to your `.env`:

```bash [.env]
WPNUXT_WORDPRESS_URL=http://my-wpnuxt-site.local
```

## Option 3: wp-env (Docker)

[wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) is WordPress's official Docker-based local environment.

### Requirements

- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- Node.js 20+

### Setup

1. Install wp-env globally:```bash
npm install -g @wordpress/env
```
2. Create `.wp-env.json` in your project root:```json
{
  "plugins": [
    "https://downloads.wordpress.org/plugin/wp-graphql.zip",
    "https://github.com/wpengine/wp-graphql-content-blocks/releases/latest/download/wp-graphql-content-blocks.zip"
  ],
  "port": 8080
}
```
3. Start WordPress:```bash
wp-env start
```
4. Access WordPress admin at `http://localhost:8080/wp-admin`
  - **Username:** `admin`
  - **Password:** `password`
5. Add to your `.env`:```bash
WPNUXT_WORDPRESS_URL=http://localhost:8080
```

### wp-env Commands

```bash
wp-env start      # Start WordPress
wp-env stop       # Stop WordPress
wp-env destroy    # Remove environment (start fresh)
```

## Option 4: Existing WordPress

You can also use any existing WordPress installation (local or remote).

### Requirements

1. Install and activate [WPGraphQL](https://wordpress.org/plugins/wp-graphql/)
2. Enable introspection in **GraphQL → Settings**
3. Ensure the GraphQL endpoint is accessible from your dev machine

### Connect

```bash [.env]
WPNUXT_WORDPRESS_URL=https://your-wordpress-site.com
```

<callout type="tip">

For remote development, consider using a staging site rather than production.

</callout>

## Testing Your Setup

After configuring WordPress, verify it works:

1. Visit `{your-wordpress-url}/graphql` - you should see the GraphQL IDE
2. Run this query:
```graphql
{
  posts {
    nodes {
      title
    }
  }
}
```
3. Start your Nuxt dev server:
```bash
pnpm dev
```

## Demo WordPress

Don't have WordPress set up yet? Use our demo instance to get started:

```bash [.env]
WPNUXT_WORDPRESS_URL=https://wordpress.wpnuxt.com
```

This is a read-only demo with sample content, perfect for trying out WPNuxt.

## Related Pages

- **Installation** — Install and configure WPNuxt
- **WordPress Setup** — Configure WordPress for WPNuxt
- **Quick Start** — Build a blog from scratch in 15 minutes


## Sitemap

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