|
| 1 | +export const metadata = { |
| 2 | + title: "Migrate From WPGraphQL Gutenberg", |
| 3 | + description: |
| 4 | + "Migrate from wp-graphql-gutenberg to wp-graphql-content-blocks. This guide covers differences between the two plugins, reasons for migration, and step-by-step instructions for updating your GraphQL queries and block structures to ensure compatibility with Faust.js and modern WPGraphQL best practices.", |
| 5 | +}; |
| 6 | + |
| 7 | +With [`wp-graphql-gutenberg`](https://github.com/pristas-peter/wp-graphql-gutenberg) being sunset you may find yourself needing to move to the improved [`wp-graphql-content-blocks`](https://github.com/wpengine/wp-graphql-content-blocks) plugin. |
| 8 | + |
| 9 | +## What's the difference? |
| 10 | + |
| 11 | +Both plugins extend WPGraphQL to add support for blocks (aka. Gutenberg) to the WPGraphQL schema. |
| 12 | + |
| 13 | +However, there are some key differences that you should be aware of: |
| 14 | + |
| 15 | +- WPGraphQL Gutenberg gets the blocks registry and sends it in a network request to the WordPress PHP application. So it needs to be synced from time to time. |
| 16 | + |
| 17 | +- It also allows the blocks to be served as JSON using the `blocksJSON` field. If requesting data this way, the data is not typechecked and you may overfetch data as a side effect. |
| 18 | + |
| 19 | +- Block attributes are using their own types, containing different type for deprecated versions. For example: |
| 20 | + |
| 21 | +```gql |
| 22 | +...on CoreParagraphBlock { |
| 23 | + attributes { |
| 24 | + ...on CoreParagraphBlockAttributes { |
| 25 | + content |
| 26 | + } |
| 27 | + ...on CoreParagraphBlockDeprecatedV1Attributes { |
| 28 | + content |
| 29 | + } |
| 30 | + } |
| 31 | +} |
| 32 | +``` |
| 33 | + |
| 34 | +- It does not allow blocks to be returned as a flat list so you have to use deeply nested queries to get the list of innerBlocks (and this won’t nearly solve the issue 100%). |
| 35 | + |
| 36 | +- wp-graphql-content-blocks does not save anything in the database (this is actually a good thing) compared to wp-graphql-gutenberg. Therefore it only supports previews when the **“preview”** button is hit in the editor. |
| 37 | + |
| 38 | +## How do I migrate a block from wp-graphql-gutenberg? |
| 39 | + |
| 40 | +To answer this question you will have check how you queried the blocks using `wp-graphql-gutenberg`. There are two different cases that you have to consider here: |
| 41 | + |
| 42 | +### You used the `blocksJSON` property to get the blocks data |
| 43 | + |
| 44 | +The `wp-graphql-content-blocks` plugin does not expose the `blocksJSON` fields, because it is problematic to do so. Getting the data as plain JSON directly from the database completely overrides the principles of GraphQL and ignores the type safety of the system. If one of the properties is altered, you have no guarantee that the GraphQL server will catch them. Plus, most of the times you will over fetch data leading to slower queries, especially if you have lots of content on the screen. |
| 45 | + |
| 46 | +So, due to the lack of Introspection, unpredictability, and in order to promote best practices, `wp-graphql-content-blocks` do not expose the block data as plain JSON. Instead, it is recommended to use GraphQL types to retrieve associated block attributes and fields.The effort required to add block fragments is not high. If you follow the recommended approach of co-located fragments, you may add them as properties to each of your block expected attribute list and make sure that you include those into the page query string. |
| 47 | + |
| 48 | +Take a look at the following example taken from [WebDevStudios nextjs-wordpress-starter](https://github.com/WebDevStudios/nextjs-wordpress-starter/blob/main/components/blocks/core/BlockCode/BlockCode.js). It shows an implementation of the `CoreCode` block using `wp-graphql-gutenberg` and getting the data using `blockJSON`. |
| 49 | + |
| 50 | +With it, you would have to create a fragment like this: |
| 51 | + |
| 52 | +```gql |
| 53 | +CoreCode.fragments = { |
| 54 | + key: `CoreCodeBlockFragment`, |
| 55 | + entry: gql` |
| 56 | + fragment CoreCodeBlockFragment on CoreCodeBlock { |
| 57 | + attributes { |
| 58 | + ...on CoreCodeBlockAttributes { |
| 59 | + anchor |
| 60 | + backgroundColor |
| 61 | + content |
| 62 | + className |
| 63 | + gradient |
| 64 | + style |
| 65 | + textColor |
| 66 | + } |
| 67 | + } |
| 68 | + } |
| 69 | + `, |
| 70 | +}; |
| 71 | +``` |
| 72 | + |
| 73 | +Based on the [creating a custom block](/docs/how-to/custom-blocks/) guide from the WordPress Core Blocks you just need to add the following fragment as a new property: |
| 74 | + |
| 75 | +```gql CoreCode.fragments = { |
| 76 | + key: `CoreCodeBlockFragment`, |
| 77 | + entry: gql` |
| 78 | + fragment CoreCodeBlockFragment on CoreCode { |
| 79 | + attributes { |
| 80 | + anchor |
| 81 | + backgroundColor |
| 82 | + content |
| 83 | + className |
| 84 | + gradient |
| 85 | + style |
| 86 | + textColor |
| 87 | + } |
| 88 | + } |
| 89 | + `, |
| 90 | +}; |
| 91 | +``` |
| 92 | + |
| 93 | +When the `WordPressBlocksViewer` renders the component, it passes the whole block data as a property of that block. If your block is designed to accept different properties for attributes and for `innerBlocks` you have to create a wrapper to forward the properties into the right slots: |
| 94 | + |
| 95 | +```js title="CoreCode.js" |
| 96 | +export default function CoreCode({attributes, children}) { |
| 97 | + const BlockCode = dynamic(() => import('@/components/blocks/core/BlockCode')) |
| 98 | + return <BlockCode {...attributes} innerBlocks={children}> |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +### You used the block field with GraphQL types and fragments |
| 103 | + |
| 104 | +If you were using the block field from the `wp-graphql-gutenberg` then most of the component fragment queries should be the same with the following exceptions. |
| 105 | + |
| 106 | +You should be querying the block attributes without qualifying their type: |
| 107 | + |
| 108 | +**Before:** |
| 109 | + |
| 110 | +```gql |
| 111 | +...on CoreParagraphBlock { |
| 112 | + attributes { |
| 113 | + ...on CoreParagraphBlockAttributes { |
| 114 | + content |
| 115 | + } |
| 116 | + } |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +**After:** |
| 121 | + |
| 122 | +```gql |
| 123 | +...on CoreParagraphBlock { |
| 124 | + attributes { |
| 125 | + content |
| 126 | + } |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +There are no separate fields `previewBlocks` and `previewBlocksJSON`. If you want to preview posts or pages you should be setting the `asPreview` boolean to `true` for the post/page in your GraphQL request (this is how Faust.js previews work under the hood). |
| 131 | + |
| 132 | +The base interface for each block contains different fields, so you need to make sure your queries use the valid ones from this list: |
| 133 | + |
| 134 | +- `renderedHTML`: It’s the HTML of the block as rendered by the render_block function. |
| 135 | + |
| 136 | +- `name`: The actual name of the block taken from its block.json spec. |
| 137 | + |
| 138 | +- `__typename`: The type of block transformed from the name field in camel-case notation. |
| 139 | + |
| 140 | +- `apiVersion`: The apiVersion of the block taken from its block.json spec. |
| 141 | + |
| 142 | +- `innerBlocks`: The `innerblock` list of that block. |
| 143 | + |
| 144 | +-`isDynamic`: Whether the block is dynamic or not, taken from its block.json spec. |
| 145 | + |
| 146 | +- `clientId`, `parentClientId`: Unique identifiers for the block and the parent of the block. |
0 commit comments