Turning WordPress into a Headless CMS isn't straightforward, so grab a cup of ☕️ because following these steps will take ~20 minutes.

The following instructions assume you'll be standing up a fresh local install of WordPress.

Requirements​

Make sure you have the following dependencies:

• Composer
• Gravity Forms
• Local WP (or Docker or VVV or whatever you prefer as a WordPress development tool)

WordPress Setup​

Step 1: Install WordPress​

Create a new WordPress install. We recommend the following settings:

• Either NGINX or Apache
• PHP 7.4+
• MySQL 5.7+
• Enable SSL certificate

Step 2: Install Plugins and Theme​

Now that you've got a local WordPress install, it's time to turn it into a Headless CMS!

1. In your terminal, change directories to your new WordPress install's/wp-content directory, then download ourcomposer.json.

curl -O https://raw.githubusercontent.com/WebDevStudios/nextjs-wordpress-starter/main/backend/composer.json

2. Install free plugins and the theme:

composerinstall

3. Install premium plugin:Gravity Forms.

4. Activate all plugins and theme in the WP Dashboard or useWP CLI:

wp plugin activate --all

wp theme activate wds-headless-theme

Step 3: Configurewp-config.php​

The follow constants needs to be inwp-config.php:

define( 'HEADLESS_FRONTEND_URL', 'http://localhost:3000/' );
define( 'PREVIEW_SECRET_TOKEN', 'ANY_RANDOM_STRING');
define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'ANY_RANDOM_STRING' );

To generate a random strings, we recommend using theWordPress Salt Generator. Just copy and paste any of the generated strings into the constants above.

Learn more about setting upwp-config.php.

Step 4: Create Pages​

In the WordPress Dashboard, navigate toPages -> Add New

Create three blank pages named:

1. Homepage
2. Blog
3. 404

There's nothing else needed for this step.

Step 5: Set Page Options​

In the WordPress Dashboard, navigate toSettings -> Reading -> "Your homepage displays" and set static pages for Homepage and Posts page:

Now navigate toSettings -> Headless Config -> Custom Page Options and set the custom 404 page:

You should now see your Homepage, Blog, and 404 page like so:

Step 6: Set Permalinks​

In the WordPress Dashboard, navigate toSettings -> Permalinks

1. Select theDay and name structure:

/%year%/%monthnum%/%day%/%postname%/

2. Save the settings.

Step 7: Set Menus​

You'll need to create at least one menu,Primary. Additionally, you can create a Mobile and Footer menu. In the WordPress Dashboard, navigate toAppearance -> Menus

1. Menu Name:Primary
2. Display location:Primary Menu
3. Click "Save Menu"
4. Add menu items as needed

Plugins Setup​

Update Block Registry​

In order for the WP GraphQL Gutenberg plugin to createblockJSON, you'll need to click this button to update the block registry:

GraphQL Gutenberg -> Update

Application Password​

The frontend will need to authenticate with WordPress, we can useApplication Passwords.

1. Users -> Profile -> Scroll to the bottom
2. Enter a name, e.g,nextjs-wordpress-starter
3. Click -> Add New Application Password

Copy and paste the password into a safe location. You will need to add both yourWordPress username and Application password to the.env file for the frontend. Learn more aboutENV Variables.

WP Search with Algolia​

See theWDS Headless Algolia documentation.

Gravity Forms​

See theWDS Headless Gravity Forms documentation.

Enable Previews​

To enable previews, you'll need both aPREVIEW_SECRET_TOKEN constant inwp-config.php andWORDPRESS_PREVIEW_SECRET ENV variable in the frontend.env file.

The token can be any random string, as long as they match in both locations!

WordPress:

// wp-config.php
define('PREVIEW_SECRET_TOKEN', 'ANY_RANDOM_STRING');

Next.js:

// .env
WORDPRESS_PREVIEW_SECRET='ANY_RANDOM_STRING'

Next Steps​

Now that WordPress is ready, head on over and set up theFrontend to continue.