Skip to content

WordPress Plugin: Decoupled (headless) support


Some sites use WordPress as an API and render the front-end separately using frameworks such as Next.js or Gatsby. On such a site, you are responsible for:

  • Loading the tracking script on your front-end. Please refer to the documentation on how to add it.
  • Rendering the metadata that will be crawled by

The wp-parsely plugin can be used to provide the metadata and provides integrations with the REST API and WPGraphQL.


The plugin automatically adds a parsely field to REST API endpoints corresponding to the Tracked Post Types and Tracked Page Types selected in the plugin settings. By default, this would be the /wp-json/wp/v2/pages and /wp-json/wp/v2/posts endpoints along with the corresponding single resource endpoints. This choice of objects types can be further adjusted by using the wp_parsely_rest_object_types filter:

// Disable REST API output from pages, but enable for term archives.
	function( $object_types ) {
		$object_types = array_diff( $object_types, array( 'page' ) );
		$object_types[] = 'term';
		return $object_types;

The parsely field contains the following fields:

  • version, which is a string identifying the version of the REST API output; this will be updated if changes are made to the output, so consuming applications can check against it.
  • meta, which is an array of metadata for the specific post, page, or other custom post type.
  • rendered, which is the rendered HTML of the metadata for the post, page, or other custom post type. This will be a JSON-LD <script> tag, or a set of <meta> tags, depending on the format selected in the plugin settings. The decoupled code can consume and use this directly, instead of building the values from the meta field values.

The rendered field is a convenience field containing the HTML-formatted metadata which can be printed to a decoupled page as is. This can be disabled by returning false from the wp_parsely_enable_rest_rendered_support filter.

// Disable rendered field output from the REST API output.
add_filter( 'wp_parsely_enable_rest_rendered_support', '__return_false' );

The REST API integration can be disabled by returning false from the wp_parsely_enable_rest_api_support filter.

// Disable all REST API output from the plugin.
add_filter( 'wp_parsely_enable_rest_api_support', '__return_false' );


If the WPGraphQL plugin is installed, the wp-parsely plugin will register a parsely field on the ContentNode interface, which makes it available on most post types by default.

Here is an example GraphQL query for a post. Documentation for each field is provided via the GraphQL schema.

query PostWithMetadata {
  id: 1
 ) {
  parsely {
   rawJsonLd:jsonLd(removeWrappingTag: true)

The GraphQL integration can be disabled by returning false from the wp_parsely_enable_graphql_support filter.

// Disable all GraphQL output from the plugin.
add_filter( 'wp_parsely_enable_graphql_support', '__return_false' );

Last updated: December 28, 2022