This guide will get you up and running with our Headless Framework and help you understand what it offers.
You should have Node.js installed first.
Our headless framework is built on top of Next.js. You get all the amazing features that Next.js provides, plus an easy way to use it with WordPress!
For this guide, we’ll start with an example project to quickly see the power of our framework. To pull it down, use npx (whcih comes with Node.js) with the URL to our example project:
npx create-next-app -e https://github.com/wpengine/headless-framework/tree/canary --example-path examples/preview --use-npm
create-next-app will prompt you to provide a name for your project. Once you do that and the dependencies are installed, cd into the new project:
cd your-app-name
Create a file to hold your environment variables, such as your WordPress site URL:
cp .env.local.sample .env.local
You don't need to edit .env.local just yet.
Then npm run dev and visit 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)
Open or refresh http://localhost:3000 and you should see a list of posts from your WordPress site at the bottom of the front page, and be able to view a single post.
Install our Headless WordPress plugin to get the full benefits of the framework. We recommend Local to quickly spin up a local WordPress site. Once you have a WordPress site up and running, download the plugin and upload and activate it through the WordPress Admin.
After activation, you will be redirected to the Headless settings page. The plugin has a dependency on WPGraphQL, so you’ll see a button on the right under the “Get Started with Headless” box to install and activate the WPGraphQL plugin if it’s not already active.
At this point, if you know what the URL to your front-end site is (or is going to be), you can enter that now in the Front-end Site URL field. That’s all you need to do for now on the WordPress side!
The plugin ensures that your WordPress site runs smoothly as a headless CMS. From smart content redirects to enabling post previewing to ensuring the right data is available in WPGraphQL, installing the plugin gives you the things you need to run WordPress as a headless CMS. Find a full list of plugin features here.
The example project is set up with most of the features our @wpengine/headless npm package provides, along with a way to structure your app.
We’re using a Next.js Custom App to override the default App in order to inject our <HeadlessProvider /> wrapper component. HeadlessProvider sets up an Apollo client that connects to WordPress via the NEXT_PUBLIC_WORDPRESS_URL environment variable. Our Apollo client is all set up to support both server side and client side rendering out of the box.
In Next.js, pages are used for both rendering and routing purposes. For instance, an about.tsx file would automatically be rendered at /about. In our example, we’re using an optional catch-all route - [[..page]].tsx, which Next.js will hit any time a request is made. This component simply returns a <TemplateLoader /> component. TemplateLoader is imported from the @wpengine/headless npm package and is responsible for determining what template to render based on the requested URL’s content type in WordPress. This allows you to mimic the WordPress template hierarchy inside your Next.js app.
The wp-templates/ folder contains templates that are responsible for the final rendering of a page. They are rendered from the <NextTemplateLoader /> (<TemplateLoader /> if not using Next.js) in the catch-all route page mentioned above, in the same way that WordPress PHP theme files are loaded according to the template hierarchy. This is accomplished by the TemplateLoader picking up what type of WordPress content is sent over from GraphQL. The naming convention of files in the wp-templates/ directory follows 1:1 with the WordPress template hierarchy. For example, single.tsx is the template rendered for single posts, page.tsx is the template for pages, category.tsx is for categories, and so on.
An index.tsx and single.tsx template is included in our example project. To handle other content types like pages or custom types, you can create a new .tsx file with the name of the desired template.
More information about how the TemplateLoader works can be found here.
The @wpengine/headless npm package contains several custom React hooks for interacting with WPGraphQL. In the example project’s index.tsx template, for example, the usePosts hook is used to get a list of all posts. Similarly, usePost is used in single.tsx to get the data for a single post. The hooks permit certain parameters, which allow you to refine the data returned (passing in an id to usePost, for example, to get a certain post).