Headless WordPress settings

February 20, 2025

606 words | 4 min read.

Documentation Setup ACF Headless Woo Headless WordPress Stripe Woocommerce WP Gatsby WPGraphQL

1. Set up required plugins

NOTE: It is recommended to test migrating to this plugin ecosystem using the WordPress Playground and the test configuration file available here. After the initial setup try importing Your current Woo & WP content and settings for any potential compatibility issues. If none exist proceed straight to Woo configuration.

JSON mock files:

– THEME OPTIONS & HERO /wp-setup/acf/acf-export-2025-02-21.json
– MENU OBJECT INPUT /wp-setup/acf/primary-menu-object.json
– MENU OBJECT INPUT II /wp-setup/acf/secondary-menu-object.json

First add the required plugins then activate them in this order, you can get all the required plugins at this page, you can refer to each plugin’s official documentation for more details.

1. WooCommerce
2. WP Gatsby
3. WPGraphQL
4. WPGraphQL WooCommerce
5. WPGraphQL JWT Authentication
6. WPGraphQL for ACF
7. Advanced Custom Fields
8. WooCommerce Stripe Gateway
9. Headless Mods – configures netlify builds
10. WPGraphQL CORS – enables extra layer of security
11. WPGraphQL Smart Cache – note: after setting up the options
12. Mailgun
13. Yoast SEO (not fully covered yet)
14. WPGraphql Yoast Seo (not fully covered yet)

2. Activate Headless Preview Theme

This is a blank starter preview theme for headless websites, it lets You modify the WordPress backend using custom functions and php.

1. You can download the theme here (coming soon…).
2. Download the .zip and import it to Your WordPress
3. Activate the theme
4. You can use the theme file editor to further develop the backend with functions.php

3. Create and set the homepage in reading settings

To work properly the theme needs a homepage set. Make sure You set it.

Also set the backend to be discouraged by search engines, as You don’t want it to be indexed this is fine, as Your frontend gatsby part will rank better for SEO.

It’s a good practice to also set the desired permalinks.

Note: Do not set anything in the WPGatsby settings under Settings > GatsbyJS as this is deprecated. It will be removed in the future update.

4. Configure plugins endpoints and save .env variable’s data

Go to GraphQL settings and configure your GraphQL API endpoint, you could make it encrypted for better security. Refer to the original plugin’s docs for more details.

5. Import ACF JSON

Download our ACF JSON configuration file here.

Import ACF for FSE theme options to edit menus, promobar, hero and other settings you can find the full list here. Some more complex objects like menus, sliders and opinions use custom objects, you can find their definitions here.

Proceed to setting Woocommerce and other configuration options described in this post.

6. Edit `wp-config.php`

It is recommended to set those variables in the file for development best practices and to prevent errors:

// Production wp-config.php for headless setup
define('GRAPHQL_JWT_AUTH_SECRET_KEY','YOUR_SECRET_SALT_KEY');
set_time_limit(300000);
define('GRAPHQL_DEBUG', 'false');
define('WP_DEBUG', false);
define('DISALLOW_FILE_EDIT', false);
define('DISALLOW_FILE_MODS', false);

7. Frontend rebuild options:

The headless plugin and theme provide extra options for automated builds synced with netlify and other tweaks, You can find them at the top under Frontend rebuild label.