Skip to main content

Backend Setup

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:

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

screenshot of local wp

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 our composer.json.
curl -O https://raw.githubusercontent.com/WebDevStudios/nextjs-wordpress-starter/main/backend/composer.json
  1. Install free plugins and the theme:
composer install

  1. Install premium plugin: Gravity Forms.

  2. Activate all plugins and theme in the WP Dashboard or use WP CLI:

wp plugin activate --all
wp theme activate wds-headless-theme

Step 3: Configure wp-config.php​

The follow constants needs to be in wp-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 the WordPress Salt Generator. Just copy and paste any of the generated strings into the constants above.

Learn more about setting up wp-config.php.

Step 4: Create Pages​

In the WordPress Dashboard, navigate to Pages -> 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 to Settings -> Reading -> "Your homepage displays" and set static pages for Homepage and Posts page:

screenshot

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

screenshot

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

screenshot

In the WordPress Dashboard, navigate to Settings -> Permalinks

  1. Select the Day and name structure:
/%year%/%monthnum%/%day%/%postname%/
  1. Save the settings.

screenshot of saving 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 to Appearance -> Menus

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

screenshot of setting the menu

Plugins Setup​

Update Block Registry​

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

GraphQL Gutenberg -> Update

screenshot of updating graphql gutenberg

Application Password​

The frontend will need to authenticate with WordPress, we can use Application 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 your WordPress username and Application password to the .env file for the frontend. Learn more about ENV Variables.

screenshot of setting application password

WP Search with Algolia​

See the WDS Headless Algolia documentation.

Gravity Forms​

See the WDS Headless Gravity Forms documentation.

Enable Previews​

To enable previews, you'll need both a PREVIEW_SECRET_TOKEN constant in wp-config.php and WORDPRESS_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 the Frontend to continue.