Gutenberg content – fluent-wp-client

Overview

Import fluent-wp-client/blocks when you need Gutenberg-aware workflows. The core client stays lightweight.

Four workflows:

• rendered HTML via content.rendered
• raw content via .getContent()
• block type discovery via wpBlocks.blocks()
• block read/write via blocks().get() and blocks().set()

Setup

import { WordPressClient } from 'fluent-wp-client';
import { withBlocks } from 'fluent-wp-client/blocks';

const wp = new WordPressClient({
  baseUrl: 'https://example.com',
  auth: { username: 'admin', password: 'app-password' },
});

const wpBlocks = withBlocks(wp);

Block type discovery

const availableBlocks = await wpBlocks.blocks().list();
const blockSchemas = await wpBlocks.blocks().schemas();
const paragraph = await wpBlocks.blocks().item('core/paragraph');
const paragraphSchema = await wpBlocks.blocks().schema('core/paragraph');

AI-assisted editing

The block catalog provides live block names, attribute definitions, constraints, and generated JSON Schemas — ideal for AI agents producing block trees.

Rendered content

const post = await wp.content('posts').item('hello-world');
const html = post.content.rendered;

Raw + rendered content

const content = await wp.content('posts').item('hello-world').getContent();
content.rendered // HTML
content.raw      // block markup

Caution

.getContent() requires context=edit — the caller must have edit capabilities.

Authentication Authenticate to access edit context.

Parse blocks

const blocks = await wpBlocks.content('posts').item('hello-world').blocks().get();
// WordPressParsedBlock[] | undefined (undefined if item not found)

Caution

blocks().get() requires context=edit — use an authenticated client.

With validation

const blockSchemas = await wpBlocks.blocks().schemas();
const blocks = await wpBlocks.content('posts').item('hello-world').blocks().get({
  schemas: blockSchemas,
  validate: true,
});

Note

Unknown block names throw WordPressBlockValidationError when validate: true.

Parsed blocks contain blockName, attrs, innerBlocks, innerHTML, innerContent. Whitespace-only freeform nodes are filtered out automatically.

Write blocks

const postQuery = wpBlocks.content('posts').item('hello-world');
const blocks = await postQuery.blocks().get();
const updated = [
  { ...blocks[0]!, innerHTML: '<p>New text.</p>', innerContent: ['<p>New text.</p>'] },
  ...blocks.slice(1),
];
await postQuery.blocks().set(updated);

Validation options

Pattern	What it does
set(blocks)	Structural + round-trip checks only
set(blocks, blockSchemas)	Full catalog validation (names + attributes)
set(blocks, await wpBlocks.blocks().schemas({ namespace: 'core' }))	Namespace-scoped validation
set(blocks, [singleSchema])	Single block type validation
set(blocks, { validate: false })	Skip all validation

set() checks:

• innerContent placeholders match innerBlocks
• block names and attributes match provided schemas
• parent/ancestor constraints
• serialization round-trips cleanly

Note

Without schemas, only structural and round-trip checks run. Block types are never fetched implicitly.

Blocks from list items

List methods return plain DTOs. Use a single-item query for block access:

const posts = await wp.content('posts').list({ perPage: 5 });
const blocks = await wpBlocks.content('posts').item(posts[0].id).blocks().get();

Standalone helpers

When you already have content.raw:

import {
  createWordPressBlockJsonSchemas,
  parseWordPressBlocks,
  serializeWordPressBlocks,
  validateWordPressBlocks,
} from 'fluent-wp-client/blocks';

const blocks = await parseWordPressBlocks(rawContent);
const serialized = serializeWordPressBlocks(blocks);

Zod schema for block trees

import { parsedBlockSchema } from 'fluent-wp-client/blocks/zod';
const blockTree = z.array(parsedBlockSchema).parse(aiOutput);

Capabilities

• .item() — context=view, public access
• .getContent(), .blocks().get(), .blocks().set() — context=edit, requires edit capabilities
• wpBlocks.blocks() — requires authenticated user with block type management access
• Missing auth/capabilities throw WordPressHttpError or WordPressAuthError