WP Engine's Headless WordPress Framework provides a set of tools to make building front-end applications with WordPress as the headless CMS a pleasant experience for both developers and publishers. This framework consists of a WordPress plugin, a set of npm packages, and guides to get you started building headless WordPress sites in Next.js.
🚧 Note: This project is in the early stages of development
Eager to try out the Headless Framework? Here's how you can get started:
- Create a new Next.js app from our getting-started project:
npx create-next-app -e https://github.com/wpengine/headless-framework/tree/canary --example-path examples/getting-started --use-npm cd my-app && cp .env.local.sample .env.localto create a file that contains your environment variables.npm run devto start the development server.- See your site at http://localhost:3000.
The sample app loads WordPress content from our demo site at https://headlessfw.wpengine.com.
Point it to your own WordPress site instead:
- Create a WordPress site if you haven't already. We recommend Local to try things out locally, or you can use a live WordPress site.
- Download, upload, and activate the
wpe-headlessplugin. (Plugin Download) - Install WP GraphQL on the WordPress site if it's not already installed.
Then, in your front-end app directory:
- Change
NEXT_PUBLIC_WORDPRESS_URLin.env.localto the full URL to your WordPress site, including thehttp://orhttps://prefix. - Change
WP_HEADLESS_SECRETin.env.localto the secret key found at Settings → Headless in your WordPress admin area. npm run dev(kill and restart npm if it was already running)
You'll see the same site with your WordPress posts instead of ours.
To enable post previews, set your front-end app URL on the WordPress Settings → Headless page (for example, http://localhost:3000 when testing locally).
➡️ Learn more about getting started
- Headless post previewing
- OAuth token authentication creation
- Preview and draft link rewrites in WP Admin to redirect to the front-end
- Smart content redirects
- Automatically redirects content from the WP site to the front-end site to minimize site visitors’ confusion and avoid SEO penalties for duplicate content
- Redirects hyperlinks inserted into posts’ content to the front-end site
- Disable WP theme admin pages
- Prevents access to admin pages that have no effect on the headless front-end appearance, such as Appearance → Themes.
- Ability to define custom menus in a GUI
- Additional data exposed through WPGraphQL
- Block stylesheets
- Post previewing integration
- Auth handler that exchanges a code for an access token
- A
HeadlessProvidercomponent to ease communication with WordPress via Apollo and WPGraphQL. - A TemplateLoader component that optionally allows you to follow the WordPress template hierarchy pattern in Next.js
- Load page templates based on the current URL path and page type
- Utilize functions like
getPropsMiddlewarefor adding to/manipulating data depending on the template
- Display WordPress menus with our
Menucomponent - React hooks for pulling data from WordPress
- “Sensible defaults” for Next.js props and paths
There are two key parts of the WordPress Headless Framework. To take full advantage, you will need to install the plugin in addition to the npm package.
After downloading the zip linked above, we recommend installing by Manually Uploading via WordPress Admin.
yarn add @wpengine/headlessnpm install --save @wpengine/headless- Getting started with the Headless Framework
- Enabling post previews in Next.js
- Using the WordPress template hieararchy in Next.js
Since we're in the early stages of development, we are not currently accepting outside contributions; although, we are interested in any problems that you encounter while using the framework.
As this repository contains a WordPress plugin as well as npm packages, we have a few recommendations to help streamline your development process.
- npm packages in this repository are MIT licensed
- WordPress plugins in this repository are GPLv2+ licensed